将非终止错误报告添加到您的 Cmdlet

Cmdlet 可以通过调用 System.Management.Automation.Cmdlet.WriteError 方法报告非终止错误，并且仍然继续对当前输入对象或进一步传入的管道对象进行操作。本部分介绍如何创建一个 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 定义一个 Name 参数，如添加处理命令行输入的参数中所述。

以下是此 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 中给出了此覆盖的详细信息。

报告错误时要记住的事情

cmdlet 在写入错误时传递的 System.Management.Automation.ErrorRecord 对象在其核心需要异常。确定要使用的异常时，请遵循 .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
  

参见

• 添加处理管道输入的参数

• 添加处理命令行输入的参数

• 创建您的第一个 Cmdlet

• 扩展对象类型和格式

• 如何注册 Cmdlet、提供程序和主机应用程序

• Windows PowerShell 参考

• Cmdlet 示例