about_Functions_Advanced_Methods

發行項
10/04/2023

簡短描述

描述指定屬性的 CmdletBinding 函式如何使用可用於已編譯 Cmdlet 的方法和屬性。

詳細描述

指定屬性的 CmdletBinding 函式可以透過 $PSCmdlet 變數存取其他方法和屬性。這些方法包括下列方法：

編譯 Cmdlet 以執行其工作的輸入處理方法。
在執行 ShouldProcess 動作之前，用來取得使用者意見反應的和 ShouldContinue 方法。
ThrowTerminatingError產生錯誤記錄的方法。
傳回不同類型的輸出的數 Write 種方法。

PSCmdlet 類別的所有方法和屬性 都可供進階函式使用。如需詳細資訊，請參閱 System.Management.Automation.PSCmdlet 。

如需屬性的詳細資訊 CmdletBinding ，請參閱 about_Functions_CmdletBindingAttribute 。 如需 CmdletBindingAttribute 類別，請參閱 System.Management.Automation.Cmdlet.CmdletBindingAttribute 。

輸入處理方法

本節所述的方法稱為輸入處理方法。對於函式，這三種方法是由函式的 begin 、 process 和 end 區塊表示。您不需要在函式中使用任何這些區塊。

注意

這些區塊也適用于不使用屬性的 CmdletBinding 函式。

下列範例顯示函式的大綱，其中包含 begin 一次性前置處理區塊、 process 多個記錄處理的區塊，以及 end 一次性後置處理的區塊。

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

注意

使用或 end 區塊需要您定義這三個 begin 區塊。使用任何區塊時，所有 PowerShell 程式碼都必須位於其中一個區塊內。

PowerShell 7.3 新增區塊 clean 進程方法。

`begin`

此區塊可用來提供函式的選擇性一次性前置處理。 PowerShell 執行時間會針對管線中函式的每個實例使用此區塊中的程式碼一次。

`process`

此區塊可用來提供函式的逐筆記錄處理。您可以使用 process 區塊，而不定義其他區塊。區塊執行的數目 process 取決於您如何使用函式，以及函式所接收的輸入。

自動變數 $_ 或 $PSItem 包含管線中目前的物件，以用於 process 區塊。自動 $input 變數包含只能供函式和腳本區塊使用的列舉值。如需詳細資訊，請參閱 about_Automatic_Variables 。

在管線開頭或外部呼叫函式時，會執行區塊 process 一次。
在管線內，區塊 process 會針對到達函式的每個輸入物件執行一次。
如果到達函式的管線輸入是空的，則 process 區塊不會執行。
- begin和 end 區塊仍會執行。

重要

如果函式參數設定為接受管線輸入，且 process 未定義區塊，則逐筆記錄處理將會失敗。在此情況下，不論輸入為何，您的函式只會執行一次。

`end`

此區塊可用來為函式提供選擇性的一次性後置處理。

`clean`

區塊 clean 已在 PowerShell 7.3 中新增。

區塊 clean 是方便使用者清除跨 begin 、 process 和 end 區塊的資源。其語意類似于 finally 涵蓋腳本函式或腳本 Cmdlet 之所有其他具名區塊的區塊。下列案例會強制執行資源清除：

當管線執行正常完成而不終止錯誤時
當管線執行因終止錯誤而中斷時
當管線停止時 Select-Object -First
當管線被 Ctrl+c 停止時，或 StopProcessing()

警告

新增區塊 clean 是重大變更。因為 clean 剖析為關鍵字，所以會防止使用者直接呼叫名為 clean 的命令，做為腳本區塊中的第一個語句。然而，這不太可能是個問題。命令仍然可以使用呼叫運算子（ & clean ）來叫用。

確認方法

ShouldProcess

在函式執行會變更系統的動作之前，呼叫此方法以要求使用者確認。函式可以根據方法所傳回的布林值繼續進行。這個方法只能從函式的區塊內 Process{} 呼叫。屬性 CmdletBinding 也必須宣告函式支援 ShouldProcess （如上一個範例所示）。

如需此方法的詳細資訊，請參閱 System.Management.Automation.Cmdlet.ShouldProcess 。

如需如何要求確認的詳細資訊，請參閱要求確認。

ShouldContinue

呼叫此方法以要求第二個確認訊息。當方法傳 $true 回時 ShouldProcess ，應該呼叫它。如需此方法的詳細資訊，請參閱 System.Management.Automation.Cmdlet.ShouldContinue 。

錯誤方法

當發生錯誤時，函式可以呼叫兩個不同的方法。當發生非終止錯誤時，函式應該呼叫 WriteError 方法，如方法一節中所述 Write 。當終止錯誤發生且函式無法繼續時，應該呼叫 ThrowTerminatingError 方法。您也可以使用 Throw 語句來終止錯誤，以及針對非終止錯誤使用 Write-Error Cmdlet。

如需詳細資訊，請參閱 System.Management.Automation.Cmdlet.ThrowTerminatingError 。

撰寫方法

函式可以呼叫下列方法來傳回不同類型的輸出。請注意，並非所有輸出都會移至管線中的下一個命令。您也可以使用各種 Write Cmdlet，例如 Write-Error 。

WriteCommandDetail

如需方法 WriteCommandDetails 的相關資訊，請參閱 System.Management.Automation.Cmdlet.WriteCommandDetail 。

WriteDebug

若要提供可用來對函式進行疑難排解的資訊，請讓函式呼叫 WriteDebug 方法。方法 WriteDebug 會向使用者顯示偵錯訊息。如需詳細資訊，請參閱 System.Management.Automation.Cmdlet.WriteDebug 。

WriteError

函式應該在發生非終止錯誤時呼叫這個方法，且函式的設計目的是要繼續處理記錄。如需詳細資訊，請參閱 System.Management.Automation.Cmdlet.WriteError 。

注意

如果發生終止錯誤，函式應該呼叫 ThrowTerminatingError 方法。

WriteObject

方法可讓函 WriteObject 式將物件傳送至管線中的下一個命令。在大部分情況下， WriteObject 是當函式傳回資料時使用的方法。如需詳細資訊，請參閱 System.Management.Automation.PSCmdlet.WriteObject 。

WriteProgress

對於動作需要很長的時間才能完成的函式，這個方法可讓函式呼叫 WriteProgress 方法，以便顯示進度資訊。例如，您可以顯示已完成百分比。如需詳細資訊，請參閱 System.Management.Automation.PSCmdlet.WriteProgress 。

WriteVerbose

若要提供函式執行作業的詳細資訊，請讓函式呼叫 WriteVerbose 方法，向使用者顯示詳細資訊訊息。根據預設，不會顯示詳細資訊訊息。如需詳細資訊，請參閱 System.Management.Automation.PSCmdlet.WriteVerbose 。

WriteWarning

若要提供可能造成非預期結果的條件相關資訊，請讓函式呼叫 WriteWarning 方法，向使用者顯示警告訊息。根據預設，會顯示警告訊息。如需詳細資訊，請參閱 System.Management.Automation.PSCmdlet.WriteWarning 。

注意

您也可以藉由設定 $WarningPreference 變數或使用 Verbose 和 Debug 命令列選項來顯示警告訊息。如需變數的詳細資訊 $WarningPreference ，請參閱 about_Preference_Variables 。

其他方法和屬性

如需可透過變數存取 $PSCmdlet 之其他方法和屬性的資訊，請參閱 System.Management.Automation.PSCmdlet 。

例如， ParameterSetName 屬性可讓您查看正在使用的參數集。參數集可讓您建立函式，根據執行函式時所指定的參數來執行不同的工作。