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.
Uma fonte de entrada para um cmdlet é a linha de comando. Este tópico descreve como adicionar um parâmetro ao cmdlet Get-Proc (que é descrito em Criando seu primeiro cmdlet) para que o cmdlet possa processar a entrada do computador local com base em objetos explícitos passados para o cmdlet. O cmdlet Get-Proc descrito aqui recupera processos com base em seus nomes e exibe informações sobre os processos em um prompt de comando.
Definindo a classe cmdlet
A primeira etapa na criação do cmdlet é a nomenclatura de cmdlet e a declaração da classe .NET Framework que implementa o cmdlet. Esse cmdlet recupera informações do processo, portanto, o nome do verbo escolhido aqui é "Obter". (Quase qualquer tipo de cmdlet capaz de recuperar informações pode processar entrada de linha de comando.) Para obter mais informações sobre verbos de cmdlet aprovados, consulte Nomes de Verbo do Cmdlet.
Aqui está a declaração de classe para o cmdlet Get-Proc. Detalhes sobre essa definição são fornecidos em Criando seu primeiro cmdlet.
[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
Inherits Cmdlet
Declarando parâmetros
Um parâmetro cmdlet permite que o usuário forneça entrada para o cmdlet. No exemplo a seguir, Get-Proc e Get-Member são os nomes de cmdlets pipelined e MemberType é um parâmetro para o cmdlet Get-Member. O parâmetro tem o argumento "property".
> Get-Proc PS; propriedade Get-Member -MemberType
Para declarar parâmetros para um cmdlet, primeiro você deve definir as propriedades que representam os parâmetros. No cmdlet Get-Proc, o único parâmetro é Name, que, nesse caso, representa o nome do objeto de processo do .NET Framework a ser recuperado. Portanto, a classe cmdlet define uma propriedade da cadeia de caracteres de tipo para aceitar uma matriz de nomes.
Esta é a declaração de parâmetro para o parâmetro Name do cmdlet Get-Proc.
/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name
{
get { return processNames; }
set { processNames = value; }
}
private string[] processNames;
#endregion Parameters
<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
Get
Return processNames
End Get
Set(ByVal value As String())
processNames = value
End Set
End Property
Para informar o runtime do Windows PowerShell de que essa propriedade é o parâmetro Name, um atributo System.Management.Automation.ParameterAttribute é adicionado à definição de propriedade. A sintaxe básica para declarar esse atributo é [Parameter()].
Observação
Um parâmetro deve ser explicitamente marcado como público. Parâmetros que não são marcados como padrão público para internos e não são encontrados pelo runtime do Windows PowerShell.
Esse cmdlet usa uma matriz de cadeias de caracteres para o parâmetro Name. Se possível, o cmdlet também deve definir um parâmetro como uma matriz, pois isso permite que o cmdlet aceite mais de um item.
Coisas para lembrar sobre definições de parâmetro
Os nomes de parâmetros e tipos de dados predefinidos do Windows PowerShell devem ser reutilizados o máximo possível para garantir que o cmdlet seja compatível com cmdlets do Windows PowerShell. Por exemplo, se todos os cmdlets usarem o nome predefinido do parâmetro
Idpara identificar um recurso, o usuário entenderá facilmente o significado do parâmetro, independentemente de qual cmdlet ele está usando. Basicamente, os nomes de parâmetro seguem as mesmas regras usadas para nomes de variáveis no CLR (Common Language Runtime). Para obter mais informações sobre a nomenclatura de parâmetros, consulte Nomes de Parâmetro de Cmdlet.O Windows PowerShell reserva alguns nomes de parâmetro para fornecer uma experiência de usuário consistente. Não use esses nomes de parâmetro:
WhatIf,Confirm,Verbose,Debug,Warn,ErrorAction,ErrorVariable,OutVariableeOutBuffer. Além disso, os seguintes aliases para esses nomes de parâmetro são reservados:vb,db,ea,ev,oveob.Nameé um nome de parâmetro simples e comum, recomendado para uso em seus cmdlets. É melhor escolher um nome de parâmetro como este do que um nome complexo exclusivo para um cmdlet específico e difícil de lembrar.Os parâmetros não diferenciam maiúsculas de minúsculas no Windows PowerShell, embora por padrão o shell preserve maiúsculas e minúsculas. A confidencialidade de maiúsculas e minúsculas dos argumentos depende da operação do cmdlet. Os argumentos são passados para um parâmetro, conforme especificado na linha de comando.
Para obter exemplos de outras declarações de parâmetro, consulte parâmetros de cmdlet.
Declarando parâmetros como posicionais ou nomeados
Um cmdlet deve definir cada parâmetro como um parâmetro posicional ou nomeado. Ambos os tipos de parâmetros aceitam argumentos únicos, vários argumentos separados por vírgulas e configurações boolianas. Um parâmetro booliano, também chamado de comutador, manipula apenas as configurações boolianas. A opção é usada para determinar a presença do parâmetro. O padrão recomendado é false.
O cmdlet Get-Proc de exemplo define o parâmetro Name como um parâmetro posicional com a posição 0. Isso significa que o primeiro argumento que o usuário insere na linha de comando é inserido automaticamente para esse parâmetro. Se você quiser definir um parâmetro nomeado, para o qual o usuário deve especificar o nome do parâmetro da linha de comando, deixe a palavra-chave Position fora da declaração de atributo.
Observação
A menos que os parâmetros precisem ser nomeados, recomendamos que você posicione os parâmetros mais usados para que os usuários não precisem digitar o nome do parâmetro.
Declarando parâmetros como obrigatórios ou opcionais
Um cmdlet deve definir cada parâmetro como um parâmetro opcional ou obrigatório. No cmdlet Get-Proc de exemplo, o parâmetro Name é definido como opcional porque a palavra-chave Mandatory não está definida na declaração de atributo.
Validação de parâmetro de suporte
O cmdlet Get-Proc de exemplo adiciona um atributo de validação de entrada, System.Management.Automation.ValidateNotNullOrEmptyAttribute, ao parâmetro Name para habilitar a validação de que a entrada não está null nem vazia. Esse atributo é um dos vários atributos de validação fornecidos pelo Windows PowerShell. Para obter exemplos de outros atributos de validação, consulte Validandode entrada de parâmetro.
[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name
Substituindo um método de processamento de entrada
Se o cmdlet for manipular a entrada de linha de comando, ele deverá substituir os métodos de processamento de entrada apropriados. Os métodos básicos de processamento de entrada são introduzidos em Criando seu primeiro cmdlet.
O cmdlet Get-Proc substitui o método System.Management.Automation.Cmdlet.ProcessRecord para lidar com a entrada de parâmetro Name fornecida pelo usuário ou um script. Esse método obtém os processos para cada nome de processo solicitado ou todos para processos se nenhum nome for fornecido. Observe que, em System.Management.Automation.Cmdlet.ProcessRecord, a chamada para System.Management.Automation.Cmdlet.WriteObject é o mecanismo de saída para enviar objetos de saída para o pipeline. O segundo parâmetro dessa chamada, enumerateCollection, é definido como true para informar o runtime do Windows PowerShell para enumerar a matriz de saída de objetos de processo e gravar um processo de cada vez na linha de comando.
protected override void ProcessRecord()
{
// If no process names are passed to the cmdlet, get all processes.
if (processNames == null)
{
// Write the processes to the pipeline making them available
// to the next cmdlet. The second argument of this call tells
// PowerShell to enumerate the array, and send one process at a
// time to the pipeline.
WriteObject(Process.GetProcesses(), true);
}
else
{
// If process names are passed to the cmdlet, get and write
// the associated processes.
foreach (string name in processNames)
{
WriteObject(Process.GetProcessesByName(name), true);
}
}
}
Protected Overrides Sub ProcessRecord()
'/ If no process names are passed to the cmdlet, get all processes.
If processNames Is Nothing Then
Dim processes As Process()
processes = Process.GetProcesses()
End If
'/ If process names are specified, write the processes to the
'/ pipeline to display them or make them available to the next cmdlet.
For Each name As String In processNames
'/ The second parameter of this call tells PowerShell to enumerate the
'/ array, and send one process at a time to the pipeline.
WriteObject(Process.GetProcessesByName(name), True)
Next
End Sub 'ProcessRecord
Exemplo de código
Para obter o código de exemplo em C# completo, consulte de exemplo GetProcessSample02.
Definindo tipos de objeto e formatação
O Windows PowerShell passa informações entre cmdlets usando objetos do .NET Framework. Consequentemente, um cmdlet pode precisar definir seu próprio tipo ou um 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 usando 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 é registrado no Windows PowerShell, você pode testá-lo executando-o na linha de comando. Aqui estão duas maneiras de testar o código para o cmdlet de exemplo. Para obter mais informações sobre como usar cmdlets da linha de comando, consulte Introdução ao Windows PowerShell.
No prompt do Windows PowerShell, use o comando a seguir para listar o processo do Internet Explorer, que se chama "IEXPLORE".
Get-Proc -Name iexploreA saída a seguir é exibida.
Handles NPM(K) PM(K) WS(K) VS(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 354 11 10036 18992 85 0.67 3284 iexplorePara listar os processos do Internet Explorer, do Outlook e do Bloco de Notas chamados "IEXPLORE", "OUTLOOK" e "NOTEPAD", use o comando a seguir. Se houver vários processos, todos eles serão exibidos.
Get-Proc -Name iexplore, outlook, notepadA saída a seguir é exibida.
Handles NPM(K) PM(K) WS(K) VS(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 732 21 24696 5000 138 2.25 2288 iexplore 715 19 20556 14116 136 1.78 3860 iexplore 3917 62 74096 58112 468 191.56 1848 OUTLOOK 39 2 1024 3280 30 0.09 1444 notepad 39 2 1024 356 30 0.08 3396 notepad
Consulte Também
a adição de parâmetros que processam de entrada de pipeline
estendendo tipos de objeto e formatação
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.
