终止错误

本主题讨论用于报告终止错误的方法。它还讨论了如何从 cmdlet 内调用该方法，并讨论了调用该方法时 Windows PowerShell 运行时可以返回的异常。

当发生终止错误时，cmdlet 应通过调用 System.Management.Automation.Cmdlet.Throwterminationerror* 方法来报告错误。此方法允许 cmdlet 发送描述导致终止错误的条件的错误记录。有关错误记录的详细信息，请参阅 Windows PowerShell 错误记录。

当调用 System.Management.Automation.Cmdlet.Throwterminateerror* 方法时，Windows PowerShell 运行时永久停止管道的执行并引发 System.Management.Automation.PipelinestoppedException 异常。任何后续尝试调用 System.Management.Automation.Cmdlet.WriteObject、System.Management.Automation.Cmdlet.WriteError 或多个其他 API 都会导致这些调用引发 System.Management.Automation.PipelinestoppedException 异常。

如果管道中的另一个 cmdlet 报告终止错误、用户要求停止管道或者管道因任何原因在完成之前停止，也可能会发生 System.Management.Automation.PipelinestoppedException 异常。 cmdlet 不需要捕获 System.Management.Automation.PipelinestoppedException 异常，除非它必须清理打开的资源或其内部状态。

在报告终止错误之前，Cmdlet 可以写入任意数量的输出对象或非终止错误。但是，终止错误会永久停止管道，并且不会报告进一步的输出、终止错误或非终止错误。

Cmdlet 只能从调用 System.Management.Automation.Cmdlet.BeginProcessing、System.Management.Automation.Cmdlet.ProcessRecord 或 System.Management.Automation.Cmdlet.EndProcessing 的线程调用 System.Management.Automation.Cmdlet.Throwterminateerror*输入处理方法。不要尝试从另一个线程调用 System.Management.Automation.Cmdlet.Throwterminateerror* 或 System.Management.Automation.Cmdlet.WriteError。相反，错误必须被传送回主线程。

cmdlet 可能会在 System.Management.Automation.Cmdlet.BeginProcessing、System.Management.Automation.Cmdlet.ProcessRecord 或 System.Management.Automation.Cmdlet.EndProcessing 方法的实现中引发异常。从这些方法引发的任何异常（除了一些停止 Windows PowerShell 主机的严重错误情况外）都会被解释为终止错误，该错误会停止管道，但不会停止整个 Windows PowerShell。 （这仅适用于主 cmdlet 线程。在 cmdlet 生成的线程中未捕获的异常，通常会停止 Windows PowerShell 主机。）我们建议您使用 System.Management.Automation.Cmdlet.Throwterminateerror* 而不是引发异常，因为错误记录提供有关错误情况的附加信息，这对最终用户很有用。 Cmdlet 应遵守托管代码指南，防止捕获和处理所有异常 (catch (Exception e))。仅将已知和预期类型的异常转换为错误记录。

参见

系统.管理.自动化.Cmdlet.BeginProcessing

系统.管理.自动化.Cmdlet.EndProcessing

系统.管理.自动化.Cmdlet.ProcessRecord

系统.管理.自动化.管道停止异常

System.Management.Automation.Cmdlet.Throwterminationerror*

System.Management.Automation.Cmdlet.WriteError

Windows PowerShell 错误记录

编写 Windows PowerShell Cmdlet