Compartilhar via


Adicionar parâmetros que processam a entrada de pipeline

Uma fonte de entrada para um cmdlet é um objeto no pipeline que se origina de um cmdlet upstream. Esta seção descreve como adicionar um parâmetro ao cmdlet Get-Proc (descrito em Criando seu primeiro cmdlet ) para que o cmdletpossa processar objetos de pipeline.

Esse cmdlet Get-Proc usa um parâmetro que aceita a entrada de um objeto de pipeline, recupera informações de processo do computador local com base nos nomes fornecidos e, em seguida, exibe informações sobre os processos na linha Name de comando.

Definindo a classe cmdlet

A primeira etapa na criação do cmdlet é sempre nomear o cmdlet e declarar a classe .NET 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 de linha de comando.) Para obter mais informações sobre verbos de cmdlet aprovados, consulte Nomes de verbos do cmdlet.

A seguir está a definição deste cmdlet Get-Proc. Os detalhes dessa definição são dados em Criando seu primeiro cmdlet.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand : Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Definindo a entrada do pipeline

Esta seção descreve como definir a entrada do pipeline para um cmdlet. Este Get-Proc cmdlet define uma propriedade que representa o parâmetro conforme descrito em Name Adicionando parâmetros que processam entrada de linha de comando. (Consulte esse tópico para obter informações gerais sobre como declarar parâmetros.)

No entanto, quando um cmdlet precisa processar a entrada do pipeline, ele deve ter seus parâmetros vinculados aos valores de entrada pelo runtime Windows PowerShell. Para fazer isso, você deve adicionar a palavra-chave ou adicionar a palavra-chave à declaração de atributo ValueFromPipeline ValueFromPipelineByProperty System.Management.Automation.Parameterattribute. ValueFromPipelineEspecifique a palavra-chave se o cmdlet acessar o objeto de entrada completo. ValueFromPipelineByPropertyEspecifique o se o cmdlet acessar apenas uma propriedade do objeto .

Aqui está a declaração de parâmetro para Name o parâmetro deste Get-Proc cmdlet que aceita a entrada do pipeline.

[Parameter(
   Position = 0,
   ValueFromPipeline = true,
   ValueFromPipelineByPropertyName = true)]
[ValidateNotNullOrEmpty]
public string[] Name
{
   get { return this.processNames; }
   set { this.processNames = value; }
}
<Parameter(Position:=0, ValueFromPipeline:=True, _
ValueFromPipelineByPropertyName:=True), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

A declaração anterior define a palavra-chave como para que o runtime do Windows PowerShell a binde o parâmetro ao objeto de entrada se o objeto for do mesmo tipo que o parâmetro ou se puder ser coagido ao ValueFromPipeline true mesmo tipo. A ValueFromPipelineByPropertyName palavra-chave também é definida como true para que Windows PowerShell runtime verifique o objeto de entrada para uma Name propriedade. Se o objeto de entrada tiver essa propriedade, o runtime vinculará o Name parâmetro à propriedade do objeto de Name entrada.

Observação

A configuração da ValueFromPipeline palavra-chave de atributo para um parâmetro tem precedência sobre a configuração da ValueFromPipelineByPropertyName palavra-chave .

Substituindo um método de processamento de entrada

Se o cmdlet for manipular a entrada do pipeline, ele precisará 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.

Esse Get-Proc cmdlet substitui o método System.Management.Automation.Cmdlet.ProcessRecord para manipular a entrada de parâmetro fornecida pelo usuário ou um Name script. Esse método obterá 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 WriteObject(System.Object,System.Boolean) é o mecanismo de saída para enviar objetos de saída para o pipeline. O segundo parâmetro dessa chamada, , é definido como para dizer ao runtime Windows PowerShell para enumerar a matriz de objetos de processo e gravar um processo de cada vez na linha enumerateCollection true 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);
    } // End foreach (string name...).
  }
}
Protected Overrides Sub ProcessRecord()
    Dim processes As Process()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        processes = Process.GetProcesses()
    Else

        '/ 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 If

End Sub 'ProcessRecord

Exemplo de código

Para obter o código de exemplo C# completo, consulte GetProcessSample03 Sample.

Definindo tipos de objeto e formataçã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.

Criando o cmdlet

Depois de implementar um cmdlet, ele deve ser registrado com Windows PowerShell por meio de Windows PowerShell snap-in. Para obter mais informações sobre como registrar cmdlets, consulte How to Register Cmdlets, Providers, and Host Applications.

Testando o cmdlet

Quando o cmdlet tiver sido registrado com Windows PowerShell, teste-o executando-o na linha de comando. Por exemplo, teste o código para o cmdlet de exemplo. Para obter mais informações sobre como usar cmdlets da linha de comando, consulte o Ponto de Partida com Windows PowerShell.

  • No prompt Windows PowerShell, insira os comandos a seguir para recuperar os nomes de processo por meio do pipeline.

    PS> type ProcessNames | get-proc
    

    A saída a seguir aparece.

    Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)    Id  ProcessName
    -------  ------  -----   ----- -----   ------    --  -----------
        809      21  40856    4448    147    9.50  2288  iexplore
        737      21  26036   16348    144   22.03  3860  iexplore
         39       2   1024     388     30    0.08  3396  notepad
       3927      62  71836   26984    467  195.19  1848  OUTLOOK
    
  • Insira as linhas a seguir para obter os objetos de processo que têm uma Name propriedade dos processos chamados "IEXPLORE". Este exemplo usa o cmdlet (fornecido pelo Windows PowerShell) como um comando upstream para recuperar os processos Get-Process "IEXPLORE".

    PS> get-process iexplore | get-proc
    

    A saída a seguir aparece.

    Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)    Id  ProcessName
    -------  ------  -----   ----- -----   ------    --  -----------
        801      21  40720    6544    142    9.52  2288  iexplore
        726      21  25872   16652    138   22.09  3860  iexplore
        801      21  40720    6544    142    9.52  2288  iexplore
        726      21  25872   16652    138   22.09  3860  iexplore
    

Consulte Também

Adicionando parâmetros que processam a entrada de linha de comando

Criando seu primeiro cmdlet

Estendendo tipos de objeto e formatação

Como registrar cmdlets, provedores e aplicativos de host

Referência do Windows PowerShell

Amostras de cmdlet