Adicionar mensagens de usuário para o cmdlet

Artigo
09/24/2021

Os cmdlets podem gravar vários tipos de mensagens que podem ser exibidas ao usuário pelo runtime Windows PowerShell. Essas mensagens incluem os seguintes tipos:

Mensagens detalhadas que contêm informações gerais do usuário.
Mensagens de depuração que contêm informações de solução de problemas.
Mensagens de aviso que contêm uma notificação de que o cmdlet está prestes a executar uma operação que pode ter resultados inesperados.
Mensagens de relatório de progresso que contêm informações sobre quanto trabalho o cmdlet concluiu ao executar uma operação que leva muito tempo.

Não há limites para o número de mensagens que o cmdlet pode gravar ou o tipo de mensagens que o cmdlet grava. Cada mensagem é escrita fazendo uma chamada específica de dentro do método de processamento de entrada do cmdlet.

Definindo o cmdlet

A primeira etapa na criação do cmdlet é sempre nomear o cmdlet e declarar a classe .NET que implementa o cmdlet. Qualquer tipo de cmdlet pode gravar notificações do usuário de seus métodos de processamento de entrada; portanto, em geral, você pode nomear esse cmdlet usando qualquer verbo que indique quais modificações do sistema o cmdlet executa. Para obter mais informações sobre verbos de cmdlet aprovados, consulte Nomes de verbos do cmdlet.

O Stop-Proc cmdlet foi projetado para modificar o sistema; portanto, a declaração System.Management.Automation.CmdletAttribute para a classe .NET deve incluir a palavra-chave attribute e SupportsShouldProcess ser definida como true .

O código a seguir é a definição para essa Stop-Proc de cmdlet. Para obter mais informações sobre essa definição, consulte Criando um cmdlet que modifica o sistema.

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

Definindo parâmetros para modificação do sistema

O Stop-Proc cmdlet define três parâmetros: Name Force , e PassThru . Para obter mais informações sobre como definir esses parâmetros, consulte Criando um cmdlet que modifica o sistema.

Aqui está a declaração de parâmetro para o cmdlet Stop-Proc.

[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;

Substituindo um método de processamento de entrada

O cmdlet deve substituir um método de processamento de entrada, geralmente será System.Management.Automation.Cmdlet.ProcessRecord. Esse Stop-Proc cmdlet substitui o método de processamento de entrada System.Management.Automation.Cmdlet.ProcessRecord. Nesta implementação do cmdlet Stop-Proc, são feitas chamadas para gravar mensagens detalhadas, mensagens de depuração e mensagens de aviso.

Observação

Para obter mais informações sobre como esse método chama os métodos System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue, consulte Criando um cmdletque modifica o sistema.

Escrevendo uma mensagem detalhada

O método System.Management.Automation.Cmdlet.WriteVerbose é usado para gravar informações gerais no nível do usuário que não estão relacionadas a condições de erro específicas. O administrador do sistema pode usar essas informações para continuar processando outros comandos. Além disso, todas as informações escritas usando esse método devem ser localizadas conforme necessário.

O código a seguir deste cmdlet Stop-Proc mostra duas chamadas para o método System.Management.Automation.Cmdlet.WriteVerbose da substituição do método 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);

Escrevendo uma mensagem de depuração

O método System.Management.Automation.Cmdlet.WriteDebug é usado para gravar mensagens de depuração que podem ser usadas para solucionar problemas da operação do cmdlet. A chamada é feita de um método de processamento de entrada.

Observação

Windows PowerShell também define um Debug parâmetro que apresenta informações detalhadas e de depuração. Se o cmdlet dá suporte a esse parâmetro, ele não precisa chamar System.Management.Automation.Cmdlet.WriteDebug no mesmo código que chama System.Management.Automation.Cmdlet.WriteVerbose.

As duas seções de código a seguir do cmdlet Stop-Proc de exemplo mostram chamadas para o método System.Management.Automation.Cmdlet.WriteDebug da substituição do método System.Management.Automation.Cmdlet.ProcessRecord.

Essa mensagem de depuração é escrita imediatamente antes que System.Management.Automation.Cmdlet.ShouldProcess seja chamado.

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

Essa mensagem de depuração é escrita imediatamente antes que System.Management.Automation.Cmdlet.WriteObject seja chamado.

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

Windows PowerShell encaminha automaticamente todas as chamadas System.Management.Automation.Cmdlet.WriteDebug para a infraestrutura de rastreamento e os cmdlets. Isso permite que as chamadas de método sejam rastreadas para o aplicativo de hospedagem, um arquivo ou um depurador sem que você tenha que fazer nenhum trabalho de desenvolvimento extra dentro do cmdlet. A entrada de linha de comando a seguir implementa uma operação de rastreamento.

PS> trace-expression stop-proc -file proc.log -command stop-proc notepad

Escrevendo uma mensagem de aviso

O método System.Management.Automation.Cmdlet.WriteWarning é usado para escrever um aviso quando o cmdlet está prestes a executar uma operação que pode ter um resultado inesperado, por exemplo, a substituição de um arquivo somente leitura.

O código a seguir do cmdlet Stop-Proc exemplo mostra a chamada para o método System.Management.Automation.Cmdlet.WriteWarning da substituição do método System.Management.Automation.Cmdlet.ProcessRecord.

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

Escrevendo uma mensagem de progresso

O System.Management.Automation.Cmdlet.WriteProgress é usado para gravar mensagens de progresso quando as operações de cmdlet levam muito tempo para ser concluídas. Uma chamada para System.Management.Automation.Cmdlet.WriteProgress passa um objeto System.Management.Automation.Progressrecord que é enviado ao aplicativo de hospedagem para renderização para o usuário.

Observação

Esse Stop-Proc cmdlet não inclui uma chamada para o método System.Management.Automation.Cmdlet.WriteProgress.

O código a seguir é um exemplo de uma mensagem de progresso escrita por um cmdlet que está tentando copiar um item.

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);

Exemplo de código

Para o código de exemplo C# completo, consulte StopProcessSample02 Sample.

Definir tipos de objeto e formatação

Windows PowerShell passa informações entre cmdlets usando objetos .NET. Consequentemente, um cmdlet pode precisar definir seu próprio tipo ou o cmdlet pode precisar estender um tipo existente fornecido por outro cmdlet. Para obter mais informações sobre como definir novos tipos ou estender tipos existentes, consulte Estendendo tipos de objeto e formatação.

Criando o cmdlet

Depois de implementar um cmdlet, ele deve ser registrado com Windows PowerShell por meio de Windows PowerShell snap-in. Para obter mais informações sobre como registrar cmdlets, consulte How to Register Cmdlets, Providers, and Host Applications.

Testando o cmdlet

Quando o cmdlet tiver sido registrado com Windows PowerShell, você poderá testá-lo executando-o na linha de comando. Vamos testar o cmdlet Stop-Proc exemplo. Para obter mais informações sobre como usar cmdlets da linha de comando, consulte o Ponto de Partida com Windows PowerShell.

A entrada de linha de comando a seguir usa Stop-Proc para interromper o processo chamado "NOTEPAD", fornecer notificações detalhadas e imprimir informações de depuração.

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

A saída a seguir aparece.

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.