Cmdlet 错误报告

Cmdlet 应根据错误是终止错误还是非终止错误以不同方式报告错误。终止错误是导致管道立即终止的错误，或者是没有理由继续处理时发生的错误。非终止错误是报告当前错误情况的错误，但 cmdlet 可以继续处理输入对象。对于非终止错误，通常会通知用户出现问题，但 cmdlet 会继续处理下一个输入对象。

除非另有说明，本文档中提到的所有类和方法都来自 System.Management.Automation 命名空间。

终止和非终止错误

以下准则可用于确定错误条件是终止错误还是非终止错误。

• 错误情况是否会阻止您的 cmdlet 成功处理任何进一步的输入对象？如果是这样，则这是一个终止错误。

• 错误条件是否与特定输入对象或输入对象的子集相关？如果是这样，这是一个非终止错误。

• 该 cmdlet 是否接受多个输入对象，以便在另一个输入对象上进行处理可以成功？如果是这样，这是一个非终止错误。

• 可以接受多个输入对象的 Cmdlet 应该决定什么是终止错误和非终止错误，即使特定情况仅适用于单个输入对象也是如此。

• Cmdlet 可以接收任意数量的输入对象，并在引发终止异常之前发送任意数量的成功或错误对象。接收到的输入对象的数量与发送的成功和错误对象的数量之间没有关系。

• 只能接受 0-1 个输入对象并仅生成 0-1 个输出对象的 Cmdlet 应将错误视为终止错误并生成终止异常。

报告非终止错误

非终止错误的报告应始终在以下方法的 cmdlet 实现中完成：

• Cmdlet.BeginProcessing
• Cmdlet.ProcessRecord
• Cmdlet.EndProcessing

这些类型的错误是通过调用 Cmdlet.WriteError 方法来报告的，该方法又将错误记录发送到错误流。

报告终止错误

通过引发异常或调用 Cmdlet.ThrowTerminateError 方法来报告终止错误。请注意，cmdlet 还可以捕获并重新抛出异常，例如 OutOfMemory，但是，它们不需要重新抛出异常，因为 PowerShell 运行时也会捕获它们。

您还可以针对特定于您的情况的问题定义自己的例外，或使用其错误记录向现有例外添加附加信息。

错误记录

PowerShell 使用 ErrorRecord 对象描述非终止错误条件。每个对象都提供错误类别信息、可选目标对象以及有关错误条件的详细信息。

错误标识符

错误标识符是一个简单的字符串，用于标识 cmdlet 内的错误情况。 PowerShell 将此标识符与 cmdlet 标识符相结合，创建一个完全限定的错误标识符，稍后可以在过滤错误流或记录错误、响应特定错误或执行其他用户特定活动时使用。

指定错误标识符时应遵循以下准则：

• 将不同的、高度特定的错误标识符分配给不同的代码路径。每个调用 Cmdlet.WriteError 或 Cmdlet.ThrowTerminateError 的代码路径都应该有自己的错误标识符。

• 对于终止错误和非终止错误，错误标识符对于公共语言运行时 (CLR) 异常类型应该是唯一的。

• 不要更改 cmdlet 或 PowerShell 提供程序版本之间的错误标识符的语义。建立错误标识符的语义后，它应该在 cmdlet 的整个生命周期中保持不变。

• 对于终止错误，请使用特定 CLR 异常类型的唯一错误标识符。如果异常类型发生更改，请使用新的错误标识符。

• 对于非终止错误，请对特定输入对象使用特定错误标识符。

• 选择与所报告的错误简洁对应的标识符文本。不要使用空格或标点符号。

• 不要生成不可重现的错误标识符。例如，不要生成包含进程标识符的标识符。仅当错误标识符与遇到相同问题的其他用户看到的标识符相对应时，错误标识符才有用。

错误类别

错误类别用于为用户对错误进行分组。 PowerShell 定义了这些类别，并且 cmdlet 和 PowerShell 提供程序在生成错误记录时必须在它们之间进行选择。

有关可用错误类别的说明，请参阅 ErrorCategory 枚举。一般来说，您应该尽可能避免使用 NoError、UndefinedError 和 GenericError。

当用户将$ErrorView设置为CategoryView时，用户可以根据类别查看错误。

参见

• Cmdlet 概述

• Cmdlet 输出的类型

• Windows PowerShell 参考