属性

属性对象将预定义的系统信息与目标元素相关联，该目标元素可以是param块或参数（第8.10节）。每个属性对象都有一个属性类型。

属性提供的信息也称为元数据。元数据可以由命令或执行环境检查以控制命令如何处理数据，或者在运行时之前通过外部工具检查以控制命令本身的处理或维护方式。

多个属性可以应用于同一个目标元素。

12.1 属性规范

有用的提示

语法定义中的 ~opt~ 表示法表示词汇实体在语法中是可选的。

attribute-list:
    attribute
    attribute-list new-lines~opt~ attribute

attribute:
    [ new-lines~opt~ attribute-name ( attribute-arguments new-lines~opt~ ) new-lines~opt~ ]
    type-literal

attribute-name:
    type-spec

attribute-arguments:
    attribute-argument
    attribute-argument new-lines~opt~ ,
    attribute-arguments

attribute-argument:
    new-lines~opt~ expression
    new-lines~opt~ simple-name
    new-lines~opt~ simple-name = new-lines~opt~ expression

属性由属性名称和一个可选的位置参数和命名参数列表组成。位置参数（如果有）位于命名参数之前。命名参数由一个简单名称组成，可选地后跟一个等号，再后跟一个表达式。如果省略表达式，则假定值 $true。

属性名称是保留的属性类型（第12.3节）或某些实现定义的属性类型。

12.2 属性实例

属性实例是属性类型的对象。该实例代表运行时的一个属性。

要创建某种属性类型 A 的对象，请使用符号 A()。属性是通过将其实例包含在 [] 内来声明的，如 [A()] 中所示。某些属性类型具有位置参数和命名参数（第 8.14 节），就像函数和 cmdlet 一样。例如，

[A(10,IgnoreCase=$true)]

显示使用参数值为 10 的位置参数和参数值为 $true 的命名参数 IgnoreCase 创建的类型 A 的实例代码>.

12.3 保留属性

以下部分中描述的属性可用于增强或修改 PowerShell 函数、筛选器、脚本和 cmdlet 的行为。

12.3.1 别名属性

此属性在脚本参数中用于指定参数的备用名称。一个参数可以有多个别名，并且每个别名在参数列表中必须是唯一的。一种可能的用途是为不同参数集中的参数使用不同的名称（请参阅ParameterSetName）。

属性参数的类型为 string[]。

考虑一个具有以下参数块的函数调用 Test1，其调用方式如下：

param (
    [Parameter(Mandatory = $true)]
    [Alias("CN")]
    [Alias("name", "system")]
    [string[]] $ComputerName
)

Test1 "Mars", "Saturn"                # pass argument by position
Test1 -ComputerName "Mars", "Saturn"  # pass argument by name
Test1 -CN "Mars", "Saturn"            # pass argument using first alias
Test1 -name "Mars", "Saturn"          # pass argument using second alias
Test1 -sys "Mars", "Saturn"           # pass argument using third alias

考虑一个具有以下参数块的函数调用 Test2，其调用方式如下：

param (
    [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
    [Alias('PSPath')]
    [string] $LiteralPath
)

Get-ChildItem "E:\*.txt" | Test2 -LiteralPath { $_ ; "`n`t";
    $_.FullName + ".bak" }
Get-ChildItem "E:\*.txt" | Test2

Cmdlet Get-ChildItem（别名 Dir）向其返回的对象添加一个 string 类型的新 NoteProperty，名为PS路径。

12.3.2AllowEmptyCollection 属性

此属性在脚本参数中使用，以允许空集合作为强制参数的参数。

考虑一个具有以下参数块的函数调用 Test，其调用方式如下：

param (
    [parameter(Mandatory = $true)]
    [AllowEmptyCollection()]
    [string[]] $ComputerName
)

Test "Red", "Green" # $computerName has Length 2
Test "Red" # $computerName has Length 1
Test -comp @() # $computerName has Length 0

12.3.3AllowEmptyString 属性

此属性在脚本参数中使用，以允许空字符串作为强制参数的参数。

考虑一个具有以下参数块的函数调用 Test，其调用方式如下：

param (
    [parameter(Mandatory = $true)]
    [AllowEmptyString()]
    [string] $ComputerName
)

Test "Red" # $computerName is "Red"
Test "" # empty string is permitted
Test -comp "" # empty string is permitted

12.3.4AllowNull 属性

此属性在脚本参数中使用，以允许 $null 作为无法进行隐式转换的强制参数的实参。

考虑一个具有以下参数块的函数调用 Test，其调用方式如下：

param (
    [parameter(Mandatory = $true)]
    [AllowNull()]
    [int[]] $Values
)

Test 10, 20, 30     # $values has Length 3, values 10, 20, 30
Test 10, $null, 30  # $values has Length 3, values 10, 0, 30
Test -val $null     # $values has value $null

注意上面的第二种情况不需要这个属性；已经存在从 $null 到 int 的隐式转换。

12.3.5 CmdletBinding 属性

此属性用在函数的 param-block 的 attribute-list 中，以指示该函数的行为类似于 cmdlet。具体来说，它允许函数使用 begin、process 和 end 命名块通过 $PsCmdlet 变量访问许多方法和属性（第 8.10.7 节）。

当此属性存在时，没有匹配位置参数的位置参数会导致参数绑定失败并且未定义 $args。 （如果没有此属性，$args 将采用任何不匹配的位置参数值。）

以下参数用于定义参数的特征：

类型：布尔值；默认值：$false 指定函数是否支持调用 ShouldProcess 方法，该方法用于在函数对系统进行更改之前提示用户反馈。 $true 值表明确实如此。 $false 值表示不存在。

类型：字符串；默认值：“中”指定所执行操作的影响级别。仅当ConfirmImpact 参数大于或等于$ConfirmPreference 首选项变量的值时，对ShouldProcess 方法的调用才会显示确认提示。该参数的可能值为： None：禁止所有确认请求。低：执行的操作丢失数据的风险较低。中：执行的操作具有中等丢失数据的风险。高：执行的操作丢失数据的风险很高。可以设置 $ConfirmPreference 的值，以便只有具有相同或更高影响级别的 cmdlet 才能在执行操作之前请求确认。例如，如果 $ConfirmPreference 设置为“中”，则影响级别为“中”或“高”的 cmdlet 可以请求确认。来自影响级别较低的 cmdlet 的请求将被抑制。

类型：字符串；默认值：“__AllParameterSets” 指定在无法从参数中确定时要使用的参数集。请参阅属性 Parameter ([§12.3.7][§12.3.7]) 中的命名参数 ParameterSetName。

类型：布尔值；默认值：$true 指定是否支持位置绑定。如果任何参数为属性 Parameter ([§12.3.7][§12.3.7]) 中的命名参数 Position 或命名参数 ParameterSetName 指定非默认值，则忽略此参数的值。否则，如果参数为 $false，则没有参数是位置参数，否则将根据指定参数的顺序为参数分配位置。

以下是使用此属性的框架示例：

[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Low")]
param ( ... )

begin { ... }
Get-process { ... }
end { ... }

12.3.6 输出类型属性

该属性用在 param-block 的 attribute-list 中来指定返回的类型。以下参数用于定义参数的特征：

类型： string[] 或类型文字数组 返回值的类型列表。

类型：string[] 指定返回由 Type 参数的相应元素指示的类型的参数集。

以下是该属性使用的几个示例：

[OutputType([int])] param ( ... )
[OutputType("double")] param ( ... )
[OutputType("string","string")] param ( ... )

12.3.7 参数属性

此属性在脚本参数中使用。以下命名参数用于定义参数的特征：

类型：字符串 此参数指定一条消息，其中包含参数的简短描述。当函数或 cmdlet 运行但具有 HelpMessage 的强制参数没有相应的参数时，以实现定义的方式使用此消息。以下示例显示了提供参数说明的参数声明。 param ( [Parameter(Mandatory=$true,
HelpMessage="计算机名称数组。")]
[string[]] $ComputerName ) Windows PowerShell：如果未提供必需的参数，运行时会提示用户获取参数值。提示对话框包含 HelpMessage 文本。

类型：布尔值；默认值：$false 此参数指定给定参数集中是否需要该参数（请参阅下面的 ParameterSetName 参数）。 $true 值表明它是。 $false 值表明它不是。 param ( [Parameter(Mandatory=$true)]
[string[]] $ComputerName ) Windows PowerShell：如果未提供必需的参数，运行时会提示用户输入参数值。提示对话框包含 HelpMessage 文本（如果有）。

类型：字符串；默认值：“__AllParameterSets” 可以编写针对不同场景执行不同操作的单个函数或 cmdlet。它通过根据想要采取的操作公开不同的参数组来实现这一点。这种参数分组称为参数集。参数 ParameterSetName 指定参数所属的参数集。此行为意味着每个参数集必须有一个唯一的参数，该参数不属于任何其他参数集的成员。对于属于多个参数集的参数，为每个参数集添加一个 Parameter 属性。这允许为每个参数集不同地定义参数。包含多个位置参数的参数集必须为每个参数定义唯一的位置。两个位置参数不能指定相同的位置。如果某个参数没有指定参数集，则该参数属于所有参数集。当定义多个参数集时，属性 CmdletBinding ([§12.3.5][§12.3.5]) 的命名参数 DefaultParameterSetName 用于指定默认参数集。如果运行时无法根据命令提供的信息确定要使用的参数集，则它会使用默认参数集；如果未指定默认参数集，则会引发异常。以下示例显示函数 Test，其参数声明包含属于两个不同参数集的两个参数，以及属于这两个参数集的第三个参数： param ( [Parameter(Mandatory=$true,
ParameterSetName="Computer" )]
[string[]] $ComputerName，有效值集。

类型：布尔值；默认值：$true 指定字符串类型的参数是否应忽略大小写。

如果参数具有数组类型，则相应参数数组的每个元素都必须与值集的元素匹配。

考虑一个具有以下参数块的函数调用 Test，其调用方式如下：

param ( [ValidateSet("Red", "Green", "Blue")]
    [string] $Color,

    [ValidateSet("up", "down", "left", "right", IgnoreCase =
        $false)]
    [string] $Direction

)

Test -col "RED"    # case is ignored, is a member of the set
Test -col "white"  # case is ignored, is not a member of the set

Test -dir "up"     # case is not ignored, is a member of the set
Test -dir "Up"     # case is not ignored, is not a member of the set

[ValidateSet(("Red", "Green", "Blue")]$color = "RED" # ok, case is ignored
$color = "Purple"  # case is ignored, is not a member of the set