Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Os cmdlets podem escrever vários tipos de mensagens que podem ser exibidas ao usuário pelo tempo de execução do Windows PowerShell. Essas mensagens incluem os seguintes tipos:
Mensagens detalhadas que contêm informações gerais do usuário.
Depurar mensagens que contenham 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 escrever ou para o tipo de mensagens que seu cmdlet grava. Cada mensagem é gravada 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 a partir 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 Cmdlet Verb Names.
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 SupportsShouldProcess attribute e ser definida como true.
O código a seguir é a definição para essa 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.
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
Seu cmdlet deve substituir um método de processamento de entrada, na maioria das vezes ele será System.Management.Automation.Cmdlet.ProcessRecord. Este cmdlet Stop-Proc substitui o método de processamento de entrada System.Management.Automation.Cmdlet.ProcessRecord. Nesta implementação do cmdlet Stop-Proc, as chamadas são feitas para escrever 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 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, qualquer informação escrita usando este método deve ser localizada conforme necessário.
O código a seguir desse 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 escrever mensagens de depuração que podem ser usadas para solucionar problemas de 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 de depuração. Se o cmdlet oferecer 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 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 é gravada imediatamente antes System.Management.Automation.Cmdlet.ShouldProcess é chamado.
message =
String.Format("Acquired name for pid {0} : \"{1}\"",
process.Id, processName);
WriteDebug(message);
Essa mensagem de depuração é gravada imediatamente antes de System.Management.Automation.Cmdlet.WriteObject ser chamado.
message =
String.Format("Writing process \"{0}\" to pipeline",
processName);
WriteDebug(message);
WriteObject(process);
O Windows PowerShell roteia automaticamente qualquer chamadas de System.Management.Automation.Cmdlet.WriteDebug 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 seguinte entrada de linha de comando implementa uma operação de rastreamento.
PS> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc bloco de notas
Escrever 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, substituir 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...
Escrever uma mensagem de progresso
O System.Management.Automation.Cmdlet.WriteProgress é usado para gravar mensagens de progresso quando as operações do cmdlet levam 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 ao usuário.
Observação
Este 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 obter o código de exemplo C# completo, consulte Exemplo de 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 formatando.
Criando 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 seu cmdlet tiver sido registrado no Windows PowerShell, você poderá testá-lo executando-o na linha de comando. Vamos testar o exemplo Stop-Proc cmdlet. Para obter mais informações sobre como usar cmdlets da linha de comando, consulte o Introdução ao Windows PowerShell.
A seguinte entrada de linha de comando usa Stop-Proc para parar o processo chamado "NOTEPAD", fornecer notificações detalhadas e imprimir informações de depuração.
PS> Stop-Proc -Name notepad -Verbose -DebugA 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.
Ver também
Criar um cmdlet que modifica o sistema
Como criar um cmdlet do Windows PowerShell
Estendendo tipos de objeto e formatação
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
