Compartilhar via

Adding Aliases, Wildcard Expansion, and Help to Cmdlet Parameters (Adicionar Aliases, Expansão de Carateres Universais e Ajuda a Parâmetros de Cmdlets)

Esta seção descreve como adicionar aliases, expansão curinga e mensagens de Ajuda aos parâmetros do cmdlet Stop-Proc (descrito em Criando um cmdlet que modifica o sistema).

Este Stop-Proc cmdlet tenta interromper processos que são recuperados usando o cmdlet Get-Proc (descrito em Criando seu primeiro 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. Como você está escrevendo um cmdlet para alterar o sistema, ele deve ser nomeado de acordo. Como esse cmdlet interrompe os processos do sistema, ele usa o verbo Stop, definido pela classe System.Management.Automation.VerbsLifecycle, com o substantivo Proc para indicar processo. Para obter mais informações sobre verbos de cmdlet aprovados, consulte Cmdlet Verb Names.

O código a seguir é a definição de classe para este cmdlet Stop-Proc.

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

Definindo parâmetros para modificação do sistema

Seu cmdlet precisa definir parâmetros que ofereçam suporte a modificações do sistema e comentários do usuário. O cmdlet deve definir um Name parâmetro ou equivalente para que o cmdlet possa modificar o sistema por algum tipo de identificador. Além disso, o cmdlet deve definir os parâmetros Force e PassThru. Para obter mais informações sobre esses parâmetros, consulte Criando um cmdlet que modifica o sistema.

Definindo um alias de parâmetro

Um alias de parâmetro pode ser um nome alternativo ou um nome curto de 1 ou 2 letras bem definido para um parâmetro de cmdlet. Em ambos os casos, o objetivo do uso de aliases é simplificar a entrada do usuário a partir da linha de comando. O Windows PowerShell oferece suporte a aliases de parâmetro por meio do atributo System.Management.Automation.AliasAttribute, que usa a sintaxe de declaração [Alias()].

O código a seguir mostra como um alias é adicionado ao parâmetro Name .

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

Além de usar o atributo System.Management.Automation.AliasAttribute, o tempo de execução do Windows PowerShell executa a correspondência parcial de nomes, mesmo que nenhum aliases seja especificado. Por exemplo, se o cmdlet tiver um parâmetro FileName e esse for o único parâmetro que começa com F, o usuário poderá inserir Filename, Filenam, File, Fiou F e ainda reconhecer a entrada como o parâmetro FileName.

Criando ajuda para parâmetros

O Windows PowerShell permite criar a Ajuda para parâmetros de cmdlet. Faça isso para qualquer parâmetro usado para modificação do sistema e feedback do usuário. Para cada parâmetro para oferecer suporte à Ajuda, você pode definir a palavra-chave atributo HelpMessage na declaração de atributo System.Management.Automation.ParameterAttribute. Essa palavra-chave define o texto a ser exibido ao usuário para obter assistência no uso do parâmetro. Você também pode definir o palavra-chave HelpMessageBaseName para identificar o nome base de um recurso a ser usado para a mensagem. Se você definir essa palavra-chave, também deverá definir a palavra-chave HelpMessageResourceId para especificar o identificador de recurso.

O código a seguir deste cmdlet Stop-Proc define a palavra-chave atributo HelpMessage para o parâmetro Name.

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

Substituindo um método de processamento de entrada

Seu cmdlet deve substituir um método de processamento de entrada, na maioria das vezes isso será System.Management.Automation.Cmdlet.ProcessRecord. Ao modificar o sistema, o cmdlet deve chamar os métodos System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue para permitir que o usuário forneça comentários antes que uma alteração seja feita. Para obter mais informações sobre esses métodos, consulte Criando um cmdlet que modifica o sistema.

Suporte à expansão curinga

Para permitir a seleção de vários objetos, seu cmdlet pode usar o System.Management.Automation.WildcardPattern e classes de System.Management.Automation.WildcardOptions para fornecer suporte de expansão curinga para entrada de parâmetros. Exemplos de padrões curinga são lsa*, *.txte [a-c]*. Use o caractere de aspas traseiras (`) como um caractere de escape quando o padrão contém um caractere que deve ser usado literalmente.

Expansões curinga de nomes de arquivos e caminhos são exemplos de cenários comuns em que o cmdlet pode querer permitir suporte para entradas de caminho quando a seleção de vários objetos é necessária. Um caso comum é no sistema de arquivos, onde um usuário deseja ver todos os arquivos que residem na pasta atual.

Você deve precisar de uma implementação de correspondência de padrão curinga personalizada apenas raramente. Nesse caso, seu cmdlet deve oferecer suporte à especificação POSIX 1003.2, 3.13 completa para expansão curinga ou ao seguinte subconjunto simplificado:

  • Ponto de interrogação (?). Corresponde a qualquer caractere no local especificado.
  • Asterisk (*). Corresponde a zero ou mais caracteres a partir do local especificado.
  • Colchete aberto ([). Introduz uma expressão de colchete padrão que pode conter caracteres ou um intervalo de caracteres. Se for necessário um intervalo, um hífen (-) é usado para indicar o intervalo.
  • Fechar parêntesis (]). Termina uma expressão de colchete padrão.
  • Caractere de fuga entre aspas (`). Indica que o próximo caractere deve ser tomado literalmente. Lembre-se de que, ao especificar o caractere de aspas inversas da linha de comando (em vez de especificá-lo programaticamente), o caractere de escape de aspas anteriores deve ser especificado duas vezes.

Observação

Para obter mais informações sobre padrões curinga, consulte Suporte a curingas em Cmdlet Parameters.

O código a seguir mostra como definir opções de curinga e definir o padrão curinga usado para resolver o parâmetro Name para este cmdlet.

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

O código a seguir mostra como testar se o nome do processo corresponde ao padrão curinga definido. Observe que, nesse caso, se o nome do processo não corresponder ao padrão, o cmdlet continuará a obter o próximo nome do processo.

if (!wildcard.IsMatch(processName))
{
  continue;
}

Exemplo de código

Para obter o código de exemplo C# completo, consulte Exemplo de StopProcessSample03.

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.

  • Inicie o Windows PowerShell e use Stop-Proc para interromper um processo usando o alias ProcessName para o parâmetro Name.

    PS> Stop-Proc -ProcessName notepad

    A saída a seguir é exibida.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (3496)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

  • Faça a seguinte entrada na linha de comando. Como o parâmetro Name é obrigatório, você será solicitado a fornecê-lo. Inserir !? exibe o texto de ajuda associado ao parâmetro.

    PS> Stop-Proc

    A saída a seguir é exibida.

    Cmdlet Stop-Proc at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
Name[0]: !?
The name of one or more processes to stop. Wildcards are permitted.
Name[0]: notepad

  • Agora faça a seguinte entrada para parar todos os processos que correspondem ao padrão curinga *note*. Você será solicitado antes de parar cada processo que corresponde ao padrão.

    PS> Stop-Proc -Name *note*

    A saída a seguir é exibida.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (1112)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

    A saída a seguir é exibida.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTEM (3712)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

    A saída a seguir é exibida.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTE (3592)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

Ver também

  • Last updated on