Adding Parameters That Process Command-Line Input (Adicionar Parâmetros que Processam Entradas da Linha de Comandos)
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 na Criação do Seu Primeiro Comandante),de modo a que o cmdlet possa processar a entrada do computador local com base em objetos explícitos passados para o cmdlet. O Get-Proc cmdlet aqui descrito recupera processos com base nos seus nomes e, em seguida, exibe informações sobre os processos num pedido de comando.
Definição da Classe Cmdlet
O primeiro passo na criação do CMDLET é o nome de CMDLET e a declaração da classe .NET Framework que implementa o cmdlet. Este cmdlet recupera informações do processo, por isso o nome do verbo escolhido aqui é "Obter". (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 o Cmdlet Verb Names.
Aqui está a declaração de classe para o Get-Proc cmdlet. Os detalhes sobre esta definição são fornecidos na Criação do Seu Primeiro Comandante.
[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
Inherits Cmdlet
Parâmetros de declaração
Um parâmetro cmdlet permite ao utilizador fornecer entrada ao cmdlet. No exemplo seguinte, Get-Proc e Get-Member são os nomes de cmdlets pipelined, e MemberType é um parâmetro para o Get-Member cmdlet. O parâmetro tem o argumento "propriedade".
PS> get-proc; get-member -propriedade de tipo membro
Para declarar parâmetros para um cmdlet, deve primeiro definir as propriedades que representam os parâmetros. No Get-Proc cmdlet, o único parâmetro é Name , que neste caso representa o nome do .NET Framework objeto de processo para recuperar. Portanto, a classe cmdlet define uma propriedade de tipo string para aceitar uma variedade de nomes.
Aqui está a declaração do 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 o Windows PowerShell tempo de execução de que esta propriedade é o Name parâmetro, um atributo System.Management.Automation.Automation.Parameterattribute é adicionado à definição de propriedade. A sintaxe básica para declarar este atributo é [Parameter()] .
Nota
Um parâmetro deve ser explicitamente marcado como público. Parâmetros que não são marcados como incumprimento público para interno e não são encontrados pelo tempo de execução Windows PowerShell.
Este cmdlet usa uma matriz de cordas para o Name parâmetro. Se possível, o seu cmdlet também deve definir um parâmetro como uma matriz, pois isto permite que o cmdlet aceite mais do que um item.
Coisas a lembrar sobre definições de parâmetros
Os nomes de parâmetros e tipos de dados pré-definidos Windows PowerShell devem ser reutilizados tanto quanto possível para garantir que o seu cmdlet é compatível com Windows PowerShell cmdlets. Por exemplo, se todos os cmdlets utilizarem o nome do parâmetro predefinido
Idpara identificar um recurso, o utilizador compreenderá facilmente o significado do parâmetro, independentemente do cmdlet que estiver a usar. Basicamente, os nomes dos parâmetros seguem as mesmas regras que as utilizadas para nomes variáveis no tempo comum de execução da linguagem (CLR). Para obter mais informações sobre o nome do parâmetro, consulte os nomes dos parâmetros do Cmdlet.Windows PowerShell reserva alguns nomes de parâmetros para proporcionar uma experiência consistente do utilizador. Não utilize estes nomes de parâmetros:
WhatIf, , , , , , ,ConfirmeVerboseDebugWarnErrorActionErrorVariableOutVariableOutBuffer. Além disso, os seguintes pseudónimos para estes parâmetros são reservados:vb, , , , , edbeaevovob.Nameé um nome de parâmetro simples e comum, recomendado para uso nos seus cmdlets. É melhor escolher um nome de parâmetro como este do que um nome complexo que é único a um cmdlet específico e difícil de lembrar.Os parâmetros são insensíveis ao Windows PowerShell, embora por defeito o estojo de concha. A sensibilidade ao caso dos argumentos depende do funcionamento do cmdlet. Os argumentos são passados para um parâmetro como especificado na linha de comando.
Por exemplo, outras declarações de parâmetros, consulte os Parâmetros 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, múltiplos argumentos separados por vírgulas e configurações booleanas. Um parâmetro Boolean, também chamado de interruptor, só lida com as definições booleanas. O interruptor é utilizado para determinar a presença do parâmetro. O padrão recomendado é false .
O Get-Proc cmdlet da amostra define o Name parâmetro como um parâmetro posicional com posição
0. Isto significa que o primeiro argumento que o utilizador introduz na linha de comando é automaticamente inserido para este parâmetro. Se pretender definir um parâmetro nomeado, para o qual o utilizador deve especificar o nome do parâmetro da linha de comando, deixe a Position palavra-chave fora da declaração de atributo.
Nota
A menos que os parâmetros tenham de ser nomeados, recomendamos que faça os parâmetros mais utilizados posicional para que os utilizadores não tenham de escrever o nome do parâmetro.
Declarar Parâmetros como Obrigatórios ou Opcionais
Um cmdlet deve definir cada parâmetro como um parâmetro opcional ou obrigatório. No Get-Proc cmdlet da amostra, 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âmetros de apoio
O Get-Proc cmdlet da amostra adiciona um atributo de validação de entrada, System.Management.Automation.Validatenotnulloremptyattribute,ao Name parâmetro para permitir a validação de que a entrada não está nem null vazia. Este atributo é um dos vários atributos de validação fornecidos por Windows PowerShell. Por exemplo, outros atributos de validação, consulte a Entrada do Parâmetro de Validação.
[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name
Sobrevam um método de processamento de entrada
Se o seu cmdlet for para manusear a entrada da linha de comando, deve anular 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 Comandante.
O Get-Proc cmdlet substitui o método System.Management.Automation.Cmdlet.ProcessRecord para lidar com a entrada de Name parâmetros fornecida pelo utilizador ou por um script. Este método obtém os processos para cada nome de processo solicitado, ou todos para processos se nenhum nome for fornecido. Note que em System.Management.Automation.Cmdlet.ProcessRecord, a chamada para System.Management.Automation.Cmdlet.WriteObject%28System.Object%2CSystem.Boolean%29 é o mecanismo de saída para o envio de objetos de saída para o pipeline. O segundo parâmetro desta chamada, enumerateCollection está definido para informar o tempo de true execução Windows PowerShell para enumerar o conjunto de saídas de objetos de processo e escrever um processo de cada vez para a 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
Amostra de código
Para obter o código de amostra completo C#, consulte a amostra GetProcessSample02.
Definição de tipos de objetos e formatação
Windows PowerShell transmite informações entre cmdlets utilizando objetos .NET Framework. Consequentemente, um cmdlet pode precisar de definir o seu próprio tipo, ou um 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 utilizando um encaixe de 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. Aqui estão duas formas de testar o código para o cmdlet da amostra. Para obter mais informações sobre a utilização de cmdlets da linha de comando, consulte "Começar com Windows PowerShell.
No Windows PowerShell, use o seguinte comando para listar o processo do Internet Explorer, que é chamado de "IEXPLORE".
get-proc -name iexploreAparece a seguinte saída.
Handles NPM(K) PM(K) WS(K) VS(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 354 11 10036 18992 85 0.67 3284 iexplorePara listar o Internet Explorer, Outlook e Bloco de notas processos denominados "IEXPLORE", "OUTLOOK" e "NOTEPAD", utilize o seguinte comando. Se houver vários processos, todos são exibidos.
get-proc -name iexplore, outlook, notepadAparece a seguinte saída.
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
Criando o seu primeiro Comandante
Ampliação de tipos de objetos e formatação
Como registar cmdlets, fornecedores e aplicações de anfitrião
Windows PowerShell Reference (Referências do Windows PowerShell)
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários