about_Functions_Advanced_Methods

项目
05/09/2024

简短说明

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

长说明

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

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

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

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

输入处理方法

本部分中介绍的方法称为输入处理方法。对于函数，这三种方法由函数的 Begin、 Process和 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

调用此方法以请求第二条确认消息。当方法返回 $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 变量或使用 Verbose 和 Debug 命令行选项来显示警告消息。有关变量的详细信息 $WarningPreference ，请参阅 about_Preference_Variables。

其他方法和属性

有关可通过变量访问 $PSCmdlet 的其他方法和属性的信息，请参阅 System.Management.Automation.PSCmdlet。

例如， ParameterSetName 属性允许查看正在使用的参数集。参数集允许创建一个函数，该函数根据运行函数时指定的参数执行不同任务。

通过