about_Functions_CmdletBindingAttribute

適用於: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

主題

about_Functions_CmdletBindingAttribute

簡短描述

描述讓函式像已編譯的 Cmdlet 般運作的屬性。

詳細描述

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

Windows 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{}
        }

ConfirmImpact

ConfirmImpact 引數可指定何時應呼叫 ShouldProcess 方法來確認函式的動作。唯有當 ConfirmImpact 引數等於或大於 $ConfirmPreference 喜好設定變數的值時，呼叫 ShouldProcess 方法才會顯示確認提示。(該引數的預設值為 Medium。)請只有在 SupportsShouldProcess 引數也已指定時，才指定這個引數。

如需確認要求的詳細資訊，請參閱 MSDN (Microsoft Developer Network) Library 中的＜要求確認＞，網址為 https://go.microsoft.com/fwlink/?LinkId=136658。

DefaultParameterSetName

DefaultParameterSetName 引數可指定參數集的名稱，當 Windows PowerShell 無法判斷要使用哪一個參數集時，就會嘗試使用該參數集。您可以使每個參數集的唯一參數都成為必要參數，就可以避免這個問題。

HelpURI

HelpURI 引數可指定描述函式之說明主題線上版本的網際網路位址 (統一資源識別項 (URI))。HelpURI 引數的值必須以 "http" 或 "https" 開頭。

HelpURI 引數值會用於 Get-Command 為函式傳回之 CommandInfo 物件的 HelpURI 屬性值。

不過，當說明檔案安裝在電腦上，而且說明檔的 RelatedLinks 區段中的第一個連結的值是 URI，或者註解式說明中的第一個 .Link 指示詞是 URI 時，說明檔中的 URI 就會做為函式的 HelpUri 屬性值。

當命令中指定 Get-Help 的 Online 參數時，Get-Help Cmdlet 會使用 HelpURI 屬性的值來尋找函式說明主題的線上版本。

SupportsPaging

SupportsPaging 引數會將 First、Skip 和 IncludeTotalCount 參數新增至函式。這些參數可讓使用者從非常大的結果集中選取輸出。此引數專為從支援資料選取之大型資料存放區 (例如 SQL 資料庫) 傳回資料的 Cmdlet 和函式所設計。

此引數在 Windows PowerShell 3.0 中引進。

First：

只取得前 'n' 個物件。

Skip：

略過前 'n' 個物件，然後取得其餘物件。

IncludeTotalCount：

報告資料集中的物件數目 (整數)，後面接著那些物件。如果 Cmdlet 無法判斷總計數，則會傳回「未知的總計數」。

Windows PowerShell 包含 NewTotalCount，這是一種 Helper 方法，它會取得要傳回的總計數值，並包含總計數值的精確度評估。

下列函式範例會示範如何將對分頁參數的支援新增至進階函式。

         function Get-Numbers
         {
             [CmdletBinding(SupportsPaging = $true)]
             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 中引進。

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

當參數不是位置 (是「具名」) 時，命令中會需要參數名稱 (或是名稱的縮寫或別名)。

當 PositionalBinding 為 $True 時，函式參數預設為位置。Windows PowerShell 會依照在函式中宣告的順序，將位置編號指派給參數。

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

Parameter 屬性的 Position 引數優先於 PositionalBinding 預設值。您可以使用 Position 引數來指定參數的位置值。如需 Position 引數的詳細資訊，請參閱 about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173)。

附註

進階函式中不支援 SupportsTransactions 引數。

關鍵字

about_Functions_CmdletBinding_Attribute

另請參閱

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute