about_Functions_CmdletBindingAttribute
簡短描述
描述讓函式運作的屬性,就像編譯的 Cmdlet 一樣。
完整描述
屬性 CmdletBinding
是函式的屬性,其運作方式就像以 C# 撰寫的已編譯 Cmdlet 一樣。 它可讓您存取 Cmdlet 的功能。
PowerShell 會以系結已編譯 Cmdlet 參數的相同方式,系結具有 CmdletBinding
屬性的函式參數。 具有 $PSCmdlet
屬性的 CmdletBinding
函式可以使用自動變數,但 $Args
變數無法使用。
在具有 屬性的函式中 CmdletBinding
,沒有相符位置參數的未知參數和位置引數會導致參數系結失敗。
注意
編譯的 Cmdlet 會使用必要 Cmdlet
屬性,類似于 CmdletBinding
本主題中所述的屬性。
Syntax
下列範例顯示函式的格式,指定屬性的所有選擇性引數 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 無法判斷要使用的參數集時,PowerShell 會嘗試使用的參數集名稱。 您可以藉由讓每個參數的唯一參數設定強制參數來避免此問題。
HelpURI
HelpURI引數會指定說明函式之線上版本說明主題的網際網路位址。 HelpURI引數的值必須以 「HTTP」 或 「HTTPs」 開頭。
HelpURI引數值用於傳回函式之CommandInfo物件的 Get-Command
HelpURI屬性值。
不過,當說明檔安裝在電腦上,而說明檔之 RelatedLinks 區段中第一個連結的值是 URI,或以批註為基礎的說明中第一個 .Link
指示詞的值是 URI 時,說明檔中的 URI 會當做函式 HelpUri 屬性的值使用。
Cmdlet Get-Help
會使用 HelpURI 屬性的值,在 命令中指定 Online 參數 Get-Help
時,找出函式說明主題的線上版本。
SupportsPaging
SupportsPaging引數會將First、Skip和IncludeTotalCount參數新增至函式。 這些參數可讓使用者從非常大的結果集中選取輸出。 此引數是針對 Cmdlet 和函式所設計,這些 Cmdlet 和函式會從支援資料選取的大型資料存放區傳回資料,例如 SQL 資料庫。
此引數是在 Windows PowerShell 3.0 中引進。
- 第一個:只取得第一個 'n' 物件。
- Skip:忽略第一個 '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引數會將Confirm和WhatIf參數新增至函式。 Confirm參數會在管線中的每個物件上執行命令之前提示使用者。 WhatIf參數會列出命令所做的變更,而不是執行命令。
PositionalBinding
PositionalBinding引數會根據預設判斷函式中的參數是否為位置。 預設值是 $True
。 您可以使用 PositionalBinding 引數搭配 值 $False
來停用位置系結。
PositionalBinding引數是在 Windows PowerShell 3.0 中引進。
當參數是位置時,參數名稱是選擇性的。 PowerShell 會根據函式命令中未具名引數值的順序或位置,將未命名的參數值與函式參數產生關聯。
當參數不是位置 (它們是「name」) 時,命令中需要名稱名稱 (或縮寫或別名) 。
當 PositionalBinding為 $True
時,函式參數預設為位置。 PowerShell 會依函式中宣告的位置順序,將位置編號指派給參數。
當 PositionalBinding為 $False
時,函式參數預設不是位置。 除非參數屬性的Position引數是在 參數上宣告,否則參數名稱 (或別名或縮寫) 必須在函式中使用 參數時包含。
Parameter屬性的Position引數優先于PositionalBinding預設值。 您可以使用 Position 引數來指定參數的位置值。 如需 Position 引數的詳細資訊,請參閱 about_Functions_Advanced_Parameters。
備註
進階函式不支援 SupportsTransactions 引數。
關鍵字
about_Functions_CmdletBinding_Attribute