about_Functions_Advanced_Methods

主題
    about_Functions_Advanced_Methods

簡短描述
    描述指定 CmdletBinding 屬性 (Attribute) 的函數如何使用編譯的 Cmdlet 可用的
    方法及屬性 (Property)。

完整描述
    指定 CmdletBinding 屬性的函數可以透過 $pscmdlet 變數存取數種方法和屬性。這
    些方法包含下列方法：


        - 輸入處理方法，編譯的 Cmdlet 會用這些方法來執行作業。

        - ShouldProcess 和 ShouldContinue 方法，用來先取得使用者意見反應，然後
          再執行動作。

        - ThrowTerminatingError 方法，用來產生錯誤記錄。

        - 數個 Write 方法，用來傳回不同類型的輸出。

        - 數個 Write 方法，用來傳回不同類型的輸出。


    進階函數可以使用 PSCmdlet 類別的所有方法和屬性。如需這些方法和屬性的詳細資訊，
    請參閱 MSDN (Microsoft Developer Network) 文件庫中的＜
    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 文件庫中的＜
      System.Management.Automation.Cmdlet.ShouldProcess＞
      (https://go.microsoft.com/fwlink/?LinkId=142142)(英文)。

      如需如何要求確認的詳細資訊，請參閱 MSDN 文件庫中的＜要求確認＞
      (https://go.microsoft.com/fwlink/?LinkID=136658)(英文)。


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


  錯誤方法

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

    如需詳細資訊，請參閱 MSDN 文件庫中的
    ＜System.Management.Automation.Cmdlet.ThrowTerminatingError＞
    (https://go.microsoft.com/fwlink/?LinkId=142144)(英文)。


  寫入方法

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


    WriteCommandDetail
      如需 WriteCommandDetails 方法的詳細資訊，請參閱 MSDN 文件庫中的＜
      System.Management.Automation.Cmdlet.WriteCommandDetail＞
      (https://go.microsoft.com/fwlink/?LinkId=142155)(英文)。


    WriteDebug
      若要提供可用來為函數疑難排解的資訊，請讓函數呼叫 WriteDebug 方法。這麼做會
      為使用者顯示偵錯訊息。如需詳細資訊，請參閱 MSDN 文件庫中的＜
      System.Management.Automation.Cmdlet.WriteDebug＞
      (https://go.microsoft.com/fwlink/?LinkId=142156)(英文)。


    WriteError
      函數在發生非終止錯誤而且是設計為繼續處理記錄時，應該呼叫這個方法。如需詳細資
      訊，請參閱 MSDN 文件庫中的
      ＜System.Management.Automation.Cmdlet.WriteError＞(https://go.microsoft.com/
      fwlink/?LinkId=142157)(英文)。

      注意：函數在發生終止錯誤時，應該呼叫 ThrowTerminatingError 方法。


    WriteObject
      這個方法可以讓函數將物件傳送給管線中的下一個命令。在大多數的情況中，這就是函
      數在傳回資料時所使用的方法。如需詳細資訊，請參閱  
      MSDN 文件庫中的＜System.Management.Automation.PSCmdlet.WriteObject＞
      (https://go.microsoft.com/fwlink/?LinkId=142158)(英文)。


    WriteProgress
      對於需要花很長時間才能完成動作的函數，使用這個方法可以呼叫 WriteProgress 方
      法以顯示進度資訊。例如，您可以顯示完成的百分比。如需詳細資訊，請參閱  
      MSDN 文件庫中的
      ＜System.Management.Automation.PSCmdlet.WriteProgress＞
      (https://go.microsoft.com/fwlink/?LinkId=142160)(英文)。


    WriteVerbose
      若要提供與函數所執行作業相關的詳細資訊，請讓函數呼叫 WriteVerbose 方法以對
      使用者顯示詳細訊息。預設不會顯示詳細訊息。如需詳細資訊，請參閱 MSDN 文件庫
      中的＜System.Management.Automation.PSCmdlet.WriteVerbose＞
      (https://go.microsoft.com/fwlink/?LinkId=142162) (英文)。

    WriteWarning
      若要提供可能導致未預期結果之條件的相關資訊，請讓函數呼叫 WriteWarning 方法
      以對使用者顯示警告訊息。預設不會顯示警告訊息。
      如需詳細資訊，請參閱 MSDN 文件庫中的
      ＜System.Management.Automation.PSCmdlet.WriteWarning＞
      (https://go.microsoft.com/fwlink/?LinkId=142164) (英文)。

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


  其他的方法和屬性

      如需可透過 $PSCmdlet 變數所存取之其他方法和屬性的詳細資訊，請參閱 MSDN 文件
      庫中的＜System.Management.Automation.PSCmdlet＞
      (https://go.microsoft.com/fwlink/?LinkId=142139) (英文)。

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


請參閱
    about_Functions_Advanced
    about_Functions_CmdletBindingAttributes
    about_Functions_Advanced_Parameters