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

Artigo
09/27/2021

Esta secção descreve como criar um cmdlet que recupera informações do computador local sem a utilização de parâmetros e, em seguida, escreve a informação para o pipeline. O cmdlet descrito aqui é um Get-Proc cmdlet que recupera informações sobre os processos do computador local, e depois exibe essa informação na linha de comando.

Nota

Tenha em atenção que ao escrever cmdlets, os conjuntos de referência Windows PowerShell® são descarregados no disco (por padrão em C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Não estão instalados na Cache de Montagem Global (GAC).

Nomeação do Comandante

Um nome de cmdlet consiste num verbo que indica a ação que o cmdlet toma e um substantivo que indica os itens em que o cmdlet atua. Como esta amostra Get-Proc cmdlet recupera objetos de processo, utiliza o verbo "Obter", definido pelo System.Management.Automation.Verbscommon enumeração, 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

Deve escolher um substantivo específico. É melhor utilizar um substantivo singular prefixado com uma versão abreviada do nome do produto. Um nome cmdlet exemplo deste tipo é Get-SQLServer " "

Escolher um Verbo

Deve utilizar um verbo do conjunto de nomes de verbos de cmdlet aprovados. Para obter mais informações sobre os verbos do cmdlet aprovados, consulte o Cmdlet Verb Names.

Definição da Classe Cmdlet

Depois de ter escolhido um nome cmdlet, defina uma classe .NET para implementar o cmdlet. Aqui está a definição de classe para esta amostra Get-Proc cmdlet:

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

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

Note que antes da definição de classe, o atributo System.Management.Automation.CmdletAttribute, com a [Cmdlet(verb, noun, ...)] sintaxe, é utilizado para identificar esta classe como um cmdlet. Este é o único atributo necessário para todos os cmdlets, e permite que o Windows PowerShell tempo de execução os chame corretamente. Pode definir palavras-chave de atributos para declarar ainda mais a classe, se necessário. Esteja ciente de que a declaração de atributos para a nossa amostra A classe GetProcCommand declara apenas os nomes substantivos e verbos para o Get-Proc cmdlet.

Nota

Para todas as classes Windows PowerShell atribuir, as palavras-chave que pode definir correspondem às propriedades da classe atributo.

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

Importante

Se quiser definir um cmdlet que aceda diretamente ao tempo de funcionação Windows PowerShell, a sua classe .NET deverá derivar da classe base System.Management.Automation.PSCmdlet. Para obter mais informações sobre esta classe, consulte criar um Cmdlet que define conjuntos de parâmetros.

Nota

A classe para um cmdlet deve ser explicitamente marcada como pública. As classes que não são marcadas como públicas vão falhar para o interior e não serão encontradas pelo tempo de execução Windows PowerShell.

Windows PowerShell utiliza o espaço de nome Microsoft.PowerShell.Commands para as suas classes de cmdlet. Recomenda-se colocar as suas aulas de cmdlet num espaço de nome de Comandos do seu espaço de nome API, por exemplo, xxx.PS.Comandos.

Sobrevam um método de processamento de entrada

A classe System.Management.Automation.Cmdlet fornece três principais métodos de processamento de entradas, pelo menos um dos quais o seu cmdlet deve ser sobreponhado. Para obter mais informações sobre como Windows PowerShell processa registos, consulte Como funciona Windows PowerShell.

Para todos os tipos de entrada, o Windows PowerShell chamadas de tempo de execução System.Management.Automation.Cmdlet.BeginProcessing para permitir o processamento. Se o seu cmdlet tiver de efetuar algum pré-processamento ou configuração, pode fazê-lo sobressaíndo este método.

Nota

Windows PowerShell usa o termo "registo" para descrever o conjunto de parâmetros fornecidos quando um cmdlet é chamado.

Se o seu cmdlet aceitar a entrada do gasoduto, deve sobrepor-se ao método System.Management.Automation.Cmdlet.ProcessRecord e, opcionalmente, o método System.Management.Automation.Cmdlet.EndProcessing. Por exemplo, um cmdlet pode sobrepor-se a ambos os métodos se recolher todas as entradas utilizando o System.Management.Automation.Cmdlet.ProcessRecord e, em seguida, operar na entrada como um todo e não um elemento de cada vez, como faz o Sort-Object cmdlet.

Se o seu cmdlet não tiver a entrada do gasoduto, deve sobrepor-se ao método System.Management.Automation.Cmdlet.EndProcessing. Tenha em atenção que este método é frequentemente utilizado no lugar do System.Management.Automation.Cmdlet.BeginProcessing quando o cmdlet não pode funcionar com um elemento de cada vez, como é o caso de um cmdlet de triagem.

Uma vez que esta amostra Get-Proc cmdlet deve receber a entrada do gasoduto, substitui o método System.Management.Automation.Cmdlet.ProcessRecord e utiliza as implementações padrão para system.Management.Automation.Cmdlet.BeginProcessing and System.Management.Automation.Cmdlet.EndProcessing. O sistema.Management.Automation.Cmdlet.ProcessRecord sobrepõe-se aos processos e escreve-os para a linha de comando utilizando 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 lembrar sobre o processamento de entradas

A fonte padrão de entrada é um objeto explícito (por exemplo, uma cadeia) fornecido pelo utilizador na linha de comando. Para obter mais informações, consulte criar um Cmdlet para processar a entrada da linha de comando.
Um método de processamento de entrada também pode receber a entrada do objeto de saída de um cmdlet a montante no oleoduto. Para obter mais informações, consulte criar um Cmdlet para processar a entrada do gasoduto. Tenha em atenção que o seu cmdlet pode receber a entrada de uma combinação de fontes de linha de comando e de gasoduto.
O cmdlet a jusante pode não voltar por muito tempo, ou não mesmo. Por essa razão, o método de processamento de entrada no seu cmdlet não deve manter fechaduras durante as chamadas para System.Management.Automation.Cmdlet.WriteObject, especialmente bloqueios para os quais o âmbito se estende para além da instância cmdlet.

Importante

Os cmdlets nunca devem ligar para o System.Console.Writeline* ou o seu equivalente.

O seu cmdlet pode ter variáveis objetivas para limpar quando terminar o processamento (por exemplo, se abrir uma pega de ficheiro no Sistema.Management.Automation.Cmdlet.BeginProcessing e manter a pega aberta para utilização por System.Management.Automation.Cmdlet.ProcessRecord). É importante lembrar que o tempo de execução Windows PowerShell nem sempre chama o método System.Management.Automation.Cmdlet.EndProcessing, que deve efetuar a limpeza de objetos.

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

Amostra de código

Para obter o código de amostra completo C#, consulte a amostra GetProcessSample01.

Definição de tipos de objetos e formatação

Windows PowerShell transmite informações entre cmdlets utilizando objetos .NET. Consequentemente, um cmdlet pode precisar de definir o seu próprio tipo, ou o cmdlet pode precisar de estender um tipo existente fornecido por outro cmdlet. Para obter mais informações sobre a definição de novos tipos ou a extensão dos tipos existentes, consulte a extensão dos tipos de objetos e a formatação.

Construção do Comandante

Depois de implementar um cmdlet, deve registá-lo com Windows PowerShell através de um encaixe Windows PowerShell. Para obter mais informações sobre o registo de cmdlets, consulte Como Registar Cmdlets, Fornecedores e Aplicações de Anfitrião.

Testar o Cmdlet

Quando o seu cmdlet estiver registado com Windows PowerShell, pode testá-lo executando-o na linha de comando. O código para a nossa amostra Get-Proc cmdlet é pequeno, mas ainda utiliza 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 a sua saída pode ser usada. Para obter mais informações sobre a utilização de cmdlets da linha de comando, consulte o Início com Windows PowerShell.

Comece Windows PowerShell e faça os processos atuais funcionarem no computador.

get-proc

Aparece a seguinte saída.

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 uma manipulação mais fácil.
```
$p=get-proc
```
Obtenha o número de processos.
```
$p.length
```
Aparece a seguinte saída.
```
63
```

Recupere um processo específico.

$p[6]

Aparece a seguinte saída.

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

Aparece a seguinte saída.

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

$p[6].starttime.dayofyear

Obtenha os processos para os quais a contagem de manípulos seja superior a 500, e serdene o resultado.

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

Aparece a seguinte saída.

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

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

$p | Get-Member -MemberType property

    TypeName: System.Diagnostics.Process

Aparece a seguinte saída.

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