Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. 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 (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, em seguida, exibe informações sobre os processos em um prompt de comando.
Definindo a classe de cmdlet
A primeira etapa na criação do cmdlet é a nomeação do 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 é "Get". (Quase qualquer tipo de cmdlet capaz de recuperar informações pode processar a entrada da linha de comando.) Para obter mais informações sobre verbos de cmdlet aprovados, consulte Cmdlet Verb Names.
Aqui está a declaração de classe para o cmdlet Get-Proc. Os 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 de 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 dos cmdlets canalizados, e MemberType é um parâmetro para o cmdlet Get-Member. O parâmetro tem o argumento "propriedade".
PS> Get-Proc; Get-Member -MemberType Propriedade
Para declarar parâmetros para um cmdlet, você deve primeiro definir as propriedades que representam os parâmetros. No cmdlet Get-Proc, o único parâmetro é Name, que, neste caso, representa o nome do objeto de processo do .NET Framework a ser recuperado. Portanto, a classe de cmdlet define uma propriedade do tipo string para aceitar uma matriz de nomes.
Aqui está 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 ao tempo de execução do Windows PowerShell 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 estão marcados como padrão público como interno e não são encontrados pelo tempo de execução do Windows PowerShell.
Este cmdlet usa uma matriz de cadeias de caracteres para o parâmetro Name. Se possível, seu 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âmetros
Nomes de parâmetros e tipos de dados predefinidos do Windows PowerShell devem ser reutilizados tanto quanto possível para garantir que seu cmdlet seja compatível com cmdlets do Windows PowerShell. Por exemplo, se todos os cmdlets usarem o nome do parâmetro
Idpredefinido para identificar um recurso, o usuário entenderá facilmente o significado do parâmetro, independentemente do cmdlet que estiver usando. Basicamente, os nomes de parâmetros seguem as mesmas regras usadas para nomes de variáveis no Common Language Runtime (CLR). Para obter mais informações sobre nomenclatura de parâmetros, consulte Cmdlet Parameter Names.O Windows PowerShell reserva alguns nomes de parâmetros para fornecer uma experiência de usuário consistente. Não use estes nomes de parâmetros:
WhatIf,Confirm,Verbose,Debug,Warn,ErrorAction,ErrorVariable,OutVariableeOutBuffer. Além disso, os seguintes aliases para esses nomes de parâmetros 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 que seja exclusivo de 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 diferenciação 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 Cmdlet Parameters.
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 booleanas. Um parâmetro booleano, também chamado de switch , lida apenas com as configurações booleanas. O switch é usado 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 na linha de comando, deixe a palavra-chave Position fora da declaração de atributo.
Observação
A menos que os parâmetros devam 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.
Declarar parâmetros como obrigatórios ou opcionais
Um cmdlet deve definir cada parâmetro como 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âmetros de suporte
O cmdlet de exemplo Get-Proc 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 Validating Parameter Input.
[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 Creating Your First Cmdlet.
O cmdlet Get-Proc substitui o método System.Management.Automation.Cmdlet.ProcessRecord para manipular a entrada de parâmetro Name fornecida pelo usuário ou por 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 no 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 informar o tempo de execução 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 C# completo, consulte GetProcessSample02 Sample.
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 formatando.
Criando o cmdlet
Depois de implementar um cmdlet, você deve registrá-lo com o 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 seu 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 seguinte comando para listar o processo do Internet Explorer, chamado "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, Outlook e Bloco de Notas denominados "IEXPLORE", "OUTLOOK" e "NOTEPAD", use o seguinte comando. 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
Ver também
Adicionando parâmetros que processam a entrada do pipeline
Estendendo tipos de objeto e formatação
Como registrar cmdlets, provedores e aplicativos host
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
