Windows PowerShell 错误记录

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.Throwterminateerror* 的每个代码路径都有其自己的标识符。通常，在为错误消息定义新模板字符串时定义新标识符，反之亦然。不要使用错误消息作为标识符。

• 当您使用特定错误标识符发布代码时，您可以使用该标识符为整个产品支持生命周期建立错误语义。不要在语义上与原始上下文不同的上下文中重用它。如果此错误的语义发生变化，请创建并使用新的标识符。

• 通常，您应该仅对特定 CLR 类型的异常使用特定的错误标识符。如果异常的类型或目标对象的类型发生变化，则创建并使用新的标识符。

• 选择与您报告的错误相对应的错误标识符文本。使用标准 .NET Framework 命名和大小写约定。不要使用空格或标点符号。不要本地化错误标识符。

• 不要以不可重现的方式动态生成错误标识符。例如，不要合并进程 ID 等错误信息。仅当错误标识符与遇到相同错误情况的其他用户看到的错误标识符相对应时，错误标识符才有用。

错误类别

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

避免使用 System.Management.Automation.ErrorCategory NotSpecified 常量。如果您有有关错误或导致错误的操作的任何信息，请选择最能描述错误或操作的类别，即使该类别并非完美匹配。

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.ErrorDetails(Cmdlet) 来加载模板字符串，请使用此构造函数。 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.Throwterminationerror* 方法之前添加替换错误消息。要添加替换消息，请设置错误记录的 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.Throwterminateerror* 报告错误记录时，Windows PowerShell 会自动添加描述错误发生时调用的命令的信息。此信息由 System.Management.Automation.Inspirationinfo 对象提供，该对象包含命令调用的 cmdlet 的名称、命令本身以及有关管道或脚本的信息。该属性是只读的。

参见

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.Throwterminationerror*

系统.管理.自动化.错误类别

系统.管理.自动化.错误类别信息

系统.管理.自动化.错误记录

系统.管理.自动化.错误详细信息

系统.管理.自动化.调用信息

Windows PowerShell 错误报告

编写 Windows PowerShell Cmdlet