向 Cmdlet 添加非终止错误报告

2025-03-25

Cmdlet 可以通过调用 System.Management.Automation.Cmdlet.WriteError 方法报告非终止错误，并继续对当前输入对象或进一步传入管道对象进行作。本部分介绍如何创建一个 cmdlet，该 cmdlet 报告其输入处理方法中的非终止错误。

对于非终止错误（以及终止错误），cmdlet 必须传递标识错误的 System.Management.Automation.ErrorRecord 对象。每个错误记录由一个名为“错误标识符”的唯一字符串标识。除了标识符，每个错误的类别由 System.Management.Automation.ErrorCategory 枚举定义的常量指定。通过将 $ErrorView 变量设置为“CategoryView”，用户可以根据其类别查看错误。

有关错误记录的详细信息，请参阅 Windows PowerShell 错误记录。

定义 Cmdlet

cmdlet 创建的第一步始终命名 cmdlet 并声明实现 cmdlet 的 .NET 类。此 cmdlet 检索进程信息，因此此处选择的谓词名称为“Get”。（几乎任何能够检索信息的 cmdlet 都可以处理命令行输入。有关批准的 cmdlet 谓词的详细信息，请参阅 Cmdlet 谓词名称。

下面是此 Get-Proc cmdlet 的定义。创建第一个 Cmdlet中提供了此定义的详细信息。

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

定义参数

如有必要，cmdlet 必须定义用于处理输入的参数。此 Get-Proc cmdlet 定义名称参数，如添加进程 Command-Line 输入的参数中所述。

下面是此 Get-Proc cmdlet Name 参数的参数声明。

[Parameter(
           Position = 0,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true
)]
[ValidateNotNullOrEmpty]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

<Parameter(Position:=0, ValueFromPipeline:=True, _
ValueFromPipelineByPropertyName:=True), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

重写输入处理方法

所有 cmdlet 必须覆盖 System.Management.Automation.Cmdlet 类提供的至少一种输入处理方法。创建第一个 Cmdlet中讨论了这些方法。

注释

cmdlet 应尽可能独立地处理每个记录。

此 Get-Proc cmdlet 重写 System.Management.Automation.Cmdlet.ProcessRecord 方法，以处理用户或脚本提供的输入的 Name 参数。如果未提供名称，此方法将获取每个请求的进程名称或所有进程的进程。创建第一个 Cmdlet中提供了此替代的详细信息。

报告错误时要记住的事项

System.Management.Automation.ErrorRecord 对象，该 cmdlet 在写入错误时需要其核心出现异常。确定要使用的异常时，请遵循 .NET 准则。基本上，如果错误在语义上与现有异常相同，则 cmdlet 应使用该异常或派生自该异常。否则，它应直接从 System.Exception 类派生新的异常或异常层次结构。

创建错误标识符（通过 ErrorRecord 类的 FullyQualifiedErrorId 属性访问）时，请记住以下几点。

使用针对诊断目的的字符串，以便在检查完全限定标识符时，可以确定错误是什么以及错误来自何处。
格式良好的完全限定错误标识符可能如下所示。

CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

请注意，在上一示例中，错误标识符（第一个标记）指定错误是什么，其余部分指示错误来自何处。

对于更复杂的方案，错误标识符可以是可在检查时分析的点分隔标记。这允许你对错误标识符的各个部分以及错误标识符和错误类别进行分支。

该 cmdlet 应将特定的错误标识符分配给不同的代码路径。请牢记以下信息，以分配错误标识符：

错误标识符应在整个 cmdlet 生命周期内保持不变。不要更改 cmdlet 版本之间的错误标识符的语义。
对错误标识符使用文本，该标识符与所报告的错误相对应。请勿使用空格或标点符号。
让 cmdlet 仅生成可重现的错误标识符。例如，它不应生成包含进程标识符的标识符。仅当用户与遇到相同问题的其他用户看到的标识符相对应时，错误标识符才对用户有用。

在以下情况下，PowerShell 不会捕获未经处理的异常：

如果 cmdlet 会创建一个新线程并在该线程中运行的代码引发未经处理的异常，PowerShell 将不会捕获错误并终止进程。
如果对象在其析构函数或 Dispose 方法中具有导致未经处理的异常的代码，PowerShell 将不会捕获错误并终止进程。

报告非终止错误

任何一种输入处理方法都可以使用 System.Management.Automation.Cmdlet.WriteError 方法向输出流报告非终止错误。

下面是此 Get-Proc cmdlet 中的代码示例，该示例演示了从 System.Management.Automation.Cmdlet.ProcessRecord 方法的重写中调用 System.Management.Automation.Cmdlet.WriteError。在这种情况下，如果 cmdlet 找不到指定进程标识符的进程，则调用。

protected override void ProcessRecord()
{
  // If no name parameter passed to cmdlet, get all processes.
  if (processNames == null)
  {
    WriteObject(Process.GetProcesses(), true);
  }
    else
    {
      // If a name parameter is passed to cmdlet, get and write
      // the associated processes.
      // Write a non-terminating error for failure to retrieve
      // a process.
      foreach (string name in processNames)
      {
        Process[] processes;

        try
        {
          processes = Process.GetProcessesByName(name);
        }
        catch (InvalidOperationException ex)
        {
          WriteError(new ErrorRecord(
                     ex,
                     "NameNotFound",
                     ErrorCategory.InvalidOperation,
                     name));
          continue;
        }

        WriteObject(processes, true);
      } // foreach (...
    } // else
  }

关于编写非终止错误的注意事项

对于非终止错误，该 cmdlet 必须为每个特定输入对象生成特定的错误标识符。

cmdlet 经常需要修改由非终止错误生成的 PowerShell作。它可以通过定义 ErrorAction 和 ErrorVariable 参数来执行此作。如果定义 ErrorAction 参数，cmdlet System.Management.Automation.ActionPreference提供用户选项，则还可以通过设置 $ErrorActionPreference 变量直接影响作。

该 cmdlet 可以使用 ErrorVariable 参数将非终止错误保存到变量，该参数不受 ErrorAction设置的影响。通过将加号（+）添加到变量名称的前面，可以向现有错误变量追加失败。

代码示例

有关完整的 C# 示例代码，请参阅 GetProcessSample04 示例。

定义对象类型和格式

PowerShell 使用 .NET 对象在 cmdlet 之间传递信息。因此，cmdlet 可能需要定义自己的类型，或者 cmdlet 可能需要扩展另一个 cmdlet 提供的现有类型。有关定义新类型或扩展现有类型的详细信息，请参阅扩展对象类型和格式。

生成 Cmdlet

实现 cmdlet 后，必须通过 Windows PowerShell 管理单元将其注册到 Windows PowerShell。有关注册 cmdlet 的详细信息，请参阅如何注册 Cmdlet、提供程序和主机应用程序。

测试 Cmdlet

将 cmdlet 注册到 PowerShell 后，可以通过在命令行上运行它来测试它。让我们测试示例 Get-Proc cmdlet 以查看它是否报告错误：

启动 PowerShell，并使用 Get-Proc cmdlet 检索名为“TEST”的进程。

Get-Proc -Name test

将显示以下输出。

Get-Proc : Operation is not valid due to the current state of the object.
At line:1 char:9
+ Get-Proc  <<<< -Name test

通过