編輯附註
重要
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 平臺的格式設定。 已修正某些錯字和次要錯誤。
屬性 物件會將預先定義的系統資訊與 目標專案產生關聯，它可以是 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()]中。 某些屬性類型具有位置和具名參數 （），就像函式和 Cmdlet 一樣。 例如
[A(10,IgnoreCase=$true)]
顯示類型為 A 的實例，使用位置參數，其參數值為 10，以及具名參數 IgnoreCase，參數值為 $true。
12.3 保留屬性
下列各節所述的屬性可用來增強或修改 PowerShell 函式、篩選、腳本和 Cmdlet 的行為。
12.3.1 Alias 屬性
這個屬性用於 script-parameter 中，以指定參數的替代名稱。 參數可能會有多個別名，而且每個別名名稱在參數清單 內必須是唯一的，。 其中一個可能的用法是在不同的參數集中有不同的參數名稱（請參閱 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，稱為 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 屬性
在 屬性清單 中，這個屬性用於函式的 參數區塊，指出該函式的作用類似於 Cmdlet。 具體來說，它允許函式透過 $PSCmdlet 變數存取一些方法和屬性，方法是使用 begin、process 和 end 命名區塊（§8.10.7）。
當此屬性存在時，沒有相符位置參數的位置自變數會導致參數係結失敗，且未定義$args。 （如果沒有此屬性，$args將接受任何不相符的位置自變數值。
下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| SupportsShouldProcess （命名） | 類型：bool;默認值：$false 指定函式是否支援呼叫 ShouldProcess 方法，這個方法用來在函式對系統進行變更之前提示使用者提供意見反應。 $true的值表示它確實如此。 $false 的值表示它並非如此。 |
| ConfirmImpact （具名） | 類型：字串;默認值：“Medium” 指定執行之動作的影響層級。 只有在 ConfirmImpact 自變數大於或等於$ConfirmPreference喜好設定變數的值時，ShouldProcess 方法的呼叫才會顯示確認提示。 此自變數的可能值為： 無：隱藏確認的所有要求。 低：執行的動作有遺失數據的風險很低。 中：執行的動作有遺失數據的中等風險。 高：執行的動作有遺失數據的風險很高。 您可以設定$ConfirmPreference的值，讓只有具有相同或更高影響層級的 Cmdlet 才能要求確認，才能執行其作業。 例如，如果$ConfirmPreference設定為 [中]，則具有 [中] 或 [高影響等級] 的 Cmdlet 可以要求確認。 對於低影響層級的 Cmdlet 請求會被抑制。 |
| DefaultParameterSetName（命名） | 類型：字串;默認值：“__AllParameterSets” 指定在無法從引數判斷時使用的參數集。 請參閱屬性 Parameter ([第12.3.7節][第12.3.7節]) 中的具名參數 ParameterSetName。 |
| PositionalBinding （命名） | 類型：bool;默認值：$true 指定是否支援位置系結。 如果任何參數在屬性 Parameter 中為具名引數 Position 或具名引數 ParameterSetName 指定了非預設值，則會忽略此引數的值 (§12.3.7)。 如果參數是 $false，則沒有任何參數具有位置性；否則，參數會根據指定的順序指派位置。 |
以下是使用此屬性的架構範例：
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Low")]
param ( ... )
begin { ... }
Get-process { ... }
end { ... }
12.3.6 OutputType 屬性
這個屬性用於 屬性清單 的 參數區塊，以指定傳回的類型。 下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| 類型 （位置 0） | 類型：string[] 或類型常值的陣列 傳回之值的型別清單。 |
| ParameterSetName （命名） | 類型：string[] 指定將會傳回類型參數中對應元素所指示之類型的參數集。 |
以下是此屬性使用的數個範例：
[OutputType([int])] param ( ... )
[OutputType("double")] param ( ... )
[OutputType("string","string")] param ( ... )
12.3.7 參數屬性
這個屬性用於 腳本參數。 下列具名自變數可用來定義 參數的特性：
| 參數 | 用途 |
|---|---|
| HelpMessage （具名） | 類型：字串 這個自變數會指定訊息，該訊息旨在包含參數的簡短描述。 當函式或 Cmdlet 執行時，這個訊息會以實作定義的方式使用，但具有 HelpMessage 的必要參數沒有對應的自變數。 下列範例顯示提供參數描述的參數宣告。 param （ [Parameter（Mandatory = $true， Windows PowerShell：如果未提供必要的參數，運行時間會提示使用者輸入參數值。 提示對話框包含 HelpMessage 文字。 |
| 強制 （具名） | 類型：bool;默認值：$false 這個自變數會指定指定參數集內是否需要參數（請參閱下面的ParameterSetName自變數）。 $true 的值表示其為真。 $false的值表示它不是。 param（[Parameter（Mandatory = $true）]） Windows PowerShell：如果未提供必要的參數，運行時間會提示使用者輸入參數值。 提示對話框包含 HelpMessage 文字，如果有的話。 |
| ParameterSetName （命名） | 類型：字串;默認值：“__AllParameterSets” 您可以撰寫可針對不同案例執行不同動作的單一函式或 Cmdlet。 其方式是根據所要採取的動作，公開不同的參數群組。 這類參數群組稱為 參數集。 argument ParameterSetName 會指定參數所屬的參數集。 此行為表示每個參數集都必須有一個不是任何其他參數集成員的唯一參數。 對於屬於多個參數集的參數，請為每個參數集新增Parameter屬性。 這可讓參數針對每個參數集以不同的方式定義。 包含多個位置參數的參數集必須為每個參數定義唯一的位置。 沒有兩個位置參數可以指定相同的位置。 如果未為參數指定任何參數集，參數會屬於所有參數集。 定義多個參數集時，會使用屬性 CmdletBinding 屬性的具名自變數 DefaultParameterSetName（[\12.3.5][\12.3.5]）來指定預設參數集。 如果運行時間無法根據命令提供的資訊判斷要使用的參數集，則運行時間會使用預設參數集，如果沒有指定預設參數集，則會引發例外狀況。 下列範例展示函式 Test，其中有兩個參數分別屬於兩個不同的參數集，還有第三個參數同時屬於這兩個集合。 param （ [Parameter（Mandatory = $true， [Parameter（必需的 = $true， [Parameter（必需的 = $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 並設定為 $true 的參數。 如果函式具有參數$ComputerName，而管線物件具有 ComputerName 屬性，則 ComputerName 屬性的值會指派給 Function 的 $ComputerName 參數： param （ [Parameter（Mandatory = $true， 參數集中的多個參數可以將 ValueFromPipelineByPropertyName 定義為 $true。 雖然單一輸入對象無法系結至多個參數，但是該輸入物件中的不同屬性可能會系結至不同的參數。 使用輸入物件的 屬性系結參數時，運行時間環境會先尋找與參數同名的屬性。 如果這類屬性不存在，執行時環境會依宣告順序尋找該參數的別名，並選擇存在屬性的第一個別名。 函式 Process-Date [Parameter（ValueFromPipelineByPropertyName=$true）] [Parameter（ValueFromPipelineByPropertyName=$true）] 進程 { ... } |
| ValueFromRemainingArguments（命名的） | 類型：bool;默認值：$false 這個自變數會指定參數是否接受未係結至函式參數的所有其餘自變數。 $true的值表示它確實如此。 $false的值表示它不成立。 下列範例顯示參數$Others，接受傳遞至函式 Test 之輸入物件的所有其餘自變數： param （Parameter（Mandatory = $true）][int] $p 1， 測試 10 20 # $Others 長度為 0 |
實作也可以定義其他屬性。
也會提供下列屬性：
- HelpMessageBaseName：指定資源識別碼所在的位置。 例如，此參數可以指定一個資源元件，其中包含需要本地化的說明訊息。
- HelpMessageResourceId：指定說明訊息的資源識別碼。
12.3.8 PSDefaultValue 屬性
這個屬性用於 script-parameter，以提供關於參數的額外資訊。 屬性會以已定義的實作方式使用。 下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| 幫助（已命名） | 類型：字串 這個自變數會指定訊息，該訊息旨在包含參數預設值的簡短描述。 此訊息會以實作定義的方式使用。 Windows PowerShell：該訊息用於 [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) cmdlet 顯示的說明主題中，作為參數描述的一部分。 |
| 值 （具名） | 類型：物件 這個自變數會指定一個值，這個值是要做為參數的預設值。 值會以實作定義的方式使用。 Windows PowerShell：當未指定 Help 屬性時，此值會當做 [Get-Help]（xref：Microsoft.PowerShell.Core.Get-Help）Cmdlet 所顯示之說明主題的參數描述的一部分。 |
12.3.9 SupportsWildcards 屬性
這個屬性用於 script-parameter，以提供關於參數的額外資訊。 屬性會以已定義的實作方式使用。
此屬性會作為 Get-Help cmdlet 所顯示的協助主題中參數描述的一部分使用。
12.3.10 ValidateCount 屬性
這個屬性用於 script-parameter，以指定參數可接受的自變數值下限和最大數目。 下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| 最小長度 （位置 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 屬性
這個屬性用於 script-parameter 或 變數，以指定參數自變數的最小和最大長度，該自變數必須具有類型字元串。 下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| 最小長度 （位置 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 屬性
這個屬性用於 script-parameter 或 變數，以指定參數的引數不能 $null，也不能是包含 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 屬性
這個屬性用於 script-parameter 或 變數，以指定參數不可是$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 屬性
這個屬性用於 script-parameter 或 變數，以指定正則表達式來比對參數的引數的模式。 下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| RegexString （位置 0） | 類型：字串 用來驗證參數自變數的正則表達式 |
| 選項（具名） | 類型：一般 -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 屬性
這個屬性用於 script-parameter 或 變數，以指定參數自變數的最小值和最大值。 下列自變數可用來定義 參數的特性：
| 參數名稱 | 用途 |
|---|---|
| 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 屬性
這個屬性用於 script-parameter 或 變數，以指定要用來驗證參數自變數的腳本。
位置 1 中的自變數是 script-block-expression。
請考慮具有下列參數區塊的函式呼叫 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
