Windows PowerShell 错误记录

2025-03-25

Cmdlet 必须传递 System.Management.Automation.ErrorRecord 对象，该对象标识终止错误和非终止错误的错误条件。

System.Management.Automation.ErrorRecord 对象包含以下信息：

描述错误的异常。通常，这是 cmdlet 捕获并转换为错误记录的异常。每个错误记录都必须包含异常。

如果 cmdlet 未捕获异常，则必须创建新的异常，并选择最能描述错误条件的异常类。但是，无需引发异常，因为它可以通过 System.Management.Automation.ErrorRecord 对象的 System.Management.Automation.ErrorRecord.Exception 属性进行访问。

一个错误标识符，它提供一个目标设计器，可用于诊断目的和 Windows PowerShell 脚本来处理具有特定错误处理程序的特定错误条件。每个错误记录都必须包含错误标识符（请参阅错误标识符）。
一个错误类别，提供可用于诊断目的的常规设计器。每个错误记录都必须指定错误类别（请参阅错误类别）。
可选的替换错误消息和建议的作（请参阅替换错误消息）。
有关引发错误的 cmdlet 的可选调用信息。此信息由 Windows PowerShell 指定（请参阅调用消息）。
发生错误时正在处理的目标对象。这可能是输入对象，也可能是 cmdlet 正在处理的另一个对象。例如，对于命令 Remove-Item -Recurse C:\somedirectory，错误可能是“C：\somedirectory\lockedfile”的 FileInfo 对象的实例。目标对象信息是可选的。

错误标识符

创建错误记录时，请指定一个标识符，该标识符指定 cmdlet 中的错误条件。 Windows PowerShell 将目标标识符与 cmdlet 的名称组合在一起，以创建完全限定的错误标识符。可以通过 System.Management.Automation.ErrorRecord 对象的 System.Management.Automation.ErrorRecord.FullyQualifiedErrorId 属性访问完全限定的错误标识符。错误标识符本身不可用。它仅作为完全限定错误标识符的一部分提供。

创建错误记录时，使用以下准则生成错误标识符：

使错误标识符特定于错误条件。针对诊断目的的错误标识符以及处理具有特定错误处理程序的特定错误条件的脚本。用户应能够使用错误标识符来标识错误及其源。错误标识符还启用针对现有异常中特定错误条件的报告，以便不需要新的异常子类。
通常，将不同的错误标识符分配给不同的代码路径。最终用户受益于特定标识符。通常，调用 System.Management.Automation.Cmdlet.WriteError 或 System.Management.Automation.Cmdlet.ThrowTerminatingError* 的每个代码路径都有自己的标识符。作为规则，在为错误消息定义新的模板字符串时定义新标识符，反之亦然。不要将错误消息用作标识符。
使用特定错误标识符发布代码时，可以使用该标识符为完整的产品支持生命周期建立错误的语义。请勿在语义上不同于原始上下文的上下文中重复使用它。如果此错误的语义发生更改，请创建并使用新标识符。
通常，应仅针对特定 CLR 类型的异常使用特定的错误标识符。如果异常的类型或目标对象的类型发生更改，请创建并使用新标识符。
为错误标识符选择文本，该文本简明对应于所报告的错误。使用标准 .NET Framework 命名和大写约定。请勿使用空格或标点符号。不要本地化错误标识符。
不要以不可重现的方式动态生成错误标识符。例如，不要包含错误信息，例如进程 ID。仅当错误标识符与遇到相同错误条件的其他用户看到的错误标识符相对应时，错误标识符才有用。

错误类别

创建错误记录时，请使用 System.Management.Automation.ErrorCategory 枚举定义的常量之一指定错误类别。当用户将 $ErrorView 变量设置为 "CategoryView"时，Windows PowerShell 使用错误类别显示错误信息。

避免使用 System.Management.Automation.ErrorCategoryNotSpecified 常量。如果你有有关错误或导致错误的作的任何信息，请选择最能描述错误或作的类别，即使该类别不是完美的匹配项。

Windows PowerShell 显示的信息称为类别视图字符串，是从 System.Management.Automation.ErrorCategoryInfo 类的属性生成的。（可通过错误 System.Management.Automation.ErrorRecord.CategoryInfo 属性访问此类。

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

以下列表描述了显示的信息：

类别：Windows PowerShell 定义的 System.Management.Automation.ErrorCategory 常量。
TargetName：默认情况下，cmdlet 在发生错误时正在处理的对象的名称。或者，另一个 cmdlet 定义的字符串。
TargetType：默认情况下，目标对象的类型。或者，另一个 cmdlet 定义的字符串。
活动：默认情况下，创建错误记录的 cmdlet 的名称。或者，其他一些 cmdlet 定义的字符串。
原因：默认情况下，异常类型。或者，另一个 cmdlet 定义的字符串。

替换错误消息

为 cmdlet 开发错误记录时，错误的默认错误消息来自 System.Exception.Message 属性中的默认消息文本。这是一个只读属性，其消息文本仅用于调试目的（根据 .NET Framework 准则）。建议创建一条错误消息来替换或扩充默认消息文本。使消息更加用户友好且更特定于 cmdlet。

替换消息由 System.Management.Automation.ErrorDetails 对象提供。使用此对象的以下构造函数之一，因为它们提供了 Windows PowerShell 可以使用的其他本地化信息。

ErrorDetails（Cmdlet、String、String、Object[]）：如果模板字符串是实现 cmdlet 的同一程序集中的资源字符串，或者如果要通过替代 System.Management.Automation.Cmdlet.GetResourceString 方法加载模板字符串，请使用此构造函数。
ErrorDetails（Assembly， String， String， Object[]）：如果模板字符串位于另一个程序集中，并且您不通过 System.Management.Automation.Cmdlet.GetResourceString重写来加载该构造函数。

替换消息应符合 .NET Framework 设计准则，以编写略有差异的异常消息。准则指出，应为开发人员编写异常消息。应为 cmdlet 用户编写这些替换消息。

必须在调用 System.Management.Automation.Cmdlet.WriteError 或 System.Management.Automation.Cmdlet.ThrowTerminatingError* 方法之前添加替换错误消息。若要添加替换消息，请设置错误记录的 System.Management.Automation.ErrorRecord.ErrorDetails 属性。设置此属性后，Windows PowerShell 将显示 System.Management.Automation.ErrorDetails.Message* 属性，而不是默认消息文本。

建议的作信息

System.Management.Automation.ErrorDetails 对象还可以提供有关发生错误时建议的作的信息。

调用信息

当 cmdlet 使用 System.Management.Automation.Cmdlet.WriteError 或 System.Management.Automation.Cmdlet.ThrowTerminatingError* 报告错误记录时，Windows PowerShell 会自动添加描述发生错误时调用的命令的信息。此信息由 System.Management.Automation.InvocationInfo 对象提供，该对象包含命令调用的 cmdlet 的名称、命令本身以及有关管道或脚本的信息。此属性是只读的。