将用户消息添加到您的 Cmdlet

Cmdlet 可以编写多种可由 Windows PowerShell 运行时向用户显示的消息。这些消息包括以下类型：

• 包含一般用户信息的详细消息。

• 包含故障排除信息的调试消息。

• 警告消息，其中包含 cmdlet 将要执行可能产生意外结果的操作的通知。

• 进度报告消息，其中包含有关 cmdlet 在执行需要很长时间的操作时已完成多少工作的信息。

cmdlet 可以写入的消息数量或 cmdlet 写入的消息类型没有限制。每条消息都是通过在 cmdlet 的输入处理方法中进行特定调用来写入的。

定义 Cmdlet

创建 cmdlet 的第一步始终是命名 cmdlet 并声明实现该 cmdlet 的 .NET 类。任何类型的 cmdlet 都可以通过其输入处理方法编写用户通知；因此，一般来说，您可以使用任何指示 cmdlet 执行的系统修改的动词来命名此 cmdlet。有关批准的 cmdlet 动词的详细信息，请参阅 Cmdlet 动词名称。

Stop-Proc cmdlet 旨在修改系统；因此，.NET 类的 System.Management.Automation.CmdletAttribute 声明必须包含 SupportsShouldProcess 属性关键字并设置为 true。

以下代码是此 Stop-Proc cmdlet 类的定义。有关此定义的详细信息，请参阅创建修改系统的 Cmdlet。

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

定义系统修改参数

Stop-Proc cmdlet 定义三个参数：Name、Force 和 PassThru。有关定义这些参数的详细信息，请参阅创建修改系统的 Cmdlet。

以下是 Stop-Proc cmdlet 的参数声明。

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

/// <summary>
/// Specify the Force parameter that allows the user to override
/// the ShouldContinue call to force the stop operation. This
/// parameter should always be used with caution.
/// </summary>
[Parameter]
public SwitchParameter Force
{
  get { return force; }
  set { force = value; }
}
private bool force;

/// <summary>
/// Specify the PassThru parameter that allows the user to specify
/// that the cmdlet should pass the process object down the pipeline
/// after the process has been stopped.
/// </summary>
[Parameter]
public SwitchParameter PassThru
{
  get { return passThru; }
  set { passThru = value; }
}
private bool passThru;

重写输入处理方法

您的 cmdlet 必须重写输入处理方法，最常见的是 System.Management.Automation.Cmdlet.ProcessRecord。此 Stop-Proc cmdlet 重写 System.Management.Automation.Cmdlet.ProcessRecord 输入处理方法。在此 Stop-Proc cmdlet 的实现中，进行调用以写入详细消息、调试消息和警告消息。

笔记

有关此方法如何调用 System.Management.Automation.Cmdlet.ShouldProcess 和 System.Management.Automation.Cmdlet.ShouldContinue 方法的详细信息，请参阅创建修改系统的 Cmdlet。

编写详细消息

System.Management.Automation.Cmdlet.WriteVerbose 方法用于写入与特定错误条件无关的常规用户级信息。然后系统管理员可以使用该信息继续处理其他命令。此外，使用此方法编写的任何信息都应根据需要进行本地化。

此 Stop-Proc cmdlet 中的以下代码显示了从 System.Management.Automation.Cmdlet.ProcessRecord 方法的重写中对 System.Management.Automation.Cmdlet.WriteVerbose 方法的两次调用。

message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);

message = String.Format("Stopped process \"{0}\", pid {1}.",
                        processName, process.Id);

WriteVerbose(message);

编写调试消息

System.Management.Automation.Cmdlet.WriteDebug 方法用于写入可用于排除 cmdlet 操作故障的调试消息。该调用是通过输入处理方法进行的。

笔记

Windows PowerShell 还定义了一个Debug 参数，用于显示详细信息和调试信息。如果您的 cmdlet 支持此参数，则不需要在调用 System.Management.Automation.Cmdlet.WriteVerbose 的同一代码中调用 System.Management.Automation.Cmdlet.WriteDebug。

示例 Stop-Proc cmdlet 中的以下两段代码显示了通过重写 System.Management.Automation.Cmdlet.ProcessRecord 方法对 System.Management.Automation.Cmdlet.WriteDebug 方法的调用。

此调试消息是在调用 System.Management.Automation.Cmdlet.ShouldProcess 之前立即写入的。

message =
          String.Format("Acquired name for pid {0} : \"{1}\"",
                       process.Id, processName);
WriteDebug(message);

此调试消息是在调用 System.Management.Automation.Cmdlet.WriteObject 之前立即写入的。

message =
         String.Format("Writing process \"{0}\" to pipeline",
         processName);
WriteDebug(message);
WriteObject(process);

Windows PowerShell 自动将任何 System.Management.Automation.Cmdlet.WriteDebug 调用路由到跟踪基础结构和 cmdlet。这允许将方法调用跟踪到托管应用程序、文件或调试器，而无需在 cmdlet 中执行任何额外的开发工作。以下命令行条目实现跟踪操作。

PS>跟踪表达式stop-proc -file proc.log -command stop-proc notepad

编写警告消息

System.Management.Automation.Cmdlet.WriteWarning 方法用于在 cmdlet 即将执行可能产生意外结果的操作（例如覆盖只读文件）时写入警告。

示例 Stop-Proc cmdlet 中的以下代码显示了从 System.Management.Automation.Cmdlet.ProcessRecord 方法的重写中对 System.Management.Automation.Cmdlet.WriteWarning 方法的调用。

 if (criticalProcess)
 {
   message =
             String.Format("Stopping the critical process \"{0}\".",
                           processName);
   WriteWarning(message);
} // if (criticalProcess...

编写进度消息

System.Management.Automation.Cmdlet.WriteProgress 用于在 cmdlet 操作需要较长时间才能完成时写入进度消息。对 System.Management.Automation.Cmdlet.WriteProgress 的调用会传递一个 System.Management.Automation.Progressrecord 对象，该对象被发送到托管应用程序以呈现给用户。

笔记

此 Stop-Proc cmdlet 不包含对 System.Management.Automation.Cmdlet.WriteProgress 方法的调用。

以下代码是由尝试复制项目的 cmdlet 编写的进度消息的示例。

int myId = 0;
string myActivity = "Copy-item: Copying *.* to c:\abc";
string myStatus = "Copying file bar.txt";
ProgressRecord pr = new ProgressRecord(myId, myActivity, myStatus);
WriteProgress(pr);

pr.RecordType = ProgressRecordType.Completed;
WriteProgress(pr);

代码示例

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

定义对象类型和格式

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

构建 Cmdlet

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

测试 Cmdlet

当您的 cmdlet 已注册到 Windows PowerShell 后，您可以通过在命令行上运行它来测试它。让我们测试示例 Stop-Proc cmdlet。有关从命令行使用 cmdlet 的详细信息，请参阅 Windows PowerShell 入门。

• 以下命令行条目使用 Stop-Proc 停止名为“NOTEPAD”的进程，提供详细通知并打印调试信息。

  PS> stop-proc -Name notepad -Verbose -Debug
  

  将出现以下输出。

  VERBOSE: Attempting to stop process " notepad ".
  DEBUG: Acquired name for pid 5584 : "notepad"
  
  Confirm
  Continue with this operation?
  [Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"): Y
  
  Confirm
  Are you sure you want to perform this action?
  Performing operation "stop-proc" on Target "notepad (5584)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  VERBOSE: Stopped process "notepad", pid 5584.
  

参见

创建修改系统的 Cmdlet

如何创建 Windows PowerShell Cmdlet

扩展对象类型和格式

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

Windows PowerShell SDK