about_Functions_Advanced_Methods

發行項
10/16/2024

簡短描述

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

詳細描述

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

適用於所有函式的相同輸入處理方法。
在執行 ShouldProcess 動作之前，用來取得使用者意見反應的和 ShouldContinue 方法。
ThrowTerminatingError產生錯誤記錄的方法。
傳回不同類型的輸出的數 Write 種方法。

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

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

輸入處理方法

本節所述的方法稱為輸入處理方法。對於函式，這三種方法是由函式的 begin、 process和 end 區塊表示。 PowerShell 7.3 新增區塊 clean 進程方法。

您不需要在函式中使用任何這些區塊。如果您沒有使用具名區塊，PowerShell 會將程式代碼 end 放入函式的區塊中。不過，如果您使用這些具名區塊中的任何一個 dynamicparam ，或定義區塊，則必須將所有程式代碼放在具名區塊中。

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

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

注意

這些區塊適用於所有函式，而不只是使用屬性的 CmdletBinding 函式。

`begin`

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

`process`

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

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

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

重要

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

當您建立接受管線輸入並使用 CmdletBinding的函式時， process 區塊應該使用您為管線輸入定義的參數變數，而不是 $_ 或 $PSItem。例如：

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

`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 屬性可讓您查看正在使用的參數集。參數集可讓您建立函式，根據執行函式時所指定的參數來執行不同的工作。

共用方式為