在 PowerShell 中使用 CmdletBinding 属性

Migel Hewage Nimesha 2023年1月30日 2022年5月31日
  1. PowerShell 中的 CmdletBinding 属性
  2. CmdletBinding 属性与 Verbose 参数一起使用
  3. CmdletBinding 属性与 $PSCmdlet 对象和 SupportsShouldProcess 一起使用
  4. 使用 CmdletBinding 属性和 Parameter 属性来控制函数参数
在 PowerShell 中使用 CmdletBinding 属性

cmdlet 是在 PowerShell 环境中执行单一功能的轻量级脚本。cmdlet 可以用任何 .Net 语言编写。

通常,cmdlet 表示为执行命令的动词-名词对。该命令是对底层操作系统的命令,以由最终用户执行特定服务。

PowerShell 环境包括 200 多个基本的 cmdlet,例如 New-ItemMove-ItemSet-LocationGet-Locationcmdlet 共享一组简单的 PowerShell 函数中不可用的通用功能。

  1. 支持 -WhatIfErrorActionVerbose 等常用参数。
  2. 提示确认
  3. 强制参数支持

PowerShell 中的 CmdletBinding 属性

通过继承上面讨论的基本 cmdlet 功能,可以将简单的 PowerShell 函数编写为高级函数。CmdletBinding 属性使你能够访问这些基本的 cmdlet 功能。

下面显示了带有所有可能参数的 CmdletBinding 属性语法。

{
    [CmdletBinding(ConfirmImpact=<String>,
    DefaultParameterSetName=<String>,
    HelpURI=<URI>,
    SupportsPaging=<Boolean>,
    SupportsShouldProcess=<Boolean>,
    PositionalBinding=<Boolean>)]

    Param ($myparam)
    Begin{}
    Process{}
    End{}
}

假设我们有一个名为 Helloworld-To-UpperCase 的简单 PowerShell 函数。

Function Helloworld-To-UpperCase {
    "helloworld".ToUpper();
}

此函数没有附加参数。因此,这称为简单的 PowerShell 函数。

但是我们可以使用 CmdletBinding 属性将此功能转换为高级功能并访问基本的 cmdlet 功能和参数,如下所示。

Function Helloworld-To-UpperCase {
    [CmdletBinding()]Param()
    "helloworld".ToUpper();
}

Helloworld-To-UpperCase 函数已转换为继承所有基本 cmdlet 功能的高级函数。基本的 cmdlet 参数可用于此函数。

如果你在 PowerShell 窗口中使用 - 调用此函数,它应该列出来自 cmdlet 的所有常用参数。

helloworld-to-uppercase -

输出:

cmdlet 参数

常见的 cmdlet 参数和功能可以在我们的高级功能中使用以扩展功能。

CmdletBinding 属性与 Verbose 参数一起使用

-verbose 是有价值的常用参数之一,可以在执行高级功能时显示消息。

Function Helloworld-To-UpperCase {
    [CmdletBinding()]Param()

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    "helloworld".ToUpper();
}

当我们使用 -verbose 参数调用上述函数时,它会将所有 Write-Verbose 字符串打印到 PowerShell 窗口。

HelloWorld-To-UpperCase -Verbose

输出:

带有详细参数的 CmdletBinding

CmdletBinding 属性与 $PSCmdlet 对象和 SupportsShouldProcess 一起使用

由于我们使用了 CmdletBinding 属性,我们的高级函数可以轻松访问 $PSCmdlet 对象。该对象包含多个方法,例如 ShouldContinueShouldProcessToStringWriteDebug 等。

CmdletBinding 属性与 ShouldContinue 方法一起使用

此方法允许用户处理确认请求。同时,必须将 SupportsShouldProcess 参数设置为 $True

ShouldContinue 方法有几个重载方法,我们将使用带有两个参数的方法。

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess=$True)]Param()

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        "helloworld".ToUpper();
    } Else {
        "helloworld kept in lowercase."
    }
}

我们可以使用 -Confirm 参数调用该函数,它会显示一个确认框,如下所示。

HelloWorld-To-UpperCase -Confirm

输出:

使用 ShouldContinue 方法 1 的 CmdletBinding

如果用户点击 Yes,它应该实现 if 块中的方法并以大写字母打印 helloworld 字符串。

CmdletBinding 与 ShouldContinue 方法 2

如果不是,它应该显示 helloworld 保持在小写消息。

CmdletBinding 与 ShouldContinue 方法 3

使用 CmdletBinding 属性和 Parameter 属性来控制函数参数

让我们让我们的高级函数将一个参数作为一个字符串。

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess=$True)]
    Param([string]$word)

    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        $word.ToUpper();
    } Else {
        "helloworld kept in lowercase."
    }
}

我们已将 Helloworld-To-UpperCase 函数更改为采用一个名为 $word 的字符串类型参数。当函数被调用时,我们需要提供一个字符串作为参数。

提供的文本将转换为大写。如果用户没有提供任何文本参数,该函数将给出一个空输出。

我们可以通过强制 $word 参数并给参数位置 0 来控制这一点。

Function Helloworld-To-UpperCase {
    [CmdletBinding(SupportsShouldProcess=$True)]
    Param(
    [Parameter(
        Mandatory=$True, Position=0
    ) ]
    [string]$word
    )

    #Verbose
    Write-Verbose "This is the common parameter usage -Version within our Helloworld-To-UpperCase function"

    #If/Else block for request processing
    if ($PSCmdlet.ShouldContinue("Are you sure on making the helloworld all caps?", "Making uppercase with ToUpper")) {
        $word.ToUpper();
    } Else {
        "helloworld kept in lowercase."
    }
}

我们添加了一些标志来控制 $word 参数的行为。由于它是强制性的,因此我们需要在函数执行时提供一个字符串值。

HelloWorld-To-UpperCase -Confirm "stringtouppercase"

如果我们不提供 text 参数,PowerShell 会一直要求这样做。

CmdletBinding 参数属性

你可以使用多个标志来控制函数中的参数,如以下 Parameter 属性语法所示。

 Param
(
    [Parameter(
        Mandatory=<Boolean>,
        Position=<Integer>,
        ParameterSetName=<String>,
        ValueFromPipeline=<Boolean>,
        ValueFromPipelineByPropertyName=<Boolean>,
        ValueFromRemainingArguments=<Boolean>,
        HelpMessage=<String>,
     )]
    [string[]]
    $Parameter1
)
Migel Hewage Nimesha avatar Migel Hewage Nimesha avatar

Nimesha is a Full-stack Software Engineer for more than five years, he loves technology, as technology has the power to solve our many problems within just a minute. He have been contributing to various projects over the last 5+ years and working with almost all the so-called 03 tiers(DB, M-Tier, and Client). Recently, he has started working with DevOps technologies such as Azure administration, Kubernetes, Terraform automation, and Bash scripting as well.