向 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.WriteVerbose 方法用于编写与特定错误条件无关的常规用户级信息。 然后，系统管理员可以使用该信息继续处理其他命令。 此外，应根据需要本地化使用此方法编写的任何信息。

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

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作问题的调试消息。 调用来自输入处理方法。

示例 Stop-Proc cmdlet 中的以下两个部分代码显示了对 System.Management.Automation.Cmdlet.WriteDebug 方法的调用，方法是从 System.Management.Automation.Cmdlet.ProcessRecord 方法的重写。

在调用 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> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc 记事本

编写警告消息

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 对象，以便向用户呈现。

以下代码是尝试复制项的 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