Compartilhar via

Adicionar aliases, expansão de curinga e ajuda a parâmetros de cmdlet

  • Artigo

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

Esse Stop-Proc cmdlet tenta interromper os processos recuperados usando o Get-Proc cmdlet (descrito na criação do 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 adequadamente. Como esse cmdlet interrompe os processos do sistema, ele usa o verbo Stop, definido pela classe System.Management.Automation.Verbslifecycle , com o Proc do substantivo para indicar o processo. Para obter mais informações sobre verbos de cmdlet aprovados, consulte Nomes de Verbo do Cmdlet.

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

[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 dão suporte a modificações do sistema e comentários do usuário. O cmdlet deve definir um parâmetro name ou equivalente para que o cmdlet seja capaz de 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 letra ou 2 letras bem definido para um parâmetro cmdlet. Em ambos os casos, o objetivo de usar aliases é simplificar a entrada do usuário da linha de comando. Windows PowerShell dá suporte a aliases de parâmetro por meio do atributo System.Management.Automation.Aliasattribute, que usa a sintaxe [Alias()]de declaração .

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 runtime 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 comF, o usuário poderá inserirFilename, Filenam, File``Fiou F ainda reconhecer a entrada como o parâmetro FileName.

Criando ajuda para parâmetros

Windows PowerShell permite que você crie a Ajuda para parâmetros de cmdlet. Faça isso para qualquer parâmetro usado para modificação do sistema e comentários do usuário. Para que cada parâmetro dê suporte à Ajuda, você pode definir a palavra-chave do 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 a 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 Stop-Proc cmdlet define a palavra-chave do 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, o cmdlet pode usar as classes System.Management.Automation.WildcardPattern e System.Management.Automation.WildcardOptions para fornecer suporte à expansão curinga para entrada de parâmetro. Exemplos de padrões curinga são lsa*, *.txte [a-c]*. Use o caractere de citação invertida (`) como um caractere de escape quando o padrão contiver um caractere que deve ser usado literalmente.

Expansões curinga de nomes de arquivo e caminho 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 está 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 personalizada de correspondência de padrões curinga raramente. Nesse caso, o cmdlet deve dar suporte à especificação completa posix 1003.2, 3.13 para expansão curinga ou ao seguinte subconjunto simplificado:

  • Ponto de interrogação (?). Corresponde a qualquer caractere no local especificado.
  • Asterisco (*). Corresponde a zero ou mais caracteres começando no local especificado.
  • Colchete aberto ([). Apresenta uma expressão de colchete de padrão que pode conter caracteres ou um intervalo de caracteres. Se um intervalo for necessário, um hífen (-) será usado para indicar o intervalo.
  • Fechar colchete (]). Encerra uma expressão de colchete padrão.
  • Caractere de escape de citação invertida (`). Indica que o próximo caractere deve ser levado literalmente. Lembre-se de que, ao especificar o caractere de citação de fundo da linha de comando (em vez de especificá-lo programaticamente), o caractere de escape de citação de back-quote deve ser especificado duas vezes.

Observação

Para obter mais informações sobre padrões curinga, consulte Suporte a curingas em parâmetros de cmdlet.

O código a seguir mostra como definir opções 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 em C# completo, consulte StopProcessSample03 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 Estender tipos de objeto e formatação.

Criando o Cmdlet

Depois de implementar um cmdlet, ele deve ser registrado com Windows PowerShell por meio de um snap-in 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 com 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 com Windows PowerShell.

  • Inicie 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 aparece.

    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ê é solicitado a fazer isso. A inserção !? apresenta o texto de ajuda associado ao parâmetro.

    PS> Stop-Proc

    A saída a seguir aparece.

    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 entrada a seguir para interromper todos os processos que correspondem ao padrão *note*curinga. Você é solicitado antes de interromper cada processo que corresponda ao padrão.

    PS> Stop-Proc -Name *note*

    A saída a seguir aparece.

    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 aparece.

    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 aparece.

    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

Consulte Também