Creating a Cmdlet without Parameters (Criar um Cmdlet sem Parâmetros)

Artigo
03/25/2025

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, os assemblies de referência do Windows PowerShell® são baixados em disco (por padrão em C:\Arquivos de Programas\Assemblies de Referência\Microsoft\WindowsPowerShell\v1.0). Eles não estão instalados no GAC (Global Assembly Cache).

Nomeando o cmdlet

Um nome de cmdlet consiste em um verbo que indica a ação que o cmdlet executa e um substantivo que indica os itens nos quais o cmdlet atua. Como esse cmdlet de exemplo Get-Proc 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: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Escolher um substantivo

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

Escolher um verbo

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

Definindo a classe de 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 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 do 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 do Windows PowerShell, as palavras-chave que você pode definir correspondem às propriedades da classe de atributo.

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

Importante

Se você quiser definir um cmdlet que acesse o tempo de execução do Windows PowerShell diretamente, sua classe .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 estão marcadas como públicas serão padronizadas como internas e não serão encontradas pelo tempo de execução do Windows PowerShell.

O Windows PowerShell usa o namespace Microsoft.PowerShell.Commands para suas classes de cmdlet. É recomendável colocar suas classes de cmdlet em um namespace Commands do seu namespace de API, por exemplo, xxx.PS. Comandos.

Substituindo um método de processamento de entrada

A classe System.Management.Automation.Cmdlet do 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 o 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

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 entrada de pipeline, ele deverá substituir o método System.Management.Automation.Cmdlet.ProcessRecord e, opcionalmente, o método System.Management.Automation.Cmdlet.EndProcessing. Por exemplo, um cmdlet pode substituir ambos os métodos se reunir todas as entradas usando System.Management.Automation.Cmdlet.ProcessRecord e, em seguida, operar na entrada como um todo, em vez de um elemento de cada vez, como faz o cmdlet Sort-Object.

Se o cmdlet não receber entrada de pipeline, ele deverá substituir o método System.Management.Automation.Cmdlet.EndProcessing. Lembre-se de que esse método é usado com freqüência no lugar de System.Management.Automation.Cmdlet.BeginProcessing quando o cmdlet não pode operar em um elemento de cada vez, como é o caso de um cmdlet de classificação.

Como esse exemplo Get-Proc cmdlet deve receber entrada de 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.EndProcessing. A substituição do System.Management.Automation.Cmdlet.ProcessRecord recupera 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 para lembrar sobre o processamento de entrada

A fonte padrão para 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 de pipeline. Lembre-se de que seu cmdlet pode receber entrada de uma combinação de fontes de linha de comando e pipeline.
O cmdlet downstream pode não retornar por muito tempo ou não retornar de todo. 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 nunca devem chamar System.Console.Writeline* ou equivalente.

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

Por exemplo, System.Management.Automation.Cmdlet.EndProcessing pode não ser chamado se o cmdlet for cancelado no meio do caminho ou se ocorrer um erro de encerramento em qualquer parte do cmdlet. Portanto, um cmdlet que requer limpeza de objeto deve implementar o padrão System.IDisposable completo, incluindo o finalizador, para que o tempo de execução possa chamar System.Management.Automation.Cmdlet.EndProcessing e System.IDisposable.Dispose* no final do processamento.

Exemplo de código

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

Definindo 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, você deve registrá-lo com o 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. O código para nosso cmdlet Get-Proc de exemplo é pequeno, mas ainda usa o tempo de execução do 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 da linha de comando, consulte o Introdução ao Windows PowerShell.

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

Get-Proc

A saída a seguir é exibida.

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

Atribua uma variável aos resultados do cmdlet para facilitar a manipulação.
```
$p=Get-Proc
```
Obtenha o número de processos.
```
$p.Length
```
A saída a seguir é exibida.
```
63
```

Recupere um processo específico.

$p[6]

A saída a seguir é exibida.

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

Obtenha a hora de início deste processo.

$p[6].StartTime

A saída a seguir é exibida.

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

$p[6].StartTime.DayOfYear

Obtenha os processos para os quais a contagem de identificadores é maior que 500 e classifique o resultado.

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

A saída a seguir é exibida.

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

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

$p | Get-Member -MemberType Property

    TypeName: System.Diagnostics.Process

A saída a seguir é exibida.

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