about_Functions_Advanced_Methods

简短说明

描述指定特性的 CmdletBinding 函数如何使用可用于编译的 cmdlet 的方法和属性。

长说明

指定特性的 CmdletBinding 函数可以通过变量访问许多方法和属性 $PSCmdlet 。 这些方法包括以下方法:

  • 编译的 cmdlet 用于执行其工作的输入处理方法。
  • ShouldProcess执行操作之前用于获取用户反馈的方法和ShouldContinue方法。
  • ThrowTerminatingError用于生成错误记录的方法。
  • 返回不同类型的输出的几种 Write 方法。

PSCmdlet 类的所有方法和属性都可用于高级函数。 有关详细信息,请参阅 System.Management.Automation.PSCmdlet

有关属性的详细信息 CmdletBinding ,请参阅 about_Functions_CmdletBindingAttribute。 有关 CmdletBindingAttribute 类,请参阅 System.Management.Automation.Cmdlet.CmdletBindingAttribute

输入处理方法

本节中所述的方法称为输入处理方法。 对于函数,这三种方法由BeginProcess函数的块和End块表示。 无需在函数中使用这些块。

备注

这些块也可用于不使用特性的 CmdletBinding 函数。

开始

此块用于为函数提供可选的一次性预处理。 PowerShell 运行时将此块中的代码一次用于管道中函数的每个实例。

进程

此块用于为函数提供逐条记录处理。 无需定义其他块即可使用 Process 块。 块执行的数量 Process 取决于你如何使用函数以及函数接收的输入。

自动变量 $_$PSItem 包含管道中的当前对象,以便在块中使用 Process 。 自动 $input 变量包含一个枚举器,该枚举器仅适用于函数和脚本块。 有关详细信息,请参阅 about_Automatic_Variables

  • 在管道的开头或外部调用函数将执行一 Process 次块。
  • 在管道中,该 Process 块针对到达函数的每个输入对象执行一次。
  • 如果到达函数的管道输入为空,则 Process不会 执行。
    • Begin仍然执行和End块。

重要

如果函数参数设置为接受管道输入,并且 Process 未定义块,则逐条记录处理将失败。 在这种情况下,无论输入如何,函数仅执行一次。

结束

此块用于为函数提供可选的一次性后处理。

以下示例显示了一个函数的轮廓,该函数包含一 Begin 次性预处理的块、 Process 用于多个记录处理的块,以及一 End 次性后处理的块。

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

备注

使用任一块或End块需要定义所有三个Begin块。 使用所有三个块时,所有 PowerShell 代码都必须位于其中一个块内。

确认方法

ShouldProcess

在函数执行将更改系统的操作之前,调用此方法以请求用户确认。 该函数可以根据方法返回的布尔值继续。 只能从函数块内 Process{} 调用此方法。 该 CmdletBinding 特性还必须声明函数支持 ShouldProcess (,如上一个示例) 所示。

有关此方法的详细信息,请参阅 System.Management.Automation.Cmdlet.ShouldProcess

有关如何请求确认的详细信息,请参阅 “请求确认”。

ShouldContinue

调用此方法以请求第二条确认消息。 当方法返回$trueShouldProcess,应调用它。 有关此方法的详细信息,请参阅 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 属性允许查看正在使用的参数集。 通过参数集,可以创建一个函数,该函数根据运行函数时指定的参数执行不同的任务。

另请参阅