Adicionar parâmetros que processam a entrada de linha de comando
Uma fonte de entrada para um cmdlet é a linha de comando. Este tópico descreve como adicionar um parâmetro ao Get-Proc cmdlet (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 Get-Proc cmdlet descrito aqui recupera os processos com base em seus nomes e, em seguida, exibe informações sobre os processos em um prompt de comando.
Definindo a classe do cmdlet
a primeira etapa na criação de cmdlet é a nomenclatura de cmdlets e a declaração da classe .NET Framework que implementa o cmdlet. Esse cmdlet recupera informações de processo, portanto, o nome do verbo escolhido aqui é "Get". (Quase qualquer tipo de cmdlet capaz de recuperar informações pode processar a entrada de linha de comando.) Para obter mais informações sobre verbos de cmdlet aprovados, consulte nomes de verbo de cmdlet.
Aqui está a declaração de classe para o Get-Proc cmdlet. Detalhes sobre essa definição são fornecidos na criação do 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 de cmdlets de pipeline e MemberType é um parâmetro para o Get-Member cmdlet. O parâmetro tem o argumento "Property".
PS> Get-proc; get-member -Propriedade MemberType
Para declarar parâmetros para um cmdlet, você deve primeiro definir as propriedades que representam os parâmetros. no Get-Proc cmdlet, o único parâmetro é Name , que, nesse caso, representa o nome do objeto de processo de .NET Framework a ser recuperado. Portanto, a classe cmdlet define uma propriedade do tipo cadeia de caracteres para aceitar uma matriz de nomes.
Aqui está a declaração de parâmetro para o Name parâmetro do Get-Proc cmdlet.
/// <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 Windows PowerShell runtime que essa propriedade é o Name parâmetro, 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 interno e não são encontrados pelo tempo de execução de Windows PowerShell.
Esse cmdlet usa uma matriz de cadeias de caracteres para o Name parâmetro. 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 a serem lembradas sobre definições de parâmetros
os nomes de parâmetro Windows PowerShell e os tipos de dados predefinidos devem ser reutilizados o máximo possível para garantir que o cmdlet seja compatível com os cmdlets Windows PowerShell. Por exemplo, se todos os cmdlets usarem o nome de parâmetro predefinido
Idpara identificar um recurso, o usuário entenderá facilmente o significado do parâmetro, independentemente do cmdlet que estiver usando. Basicamente, os nomes de parâmetro seguem as mesmas regras que as usadas para nomes de variáveis no Common Language Runtime (CLR). Para obter mais informações sobre a nomenclatura de parâmetros, consulte nomes de parâmetro de cmdlet.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,,,,,ConfirmVerboseDebugWarnErrorAction,ErrorVariable,OutVariableeOutBuffer. Além disso, os aliases a seguir para esses nomes de parâmetro são reservados:,,,,vbdbeaevoveob.Nameé um nome de parâmetro simples e comum, recomendado para uso em seus cmdlets. É melhor escolher um nome de parâmetro como este de um nome complexo que seja exclusivo para um cmdlet específico e difícil de lembrar.os parâmetros não diferenciam maiúsculas de minúsculas em Windows PowerShell, embora por padrão o shell preserve o caso. Diferenciar maiúsculas de 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. Os dois 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 switch, trata apenas das configurações boolianas. A opção é usada para determinar a presença do parâmetro. O padrão recomendado é false .
O cmdlet de exemplo Get-Proc define o Name parâmetro como um parâmetro posicional com Position
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 Position palavra-chave fora da declaração do atributo.
Observação
A menos que os parâmetros devam ser nomeados, recomendamos que você crie os parâmetros mais usados posicionais 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 de exemplo Get-Proc , o Name parâmetro é definido como opcional porque a Mandatory palavra-chave não está definida na declaração de atributo.
Validação de parâmetro de suporte
O cmdlet de exemplo Get-Proc adiciona um atributo de validação de entrada, System. Management. Automation. Validatenotnulloremptyattribute, ao Name parâmetro para habilitar a validação de que a entrada não é 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 validando a 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 na criação do seu primeiro cmdlet.
O Get-Proc cmdlet substitui o método System. Management. Automation. cmdlet. ProcessRecord para manipular a Name entrada de parâmetro fornecida pelo usuário ou um script. Esse método obtém os processos para cada nome de processo solicitado ou todos os processos, se nenhum nome for fornecido. Observe que em System. Management. Automation. cmdlet. ProcessRecord, a chamada para System. Management. Automation. cmdlet. WriteObject% 28System. Object% 2CSystem. booliano %29 é 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 tempo de execução de Windows PowerShell para enumerar a matriz de saída de objetos de processo e gravar um processo por 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 completo em C#, consulte exemplo de GetProcessSample02.
Definindo tipos de objeto e formatação
Windows PowerShell passa informações entre os cmdlets usando .NET Framework objetos. 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.
Criando o cmdlet
depois de implementar um cmdlet, você deve registrá-lo com Windows PowerShell usando um snap-in de Windows PowerShell. Para obter mais informações sobre como registrar cmdlets, consulte como registrar cmdlets, provedores e aplicativos de host.
Testando o cmdlet
quando o cmdlet é registrado com 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 na linha de comando, consulte introdução com Windows PowerShell.
no prompt de Windows PowerShell, use o comando a seguir para listar o processo do Internet Explorer, denominado "iexplore".
get-proc -name iexploreA saída a seguir aparece.
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 chamados "iexplore", "Outlook" e "bloco de notas", 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 aparece.
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
Adicionar parâmetros que processam a entrada de pipeline
Estendendo tipos de objeto e formatação
Como registrar cmdlets, provedores e aplicativos host
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de