about_Functions_Advanced_Methods

適用於: Windows PowerShell 2.0, Windows PowerShell 3.0

主題

about_Functions_Advanced_Methods

簡短描述

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

詳細描述

指定 CmdletBinding 屬性的函式可以透過 $pscmdlet 變數存取一些方法和屬性。這些方法包括：

- 已編譯的 Cmdlet 用來執行其工作的輸入處理方法。

- 執行動作之前，用來取得使用者回應的 ShouldProcess 和 ShouldContinue 方法。

- 用於產生錯誤記錄的 ThrowTerminatingError 方法。

- 傳回不同輸出類型的幾種寫入方法。

PSCmdlet 類別的所有方法和屬性都適用於進階函式。如需這些方法和屬性的詳細資訊，請參閱 MSDN (Microsoft Developer Network) Library 中的 System.Management.Automation.PSCmdlet，網址為 https://go.microsoft.com/fwlink/?LinkId=142139。

輸入處理方法

本節所述的方法稱為輸入處理方法。在函式中，這三種方法會以函式的 Begin、Process 和 End 區塊來表示。每個函式都必須包含上述一或多個區塊。Windows PowerShell® 執行階段使用這些區塊中的程式碼來執行函式(這些區塊也適用於不使用 CmdletBinding 屬性的函式)。

Begin

這個區塊可用來提供函式的選擇性一次性前置處理。每次管線中出現函式，Windows PowerShell 執行階段就會使用這個區塊中的程式碼一次。

Process

這個區塊可用來提供函式的依記錄處理。根據函式的輸入，可不限次數的使用這個區塊，或完全不使用。例如，如果函式是管線中的第一個命令，則會使用 Process 區塊一次。如果函式不是管線中的第一個命令，每當函式從管線收到一個輸入，便會使用 Process 區塊一次。如果沒有任何管線輸入，則不會使用 Process 區塊。

如果函式參數設定為接受管線輸入，則必須定義這個區塊。如果未定義這個區塊且參數接受來自管線的輸入，則函式會遺失透過管線傳遞至函式的值。

此外，當函式支援確認要求時 (當 Parameter 屬性的 SupportsShouldProcess 參數設定為 $True 時)，必須從 Process 區塊內部呼叫 ShouldProcess 方法。

End

這個區塊可用來提供函式的選擇性一次性後續處理。

下列範例概述包含用於一次性前置處理的 Begin 區塊、用於處理多筆記錄的 Process 區塊和用於一次性後續處理的 End 區塊之函式。

          Function Test-ScriptCmdlet
          {
            [CmdletBinding(SupportsShouldProcess=$True)] 
            Param ($Parameter1)
            Begin{}
            Process{}
            End{}
          }

確認方法

ShouldProcess

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

如需這個方法的詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.Cmdlet.ShouldProcess，網址為 https://go.microsoft.com/fwlink/?LinkId=142142。

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

ShouldContinue

呼叫這個方法可要求第二個確認訊息。當 ShouldProcess 方法傳回 $true 時，應該呼叫這個方法。如需這個方法的詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.Cmdlet.ShouldContinue，網址為 https://go.microsoft.com/fwlink/?LinkId=142143。

錯誤方法

函式在發生錯誤時會呼叫兩個不同的方法。發生非終止錯誤時，函式應該呼叫 WriteError 方法，＜寫入方法＞一節將進行說明。發生終止錯誤且函式無法繼續時，函式應該呼叫 ThrowTerminatingError 方法。您也可以針對終止錯誤使用 Throw 陳述式，並針對非終止錯誤使用 Write-Error Cmdlet。

如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.Cmdlet.ThrowTerminatingError，網址為 https://go.microsoft.com/fwlink/?LinkId=142144。

寫入方法

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

WriteCommandDetail

如需 WriteCommandDetails 方法的相關資訊，請參閱 MSDN Library 中的 System.Management.Automation.Cmdlet.WriteCommandDetail，網址為 https://go.microsoft.com/fwlink/?LinkId=142155。

WriteDebug

若要提供可用來疑難排解函式的資訊，請讓函式呼叫 WriteDebug 方法。這會對使用者顯示偵錯訊息。如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.Cmdlet.WriteDebug，網址為 https://go.microsoft.com/fwlink/?LinkId=142156。

WriteError

發生非終止錯誤且函式設計成繼續處理記錄時，函式應該呼叫這個方法。如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.Cmdlet.WriteError，網址為 https://go.microsoft.com/fwlink/?LinkId=142157。

注意：

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

WriteObject

這個方法可讓函式將物件傳送至管線中的下一個命令。在大部分情況下，這是函式傳回資料時所要使用的方法。如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.PSCmdlet.WriteObject，網址為 https://go.microsoft.com/fwlink/?LinkId=142158。

WriteProgress

若為需要很長的時間才能完成其動作的函式，這個方法可讓函式呼叫 WriteProgress 方法，以便顯示進度資訊。例如，您可以顯示完成百分比。如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.PSCmdlet.WriteProgress，網址為 https://go.microsoft.com/fwlink/?LinkId=142160。

WriteVerbose

若要提供函式功能的詳細資訊，請讓函式呼叫 WriteVerbose 方法，對使用者顯示詳細訊息。預設不會顯示詳細訊息。如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.PSCmdlet.WriteVerbose，網址為 https://go.microsoft.com/fwlink/?LinkId=142162。

WriteWarning

若要提供可能會造成未預期結果之情況的相關資訊，請讓函式呼叫 WriteWarning 方法，對使用者顯示警告訊息。預設會顯示警告訊息。如需詳細資訊，請參閱 MSDN Library 中的 System.Management.Automation.PSCmdlet.WriteWarning，網址為 https://go.microsoft.com/fwlink/?LinkId=142164。

注意：

您也可以設定 WarningPreference 變數或使用 Verbose 和 Debug 命令列選項，來顯示警告訊息。

其他方法和屬性

如需可透過 $PSCmdlet 變數存取之其他方法和屬性的相關資訊，請參閱 MSDN Library 中的 System.Management.Automation.PSCmdlet，網址為 https://go.microsoft.com/fwlink/?LinkId=142139。

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

另請參閱

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute