Compartilhar via

Adicionar mensagens de usuário para o cmdlet

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

  • Mensagens detalhadas que contêm informações gerais do usuário.

  • Depurar mensagens 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 seu cmdlet pode gravar ou o tipo de mensagens que seu 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 Verbo do Cmdlet.

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

O código a seguir é a definição para esta classe de cmdlet Stop-Proc. 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 cmdlet Stop-Proc define três parâmetros: Name, Forcee PassThru. Para obter mais informações sobre como definir esses parâmetros, consulte Criando um cmdlet que modifica o sistema.

Esta é 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

Seu cmdlet deve substituir um método de processamento de entrada, na maioria das vezes será System.Management.Automation.Cmdlet.ProcessRecord. Esse cmdlet Stop-Proc 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, depurar mensagens 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 métodos, consulte Criando um cmdlet que 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 a partir de um método de processamento de entrada.

Observação

O Windows PowerShell também define um parâmetro Debug que apresenta informações detalhadas e depuração. Se o cmdlet der suporte a esse parâmetro, ele não precisará 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 exemplo Stop-Proc cmdlet 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 é gravada 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 é gravada imediatamente antes que System.Management.Automation.Cmdlet.WriteObject seja chamado.

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

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

do bloco de notas> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc PS

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, substituindo um arquivo somente leitura.

O código a seguir do cmdlet Stop-Proc de 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 demoram muito tempo para serem 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 cmdlet Stop-Proc 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 obter o código de exemplo C# completo, consulte de exemplo StopProcessSample02.

Definir tipos de objeto e formatação

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.

Compilando o cmdlet

Depois de implementar um cmdlet, ele deve ser registrado no Windows PowerShell por meio de um snap-in do Windows PowerShell. Para obter mais informações sobre como registrar cmdlets, consulte Como registrar cmdlets, provedores e aplicativos host.

Testando o cmdlet

Quando o cmdlet tiver sido registrado no Windows PowerShell, você poderá testá-lo executando-o na linha de comando. Vamos testar o cmdlet Stop-Proc de exemplo. Para obter mais informações sobre como usar cmdlets da linha de comando, consulte o Introdução ao 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 é exibida.

    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.

Consulte Também

criar um cmdlet que modifica o sistema

como criar um cmdlet do Windows PowerShell

estendendo tipos de objeto e formatação

como registrar cmdlets, provedores e aplicativos host

do SDK do Windows PowerShell

  • Last updated on