Criar um cmdlet sem parâmetros

Esta seção descreve como criar um cmdlet que recupera informações do computador local sem o uso de parâmetros e, em seguida, grava as informações no pipeline. O cmdlet descrito aqui é um cmdlet Get-Proc que recupera informações sobre os processos do computador local e, em seguida, exibe essas informações na linha de comando.

Observação

lembre-se de que, ao escrever cmdlets, o Windows PowerShell® assemblies de referência são baixados no disco (por padrão, em C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Eles não são instalados no GAC (cache de assembly global).

Nomeando o cmdlet

Um nome de cmdlet consiste em um verbo que indica a ação que o cmdlet usa e um substantivo que indica os itens que o cmdlet atua. Como esse cmdlet de Get-Proc de exemplo recupera objetos de processo, ele usa o verbo "Get", definido pela enumeração System. Management. Automation. Verbscommon e o substantivo "proc" para indicar que o cmdlet funciona em itens de processo.

Ao nomear cmdlets, não use nenhum dos seguintes caracteres: #, () {} [] &-/\ $;: "' <> | ? @ ` .

Escolhendo um substantivo

Você deve escolher um substantivo específico. É melhor usar um substantivo singular prefixado com uma versão reduzida do nome do produto. Um exemplo de nome de cmdlet desse tipo é " Get-SQLServer ".

Escolhendo um verbo

Você deve usar um verbo do conjunto de nomes de verbo de cmdlet aprovados. Para obter mais informações sobre os verbos de cmdlet aprovados, consulte nomes de verbo de cmdlet.

Definindo a classe do cmdlet

Depois de escolher um nome de cmdlet, defina uma classe .NET para implementar o cmdlet. Aqui está a definição de classe para este exemplo de Get-Proc cmdlet:

[Cmdlet(VerbsCommon.Get, "Proc")]
  public class GetProcCommand : Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Observe que, antes da definição de classe, o atributo System. Management. Automation. CmdletAttribute , com a sintaxe [Cmdlet(verb, noun, ...)] , é usado para identificar essa classe como um cmdlet. esse é o único atributo necessário para todos os cmdlets e permite que o tempo de execução de Windows PowerShell os chame corretamente. Você pode definir palavras-chave de atributo para declarar ainda mais a classe, se necessário. Lembre-se de que a declaração de atributo para nossa classe GetProcCommand de exemplo declara apenas os nomes de substantivo e verbo para o cmdlet Get-Proc.

Observação

para todas as classes de atributo de Windows PowerShell, as palavras-chave que você pode definir correspondem às propriedades da classe de atributo.

Ao nomear a classe do cmdlet, é uma prática recomendada refletir o nome do cmdlet no nome da classe. Para fazer isso, use o formato "VerbNounCommand" e substitua "verbo" e "substantivo" pelo verbo e pelo substantivo usados no nome do cmdlet. Como é mostrado na definição de classe anterior, o cmdlet de Get-Proc de exemplo define uma classe chamada GetProcCommand, que deriva da classe base System. Management. Automation. cmdlet .

Importante

se você quiser definir um cmdlet que acessa o tempo de execução do Windows PowerShell diretamente, sua classe do .net deve derivar da classe base System. Management. Automation. PSCmdlet . Para obter mais informações sobre essa classe, consulte criando um cmdlet que define conjuntos de parâmetros.

Observação

A classe de um cmdlet deve ser explicitamente marcada como pública. as Classes que não estiverem marcadas como públicas usarão como padrão o interno e não serão encontradas pelo tempo de execução Windows PowerShell.

Windows PowerShell usa o namespace Microsoft. PowerShell. commands para suas classes de cmdlet. É recomendável posicionar suas classes de cmdlet em um namespace de comandos do seu namespace de API, por exemplo, XXX. PS. Commands.

Substituindo um método de processamento de entrada

A classe System. Management. Automation. cmdlet fornece três métodos principais de processamento de entrada, pelo menos um dos quais seu cmdlet deve substituir. para obter mais informações sobre como Windows PowerShell processa registros, consulte como o Windows PowerShell funciona.

para todos os tipos de entrada, o tempo de execução do Windows PowerShell chama System. Management. Automation. Cmdlet. BeginProcessing para habilitar o processamento. Se o cmdlet precisar executar algum pré-processamento ou configuração, ele poderá fazer isso substituindo esse método.

Observação

Windows PowerShell usa o termo "registro" para descrever o conjunto de valores de parâmetro fornecidos quando um cmdlet é chamado.

Se o cmdlet aceitar a entrada do pipeline, ele deverá substituir o método System. Management. Automation. cmdlet. ProcessRecord e, opcionalmente, o método System. Management. Automation. cmdlet. endprocessor . Por exemplo, um cmdlet poderá substituir os dois métodos se ele reunir todas as entradas usando System. Management. Automation. cmdlet. ProcessRecord e, em seguida, operar na entrada como um elemento inteiro, em vez de um Element de cada vez, como o Sort-Object cmdlet faz.

Se o cmdlet não receber a entrada do pipeline, ele deverá substituir o método System. Management. Automation. cmdlet. Endprocessor . Lembre-se de que esse método é usado frequentemente no lugar de System. Management. Automation. cmdlet. BeginProcessing quando o cmdlet não pode operar em um elemento por vez, como é o caso de um cmdlet de classificação.

Como este cmdlet de Get-Proc de exemplo deve receber a entrada do pipeline, ele substitui o método System. Management. Automation. cmdlet. ProcessRecord e usa as implementações padrão para System. Management. Automation. cmdlet. BeginProcessing e System. Management. Automation. cmdlet. noprocessing. A substituição System. Management. Automation. cmdlet. ProcessRecord recupera os processos e os grava na linha de comando usando o método System. Management. Automation. cmdlet. WriteObject .

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}

Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

Coisas a serem lembradas sobre o processamento de entrada

• A fonte padrão de entrada é um objeto explícito (por exemplo, uma cadeia de caracteres) fornecido pelo usuário na linha de comando. Para obter mais informações, consulte criando um cmdlet para processar a entrada de linha de comando.

• Um método de processamento de entrada também pode receber entrada do objeto de saída de um cmdlet upstream no pipeline. Para obter mais informações, consulte criando um cmdlet para processar a entrada do pipeline. Lembre-se de que o cmdlet pode receber entrada de uma combinação de fontes de linha de comando e de pipeline.

• O cmdlet downstream pode não retornar por muito tempo ou não deve ser retornado. Por esse motivo, o método de processamento de entrada em seu cmdlet não deve manter bloqueios durante chamadas para System. Management. Automation. cmdlet. WriteObject, especialmente bloqueios para os quais o escopo se estende além da instância do cmdlet.

Importante

Os cmdlets devem nunca chamar System. console. WriteLine * ou seu equivalente.

• Seu cmdlet pode ter variáveis de objeto para limpeza quando termina o processamento (por exemplo, se abrir um identificador de arquivo no método System. Management. Automation. cmdlet. BeginProcessing e manter o identificador aberto para uso por System. Management. Automation. cmdlet. ProcessRecord). é importante lembrar que o tempo de execução de Windows PowerShell nem sempre chama o método System. Management. Automation. Cmdlet. endprocessing , que deve executar a limpeza de objeto.

Por exemplo, System. Management. Automation. cmdlet. endprocesso não poderá ser chamado se o cmdlet for cancelado no Midway ou se um erro de encerramento ocorrer em qualquer parte do cmdlet. Portanto, um cmdlet que exige a limpeza de objeto deve implementar o padrão System. IDisposable completo, incluindo o finalizador, para que o tempo de execução possa chamar o System. Management. Automation. cmdlet. endprocessor e System. IDisposable. Dispose * no final do processamento.

Exemplo de código

Para obter o código de exemplo completo em C#, consulte exemplo de GetProcessSample01.

Definindo tipos de objeto e formatação

Windows PowerShell passa informações entre os 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, você deve registrá-lo com Windows PowerShell por meio de um snap-in de Windows PowerShell. Para obter mais informações sobre como registrar cmdlets, consulte como registrar cmdlets, provedores e aplicativos de host.

Testando o cmdlet

quando o cmdlet tiver sido registrado com Windows PowerShell, você poderá testá-lo executando-o na linha de comando. o código para nosso cmdlet de Get-Proc de exemplo é pequeno, mas ele ainda usa o tempo de execução Windows PowerShell e um objeto .net existente, o que é suficiente para torná-lo útil. Vamos testá-lo para entender melhor o que Get-Proc pode fazer e como sua saída pode ser usada. Para obter mais informações sobre como usar cmdlets na linha de comando, consulte a introdução com Windows PowerShell.

1. inicie o Windows PowerShell e obtenha os processos atuais em execução no computador.

   get-proc
   

   A saída a seguir aparece.

   Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
   -------  ------  -----  -----  -----  ------  --   ----------
   254      7       7664   12048  66     173.75  1200  QCTRAY
   32       2       1372   2628   31       0.04  1860  DLG
   271      6       1216   3688   33       0.03  3816  lg
   27       2       560    1920   24       0.01  1768  TpScrex
   ...
   

2. Atribua uma variável aos resultados do cmdlet para facilitar a manipulação.

   $p=get-proc
   

3. Obter o número de processos.

   $p.length
   

   A saída a seguir aparece.

   63
   

4. Recuperar um processo específico.

   $p[6]
   

   A saída a seguir aparece.

   Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id    ProcessName
   -------  ------  -----  -----  -----  ------  --    -----------
   1033     3       2400   3336   35     0.53    1588  rundll32
   

5. Obtenha a hora de início desse processo.

   $p[6].starttime
   

   A saída a seguir aparece.

   Tuesday, July 26, 2005 9:34:15 AM
   

   $p[6].starttime.dayofyear
   

   207
   

6. Obtenha os processos para os quais a contagem de identificador é maior que 500 e Classifique o resultado.

   $p | Where-Object {$_.HandleCount -gt 500 } | Sort-Object HandleCount
   

   A saída a seguir aparece.

   Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
   -------  ------  -----  -----  -----  ------  --   ----------
   568      14      2164   4972   39     5.55    824  svchost
   716       7      2080   5332   28    25.38    468  csrss
   761      21      33060  56608  440  393.56    3300 WINWORD
   791      71      7412   4540   59     3.31    492  winlogon
   ...
   

7. Use o Get-Member cmdlet para listar as propriedades disponíveis para cada processo.

   $p | Get-Member -MemberType property
   

       TypeName: System.Diagnostics.Process
   

   A saída a seguir aparece.

   Name                     MemberType Definition
   ----                     ---------- ----------
   BasePriority             Property   System.Int32 BasePriority {get;}
   Container                Property   System.ComponentModel.IContainer Conta...
   EnableRaisingEvents      Property   System.Boolean EnableRaisingEvents {ge...
   ...
   

Consulte Também

Criando um cmdlet para processar a entrada de linha de comando

Criando um cmdlet para processar a entrada do pipeline

como criar um Cmdlet Windows PowerShell

Estendendo tipos de objeto e formatação

como Windows PowerShell funciona

Como registrar cmdlets, provedores e aplicativos host

Referência do Windows PowerShell

Amostras de cmdlet