about_Functions_Advanced_Methods

主题
    about_Functions_Advanced_Methods

简短说明
    说明指定了 CmdletBinding 属性 (attribute) 的函数如何使用可用于已编译 cmdlet 的方法和属
    性 (property)。

详细说明
    指定了 CmdletBinding 属性 (attribute) 的函数可通过 $pscmdlet 变量访问一些方法和属性 
    (property)。这些方法包括：


        - 已编译 cmdlet 执行操作时使用的输入处理方法。

        - ShouldProcess 和 ShouldContinue 方法，用于在执行操作之前获取用户反馈。

        - ThrowTerminatingError 方法，用于生成错误记录。

        - 几种 Write 方法，用于返回不同类型的输出。

        - 几种 Write 方法，用于返回不同类型的输出。


    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 方法，
    "Write 方法"一节中介绍了该方法。如果发生终止错误，函数无法继续执行，则应调用 
    ThrowTerminatingError 方法。此外，还可以对终止错误使用 Throw 语句，对非终止错误使用 
    Write-Error cmdlet。

    有关详细信息，请参阅 MSDN Libray 中的 System.Management.Automation.Cmdlet.
    ThrowTerminatingError，网址为 https://go.microsoft.com/fwlink/?LinkId=142144。


  Write 方法

      函数可调用以下方法以返回不同类型的输出。请注意，并不是所有输出都会传入管道中的下一个命
      令。您也可以使用各种 Write 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.WriteProgr
      ess，网址为 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_Advanced
    about_Functions_CmdletBindingAttributes
    about_Functions_Advanced_Parameters