共用方式為


about_Functions_CmdletBindingAttribute

簡短描述

描述讓函式運作的屬性,就像編譯的 Cmdlet 一樣。

詳細描述

屬性 CmdletBinding 是函式的屬性,可讓函式像以 C# 撰寫的已編譯 Cmdlet 一樣運作。 它可讓您存取 Cmdlet 的功能。

當您使用 屬性時 CmdletBinding ,PowerShell 會自動新增 Common Parameters。 您無法建立任何使用與一般參數相同名稱的參數。 如需詳細資訊,請參閱 about_CommonParameters

PowerShell 會以系結已編譯 Cmdlet 參數的相同方式,系結具有 CmdletBinding 屬性的函式參數。 具有 $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 方法的呼叫才會顯示確認提示。 (自變數的預設值為。)只有在同時指定 SupportsShouldProcess 自變數時,才指定這個自變數。

如需確認要求的詳細資訊,請參閱 要求確認

DefaultParameterSetName

DefaultParameterSetName 自變數會指定 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 自變數會將 FirstSkipIncludeTotalCount 參數新增至函式。 這些參數可讓使用者從非常大的結果集中選取輸出。 這個自變數是針對 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 自變數會將 ConfirmWhatIf 參數新增至函式。 Confirm 參數會在管線中的每個物件上執行命令之前提示使用者。 WhatIf 參數會列出命令將進行的變更,而不是執行命令。

PositionalBinding

PositionalBinding 自變數會根據預設判斷函式中的參數是否為位置。 預設值是 $True。 您可以使用 PositionalBinding 自變數搭配 值 $False 來停用位置系結。

PositionalBinding 自變數是在 Windows PowerShell 3.0 中引進的。

當參數是位置時,參數名稱是選擇性的。 PowerShell 會根據函式命令中未命名參數值的順序或位置,將未命名的參數值與函式參數產生關聯。

當參數不是位置時(它們為 “named”),命令中需要參數名稱(或名稱的縮寫或別名)。

當 PositionalBinding$True,函式參數預設為位置。 PowerShell 會根據函式中宣告的位置編號,將位置編號指派給參數。

當 PositionalBinding$False,函式參數預設不是位置。 除非參數屬性的Position自變數在 參數上宣告,否則參數名稱(或別名或縮寫)必須在函式中使用參數時包含。

Parameter 屬性的 Position 自變數優先於 PositionalBinding 預設值。 您可以使用 Position 自變數來指定參數的位置值。 如需Position自變數的詳細資訊,請參閱about_Functions_Advanced_Parameters

備註

階函式不支援 SupportsTransactions 自變數。

關鍵字

about_Functions_CmdletBinding_Attribute

另請參閱