about_Functions_CmdletBindingAttribute

简短说明

描述使函数像编译的 cmdlet 一样工作的属性。

长说明

属性 CmdletBinding 是函数的一个属性,使函数像用 C# 编写的已编译 cmdlet 一样运行。 它提供对 cmdlet 功能的访问权限。

PowerShell 绑定具有 CmdletBinding 属性的函数的参数,其方式与绑定已编译 cmdlet 的参数的方式相同。 自动 $PSCmdlet 变量可用于具有 属性的 CmdletBinding 函数,但 $Args 该变量不可用。

在具有 属性的函数中 CmdletBinding ,未知参数和没有匹配位置参数的位置参数会导致参数绑定失败。

注意

已编译的 cmdlet 使用必需的 Cmdlet 属性,该属性类似于 CmdletBinding 本主题中所述的属性。

语法

下面的示例演示指定 特性的所有可选参数的 CmdletBinding 函数的格式。 此示例后面提供了每个参数的简要说明。

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

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

CmdletBinding 属性的布尔参数类型在从 CmdletBinding 属性中省略时默认为 False。 将参数值设置为 $true 或仅按名称列出参数。 例如,以下 CmdletBinding 属性是等效的。

{
    [CmdletBinding(SupportsPaging=$true)]

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

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

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

ConfirmImpact

ConfirmImpact 参数指定何时应通过调用 ShouldProcess 方法来确认函数的操作。 仅当 ConfirmImpact 参数等于或大于首选项变量的值时,对 ShouldProcess 方法的$ConfirmPreference调用才会显示确认提示。 (参数的默认值为 Medium.) 仅当还指定 SupportsShouldProcess 参数时指定此参数。

有关确认请求的详细信息,请参阅 请求确认

DefaultParameterSetName

DefaultParameterSetName 参数指定当 PowerShell 无法确定要使用的参数集时将尝试使用的参数集的名称。 可以通过使每个参数的唯一参数设置为必需参数来避免此问题。

HelpURI

HelpURI 参数指定描述函数的帮助主题联机版本的 Internet 地址。 HelpURI 参数的值必须以“http”或“https”开头。

HelpURI 参数值用于为函数返回的 CommandInfo 对象的 Get-CommandHelpURI 属性的值。

但是,如果帮助文件安装在计算机上,并且帮助文件的 RelatedLinks 部分中第一个链接的值为 URI,或者基于注释的帮助中第一 .Link 个指令的值为 URI,则帮助文件中的 URI 将用作函数的 HelpUri 属性的值。

Get-Help命令中指定 的 Online 参数Get-Help时,cmdlet 使用 HelpURI 属性的值来查找函数帮助主题的联机版本。

SupportsPaging

SupportsPaging 参数将 FirstSkipIncludeTotalCount 参数添加到函数。 这些参数允许用户从非常大的结果集中选择输出。 此参数适用于从支持数据选择的大型数据存储(如 SQL 数据库)返回数据的 cmdlet 和函数。

此参数是在 Windows PowerShell 3.0 中引入的。

  • First:仅获取前一个“n”对象。
  • 跳过:忽略第一个“n”对象,然后获取其余对象。
  • IncludeTotalCount:报告数据集中的对象数 (整数) 后跟对象。 如果 cmdlet 无法确定总计数,则返回“未知的总计数”。

PowerShell 包括 NewTotalCount,这是一种帮助程序方法,用于获取要返回的总计数值,并包括对总计计数值准确性的估计。

以下示例函数演示如何向高级函数添加对分页参数的支持。

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    param()

    $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
    $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
      $FirstNumber - 1, 100)

    if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
        $TotalCountAccuracy = 1.0
        $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
          $TotalCountAccuracy)
        Write-Output $TotalCount
    }
    $FirstNumber .. $LastNumber | Write-Output
}

SupportsShouldProcess

SupportsShouldProcess 参数将 ConfirmWhatIf 参数添加到函数。 在对管道中的每个对象运行命令之前, Confirm 参数会提示用户。 WhatIf 参数列出命令将进行的更改,而不是运行命令。

PositionalBinding

PositionalBinding 参数确定函数中的参数默认情况下是否为位置参数。 默认值为 $True。 可以使用值为 $FalsePositionalBinding 参数来禁用位置绑定。

PositionalBinding 参数在 Windows PowerShell 3.0 中引入。

当参数是位置参数时,参数名称是可选的。 PowerShell 根据函数命令中未命名参数值的顺序或位置,将未命名参数值与函数参数相关联。

如果参数不是位置参数 (它们 ) “命名”,则命令中需要参数名称 (或名称) 的缩写或别名。

PositionalBinding$True时,函数参数默认为位置参数。 PowerShell 按照参数在函数中声明的顺序为参数分配位置编号。

PositionalBinding$False时,函数参数默认不是位置参数。 除非对参数声明 Parameter 属性的 Position 参数,否则在函数中使用参数时,必须包含参数名称 (或别名或缩写) 。

Parameter 属性的 Position 参数优先于 PositionalBinding 默认值。 可以使用 Position 参数指定参数的位置值。 有关 Position 参数的详细信息,请参阅 about_Functions_Advanced_Parameters

备注

高级函数不支持 SupportsTransactions 参数。

关键字

about_Functions_CmdletBinding_Attribute

另请参阅