Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Esta seção descreve como criar um cmdlet que recupera informações do computador local sem o uso de parâmetros e 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 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 (Cache de Assembly Global).
Nomeando o cmdlet
Um nome de cmdlet consiste em um verbo que indica a ação que o cmdlet toma e um substantivo que indica os itens em que o cmdlet atua. Como este exemplo Get-Proc cmdlet recupera objetos de processo, ele usa o verbo "Get", 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: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .
Escolhendo um substantivo
Você deve escolher um substantivo específico. É melhor usar um substantivo singular prefixado com uma versão abreviada do nome do produto. Um nome de cmdlet de exemplo 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 Cmdlet Verb Names.
Definindo a classe 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 cmdlet de Get-Proc de exemplo:
[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 runtime 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 "Verbo" e "Substantivo" pelo verbo e pelo substantivo usados no nome do cmdlet. Como é mostrado na definição de classe anterior, o cmdlet 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 acesse diretamente o runtime do Windows PowerShell, sua classe .NET deverá 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. Classes que não são marcadas como públicas serão padrão internas e não serão encontradas pelo runtime 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 namespace da API, por exemplo, xxx.PS. Comandos.
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 o 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 runtime 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 a 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 poderá 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 o cmdlet Sort-Object faz.
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 é frequentemente usado 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 este cmdlet Get-Proc de exemplo 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 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 origem 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 processarde 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 processarde 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. Por esse motivo, o método de processamento de entrada em seu cmdlet não deve manter bloqueios durante as chamadas para System.Management.Automation.Cmdlet.WriteObject, especialmente bloqueios para os quais o escopo se estende além da instância do cmdlet.
- 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 manter o identificador aberto para uso pelo System.Management.Automation.Cmdlet.ProcessRecord). É importante lembrar que o runtime 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 podem não ser chamados se o cmdlet for cancelado no meio do caminho ou se ocorrer um erro de término em qualquer parte do cmdlet. Portanto, um cmdlet que requer a limpeza de objetos deve implementar o padrão de System.IDisposable completo, incluindo o finalizador, para que o runtime 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 do C# completo, consulte de exemplo GetProcessSample01.
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 formatação.
Compilando o cmdlet
Depois de implementar um cmdlet, você deve registrá-lo 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 o cmdlet tiver sido registrado no Windows PowerShell, você poderá testá-lo executando-o na linha de comando. O código do nosso cmdlet Get-Proc de exemplo é pequeno, mas ainda usa o runtime 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-ProcA 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-ProcObtenha o número de processos.
$p.LengthA saída a seguir é exibida.
63Recupere 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 rundll32Obtenha a hora de início desse processo.
$p[6].StartTimeA saída a seguir é exibida.
Tuesday, July 26, 2005 9:34:15 AM$p[6].StartTime.DayOfYear207Obtenha os processos para os quais a contagem de identificadores é maior que 500 e classifique o resultado.
$p | Where-Object {$_.HandleCount -gt 500 } | Sort-Object HandleCountA 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-Memberpara listar as propriedades disponíveis para cada processo.$p | Get-Member -MemberType PropertyTypeName: System.Diagnostics.ProcessA 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... ...
Consulte Também
criar um cmdlet para processar de entrada de linha de comando
criar um cmdlet para processar de entrada de pipeline
como criar um cmdlet do Windows PowerShell
estendendo tipos de objeto e formatação
como o Windows PowerShell funciona
como registrar cmdlets, provedores e aplicativos host
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
