about_Functions_Advanced_Methods

簡短描述

描述指定 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{}
}

begin

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

process

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

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

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

當您建立接受管線輸入並使用 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

powerShell 7.3 已新增 clean 區塊。

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

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

清除區塊會捨棄寫入至 Success 數據流的任何輸出。

確認方法

ShouldProcess

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

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

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

ShouldContinue

呼叫此方法以要求第二個確認訊息。 當 ShouldProcess 方法傳回 $true時，應該呼叫它。 如需此方法的詳細資訊，請參閱 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。

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。

其他方法和屬性

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

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

另請參閱

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Preference_Variables