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

輸入處理方法

本節所述的方法稱為輸入處理方法。 對於函式,這三種方法是由函式的 beginprocessend 區塊表示。

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

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

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

注意

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

begin

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

process

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

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

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

重要

如果函式參數設定為接受管線輸入,且 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

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

確認方法

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 變數或使用 VerboseDebug 命令行選項來顯示警告訊息。 如需變數的詳細資訊 $WarningPreference ,請參閱 about_Preference_Variables

其他方法和屬性

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

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

另請參閱