编辑说明
重要
Windows PowerShell 语言规范 3.0 于 2012 年 12 月发布，基于 Windows PowerShell 3.0。 此规范不反映 PowerShell 的当前状态。 没有计划更新本文档以反映当前状态。 此处提供了本文档供历史参考。
规范文档可从 Microsoft 下载中心以 Microsoft Word 文档的形式获取，网址为：https://www.microsoft.com/download/details.aspx?id=36389 该 Word 文档已转换为 Microsoft Learn 上的演示文稿。 转换期间，进行了一些编辑更改，以适应 Docs 平台的格式设置。 已更正某些拼写错误和次要错误。
属性 对象将预定义的系统信息与 目标元素相关联，可以是参数块或参数（§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
属性由 属性名称 和位置参数和命名参数的可选列表组成。
位置参数（如果有的话）在命名参数之前。 命名参数由 simple-name 组成，可以选择后跟一个等号，后跟一个表达式。 如果省略表达式，则假定 $true 值。
attribute-name 是保留的属性类型 (§12.3) 或一些实现定义的属性类型。
12.2 属性实例
属性实例是属性类型的对象。 实例表示运行时的属性。
若要 A创建某些属性类型的对象，请使用表示法 A()。 属性通过将其实例括在 [] 中来声明，如 [A()] 中一样。 某些属性类型具有位置参数和命名参数（§8.14），就像函数和 cmdlet 一样。 例如，
[A(10,IgnoreCase=$true)]
显示一个类型 A 的实例，该实例是使用位置参数创建的，其自变量值为 10，以及一个命名参数 IgnoreCase，其自变量值为 $true。
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，称为 PSPath。
12.3.2 AllowEmptyCollection 属性
此属性用于 script-parameter，以允许将空集合作为强制参数的参数。
请考虑函数调用 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.3 AllowEmptyString 属性
此属性用于 script-parameter，以允许将空字符串作为强制参数的参数。
请考虑函数调用 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.4 AllowNull 属性
此属性用于 script-parameter，允许将 $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。 具体而言，它允许函数通过使用开始、进程和结束命名块（§8.10.7）通过$PsCmdlet变量访问许多方法和属性。
当此属性存在时，没有匹配位置参数的位置参数会导致参数绑定失败，并且未定义 $args。 （如果没有此属性，$args将采用任何不匹配的位置参数值。
以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| SupportsShouldProcess（已命名） | 类型：bool;默认值：$false 指定函数是否支持调用 ShouldProcess 方法，该方法用于在函数更改系统之前提示用户提供反馈。 $true值指示它确实存在。 值 $false 表示某种情况不成立。 |
| ConfirmImpact（已命名） | 类型：string;默认值：“中等” 指定所执行的操作的影响级别。 仅当 ConfirmImpact 参数大于或等于$ConfirmPreference首选项变量的值时，对 ShouldProcess 方法的调用才会显示确认提示。 此参数的可能值为： 无：取消所有确认请求。 低：执行的操作存在丢失数据的风险较低。 中：执行的操作有丢失数据的中等风险。 高：执行的操作有丢失数据的风险很高。 可以设置$ConfirmPreference的值，以便只有具有相同或更高影响级别的 cmdlet 才能请求确认，然后才能执行操作。 例如，如果$ConfirmPreference设置为“中”，具有中等或高影响级别的 cmdlet 可以请求确认。 来自影响级别较低的 cmdlet 的请求被抑制。 |
| DefaultParameterSetName（已命名） | 类型：string;默认值：“__AllParameterSets” 若无法从参数中确定，则指定要使用的参数集。 请参阅属性参数 ([§12.3.7][§12.3.7]) 中的命名参数 ParameterSetName。 |
| PositionalBinding（已命名） | 类型：bool;默认值：$true 指定是否支持位置绑定。 如果任何参数在属性参数 ([§12.3.7][§12.3.7]) 中为命名参数 Position 或命名参数 ParameterSetName 指定了非默认值，则会忽略此参数的值。 否则，如果参数是$false，则没有位置参数，否则根据参数指定的顺序为参数分配位置。 |
下面是使用此属性的框架示例：
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Low")]
param ( ... )
begin { ... }
Get-process { ... }
end { ... }
12.3.6 OutputType 属性
此属性用于 属性列表 的 参数块 中指定返回的类型。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| 类型 （位置 0） | 类型：string[] 或类型文本数组 返回的值类型的列表。 |
| ParameterSetName（已命名） | 类型：string[] 指定返回 Type 参数的相应元素指示的类型的参数集。 |
下面是此属性使用的几个示例：
[OutputType([int])] param ( ... )
[OutputType("double")] param ( ... )
[OutputType("string","string")] param ( ... )
12.3.7 参数属性
此属性用于 script-parameter。 以下命名参数用于定义参数的特征：
| 参数 | 用途 |
|---|---|
| HelpMessage（已命名） | 类型：字符串 此参数指定一条消息，该消息旨在包含参数的简短说明。 当运行函数或 cmdlet 时，如果具有 HelpMessage 的强制参数没有相应的参数，则以实现定义的方式使用此消息。 以下示例展示了一个参数声明，其中包含对参数的描述。 param ( [Parameter(Mandatory = $true, Windows PowerShell：如果未提供必需的参数，运行时会提示用户输入参数值。 提示对话框包括 HelpMessage 文本。 |
| Mandatory（已命名） | 类型：bool;默认值：$false 此参数指定是否在给定参数集中需要参数（请参阅下面的 ParameterSetName 参数）。 如果值为 $true，表示情况是这样的。 值 $false 表示某种情况不成立。 param ( [Parameter(Mandatory = $true)] Windows PowerShell：如果未提供必需的参数，运行时会提示用户输入参数值。 提示对话框包括 HelpMessage 文本（如果有）。 |
| ParameterSetName（已命名） | 类型：string;默认值：“__AllParameterSets” 可以编写单个函数或 cmdlet，以便针对不同的方案执行不同的操作。 它通过公开不同的参数组来执行此操作，具体取决于它想要执行的操作。 此类参数分组称为 参数集。 参数 ParameterSetName 指定参数所属的参数集。 此行为意味着每个参数集必须有一个唯一参数，该参数不是任何其他参数集的成员。 对于属于多个参数集的参数，请为每个参数集添加一个 Parameter 属性。 这允许为每个参数集以不同的方式定义参数。 包含多个位置参数的参数集必须为每个参数定义唯一位置。 没有两个位置参数可以指定相同的位置。 如果未为参数指定任何参数集，则参数属于所有参数集。 定义多个参数集时，属性 CmdletBinding（[§12.3.5][§12.3.5][§12.3.5]）的命名参数 DefaultParameterSetName 用于指定默认参数集。 如果运行时无法根据命令提供的信息确定要使用的参数集，则运行时使用默认参数集;如果未指定默认参数集，则引发异常。 以下示例展示了函数 Test，其中包含两个参数的声明，这两个参数属于两个不同的参数集合，还有一个属于这两个集合的第三个参数： param ( [Parameter(Mandatory = $true, [Parameter(Mandatory = $true, [Parameter(Mandatory = $true, if ($PsCmdlet.ParameterSetName -eq "Computer") elseif ($PsCmdlet.ParameterSetName -eq "User") 测试 -ComputerName“火星”，“金星”-SharedParam 10 |
| 职位（指定） | 类型：int 此参数指定参数在参数列表中的位置。 如果未指定此参数，则必须在设置参数时显式指定参数名称或其别名。 如果函数的参数没有位置，则根据每个参数的接收顺序向每个参数分配位置。 以下示例演示在调用函数时必须将其值指定为第一个参数的参数的声明。 param ( [Parameter(Position = 0)] |
| ValueFromPipeline（已命名） | 类型：bool;默认值：$false 此参数指定参数是否接受来自管道对象的输入。 $true值指示它确实存在。 值 $false 表示某种情况不成立。 如果函数或 cmdlet 访问完整的对象，而不仅仅是对象的属性，请指定$true。 参数集中只有一个参数可以将 ValueFromPipeline 声明为$true。 以下示例显示了接受从管道传递给函数的输入对象的必需参数$ComputerName的参数声明。 param ( [Parameter(Mandatory = $true, 有关将此参数与 Alias 属性结合使用的示例，请参阅 [§12.3.1][§12.3.1]。 |
| ValueFromPipelineByPropertyName（已命名） | 类型：bool;默认值：$false 此参数表示参数的取值是否来自管道对象的属性，该属性与此参数同名或具有相同别名。 $true值指示它确实存在。 值 $false 表示某种情况不成立。 如果满足以下条件，请指定$true：参数访问管道对象的属性，并且该属性的名称与参数的名称相同，或者该属性具有与参数相同的别名。 ValueFromPipelineByPropertyName 设置为 $true 的参数不需要与 ValueFromPipeline 设置为 $ttrue 的参数在同一集中。 如果函数具有参数$ComputerName，并且管道对象具有 ComputerName 属性，则 ComputerName 属性的值将分配给函数的 $ComputerName 参数： param ( [parameter(Mandatory = $true, 参数集中的多个参数可以将 ValueFromPipelineByPropertyName 定义为 $true。 尽管单个输入对象不能绑定到多个参数，但该输入对象中的不同属性可能绑定到不同的参数。 将参数与输入对象的属性绑定时，运行时环境首先查找与参数同名的属性。 如果此类属性不存在，运行时环境会按声明顺序查找该参数的别名，并选取属性所在的第一个此类别名。 函数 Process-Date [Parameter(ValueFromPipelineByPropertyName=$true)] [Parameter(ValueFromPipelineByPropertyName=$true)] process { … } |
| ValueFromRemainingArguments（已命名） | 类型：bool;默认值：$false 此参数指定参数是否接受未绑定到函数参数的所有剩余参数。 $true值指示它确实存在。 值 $false 表示某种情况不成立。 以下示例演示一个参数$others，该参数接受传递给函数 Test 的输入对象的所有剩余参数： param ( [parameter(Mandatory = $true)][int] $p1, Test 10 20 # $others 长度为 0 |
实现还可以定义其他属性。
还提供了以下属性：
- HelpMessageBaseName：指定资源标识符所在的位置。 例如，此参数可以指定包含要本地化的帮助消息的资源程序集。
- HelpMessageResourceId：指定帮助消息的资源标识符。
12.3.8 PSDefaultValue 属性
此属性在 脚本参数 中用于提供有关参数的其他信息。 该特性以定义的实现方式使用。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| Help（已命名） | 类型：字符串 此参数指定一条消息，该消息旨在包含参数默认值的简短说明。 此消息以实现定义的方式使用。 Windows PowerShell：该消息用作 [Get-Help]（xref：Microsoft.PowerShell.Core.Get-Help） cmdlet 所显示帮助主题参数说明的一部分。 |
| Value（已命名） | 类型：对象 此参数指定一个值，该值旨在成为参数的默认值。 值以实现定义的方式使用。 Windows PowerShell：该值用作 [Get-Help]（xref：Microsoft.PowerShell.Core.Get-Help） cmdlet 未指定 Help 属性时显示的帮助主题参数说明的一部分。 |
12.3.9 SupportsWildcards 属性
此属性在 脚本参数 中用于提供有关参数的其他信息。 该特性以定义的实现方式使用。
此属性用作 Get-Help cmdlet 显示的帮助主题参数说明的一部分。
12.3.10 ValidateCount 属性
此属性用于 脚本参数 指定参数可以接受的最小和最大参数值数。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| MinLength（位置 0） | 类型：int 此参数指定允许的最小参数值数。 |
| MaxLength （位置 1） | 类型：int 此参数指定允许的最大参数值数。 |
如果没有此属性，参数的相应参数值列表可以是任何长度。
请考虑函数调用 Test，它具有以下参数块，调用方式如下：
param (
[ValidateCount(2, 5)]
[int[]] $Values
)
Temp 10, 20, 30
Temp 10 # too few argument values
Temp 10, 20, 30, 40, 50, 60 # too many argument values
[ValidateCount(3, 4)]$Array = 1..3
$Array = 10 # too few argument values
$Array = 1..100 # too many argument values
12.3.11 ValidateLength 属性
此属性用于 脚本参数 或 变量 指定参数参数的最小和最大长度，该参数必须具有类型字符串。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| MinLength（位置 0） | 类型：int 此参数指定允许的最小字符数。 |
| MaxLength （位置 1） | 类型：int 此参数指定允许的最大字符数。 |
如果没有此属性，参数的相应参数可以是任何长度。
请考虑函数调用 Test，它具有以下参数块，调用方式如下：
param ( [parameter(Mandatory = $true)]
[ValidateLength(3,6)]
[string[]] $ComputerName )
Test "Thor","Mars" # length is ok
Test "Io","Mars" # "Io" is too short
Test "Thor","Jupiter" # "Jupiter" is too long
12.3.12 ValidateNotNull 属性
此属性用于 脚本参数 或 变量 指定参数的传入值不能为 $null，也不能是包含空值元素的集合。
请考虑函数调用 Test，它具有以下参数块，调用方式如下：
param (
[ValidateNotNull()]
[string[]] $Names
)
Test "Jack", "Jill" # ok
Test "Jane", $null # $null array element value not allowed
Test $null # null array not allowed
[ValidateNotNull()]$Name = "Jack" # ok
$Name = $null # null value not allowed
12.3.13 ValidateNotNullOrEmpty 属性
此属性用于 脚本参数 或 变量，指定该参数不能为 $null、空字符串或空数组，或作为包含 $null 值或空字符串元素的集合中的元素。
请考虑函数调用 Test，它具有以下参数块，调用方式如下：
param (
[ValidateNotNullOrEmpty()]
[string[]] $Names
)
Test "Jack", "Jill" # ok
Test "Mary", "" # empty string not allowed
Test "Jane", $null # $null array element value not allowed
Test $null # null array not allowed
Test @() # empty array not allowed
[ValidateNotNullOrEmpty()]$Name = "Jack" # ok
$Name = "" # empty string not allowed
$Name = $null # null value not allowed
12.3.14 ValidatePattern 属性
此属性用于 脚本参数 或 变量 指定正则表达式以匹配参数参数的模式。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| RegexString（位置 0） | 类型：字符串 用于验证参数参数的正则表达式 |
| Options（已命名） | 类型：Regular-Expression-Option 有关允许的值，请参阅 [§4.2.6.4][§4.2.6.4]。 |
如果参数是集合，则集合中的每个元素必须与模式匹配。
请考虑具有以下参数块的函数调用 Test，调用如下所示：
param (
[ValidatePattern('\^[A-Z][1-5][0-9]$')]
[string] $Code,
[ValidatePattern('\^(0x|0X)([A-F]|[a-f]|[0-9])([A-F]|[a-f]|[0-9])$')]
[string] $HexNum,
[ValidatePattern('\^[+|-]?[1-9]$')]
[int] $Minimum
)
Test -c A12 # matches pattern
Test -c A63 # does not match pattern
Test -h 0x4f # matches pattern
Test -h "0XB2" # matches pattern
Test -h 0xK3 # does not match pattern
Test -m -4 # matches pattern
Test -m "+7" # matches pattern
Test -m -12 # matches pattern, but is too long
[ValidatePattern('\^[a-z][a-z0-9]\*$')]$ident = "abc"
$ident = "123" # does not match pattern
12.3.15 ValidateRange 属性
此属性用于 脚本参数 或 变量 来指定参数参数的最小值和最大值。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| MinRange （位置 0） | 类型：对象 此参数指定允许的最小值。 |
| MaxRange （位置 1） | 类型：对象 此参数指定允许的最大值。 |
如果没有此属性，则没有范围限制。
请考虑函数调用 Test1，它具有以下参数块，调用方式如下：
param (
[parameter(Mandatory = $true)]
[ValidateRange(1, 10)]
[int] $StartValue
)
Test1 2
Test1 -st 7
Test1 -3 # value is too small
Test1 12 # value is too large
考虑函数调用 Test2，它具有以下参数块和调用：
param (
[parameter(Mandatory = $true)]
[ValidateRange("b", "f")]
[string] $Name
)
Test2 "Bravo" # ok
Test2 "Alpha" # value compares less than the minimum
Test2 "Hotel" # value compares greater than the maximum
请考虑函数调用 Test3，它具有以下参数块，调用方式如下：
param (
[parameter(Mandatory = $true)]
[ValidateRange(0.002, 0.003)]
[double] $Distance
)
Test3 0.002
Test3 0.0019 # value is too small
Test3 "0.005" # value is too large
[ValidateRange(13, 19)]$teenager = 15
$teenager = 20 # value is too large
12.3.16 ValidateScript 属性
此属性用于 脚本参数 或 变量，以指定用于验证参数的脚本。
位置 1 的参数是 脚本块表达式。
请考虑函数调用 Test，它具有以下参数块，调用方式如下：
param (
[Parameter(Mandatory = $true)]
[ValidateScript( { ($_ -ge 1 -and $_ -le 3) -or ($_ -ge 20) })]
[int] $Count
)
Test 2 # ok, valid value
Test 25 # ok, valid value
Test 5 # invalid value
Test 0 # invalid value
[ValidateScript({$_.Length --gt 7})]$password = "password" # ok
$password = "abc123" # invalid value
12.3.17 ValidateSet 属性
此属性用于 脚本参数 或 变量 指定参数参数的一组有效值。 以下参数用于定义参数的特征：
| 参数名称 | 用途 |
|---|---|
| ValidValues（位置 0） | 类型：string[] 有效值集。 |
| IgnoreCase（已命名） | 类型：bool;默认值：$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
