[玩转系统] 关于函数 CmdletBindingAttribute

作者：精品下载站日期：2024-12-14 02:22:35 浏览：13 分类：玩电脑

关于函数 CmdletBindingAttribute

简短描述

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

详细描述

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

当您使用 CmdletBinding 属性时，PowerShell 会自动添加通用参数。您不能创建任何与公共参数使用相同名称的参数。有关更多信息，请参阅 about_CommonParameters。

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 参数等于或大于 $ConfirmPreference 首选项变量的值时，对 ShouldProcess 方法的调用才会显示确认提示。（该参数的默认值为 Medium。）仅当还指定了 SupportsShouldProcess 参数时才指定此参数。

有关确认请求的更多信息，请参阅请求确认。

默认参数集名称

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

帮助URI

HelpURI 参数指定描述该功能的帮助主题的在线版本的 Internet 地址。 HelpURI 参数的值必须以“http”或“https”开头。

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

但是，当计算机上安装了帮助文件并且帮助文件的 RelatedLinks 部分中的第一个链接的值是 URI 或第一个 .Link的值时基于注释的帮助中的 > 指令是一个 URI，帮助文件中的 URI 用作函数的 HelpUri 属性的值。

当 Online 参数为 Get-Help cmdlet 时，Get-Help cmdlet 使用 HelpURI 属性的值来查找函数帮助主题的在线版本>Get-Help 在命令中指定。

SupportsPaging

SupportsPaging 参数将 First、Skip 和 IncludeTotalCount 参数添加到函数中。这些参数允许用户从非常大的结果集中选择输出。此参数专为从支持数据选择的大型数据存储（例如 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 参数向函数添加 Confirm 和 WhatIf 参数。 Confirm 参数会在对管道中的每个对象运行命令之前提示用户。 WhatIf 参数列出该命令将进行的更改，而不是运行该命令。

PositionalBinding

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

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

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

当参数不是位置参数（它们是“命名”）时，命令中需要参数名称（或名称的缩写或别名）。

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

当 PositionalBinding 为 $False 时，默认情况下函数参数不是位置参数。除非在参数上声明了 Parameter 属性的 Position 参数，否则在函数中使用参数时必须包含参数名称（或别名或缩写）。

Parameter 属性的 Position 参数优先于 PositionalBinding 默认值。您可以使用Position参数来指定参数的位置值。有关 Position 参数的更多信息，请参阅 about_Functions_Advanced_Parameters。