Adición de parámetros que procesan la entrada de la canalizaciónAdding Parameters that Process Pipeline Input

Un origen de entrada para un cmdlet es un objeto de la canalización que se origina en un cmdlet de nivel superior.One source of input for a cmdlet is an object on the pipeline that originates from an upstream cmdlet. En esta sección se describe cómo agregar un parámetro al cmdlet Get-proc (descrito en creación del primer cmdlet) para que el cmdlet pueda procesar objetos de canalización.This section describes how to add a parameter to the Get-Proc cmdlet (described in Creating Your First Cmdlet) so that the cmdlet can process pipeline objects.

Este cmdlet Get-proc usa un Name parámetro que acepta la entrada de un objeto de canalización, recupera información del proceso del equipo local en función de los nombres proporcionados y, a continuación, muestra información sobre los procesos en la línea de comandos.This Get-Proc cmdlet uses a Name parameter that accepts input from a pipeline object, retrieves process information from the local computer based on the supplied names, and then displays information about the processes at the command line.

Definir la clase de cmdletDefining the Cmdlet Class

El primer paso en la creación de un cmdlet es siempre nombrar el cmdlet y declarar la clase .NET que implementa el cmdlet.The first step in cmdlet creation is always naming the cmdlet and declaring the .NET class that implements the cmdlet. Este cmdlet recupera información de proceso, por lo que el nombre de verbo elegido aquí es "Get".This cmdlet retrieves process information, so the verb name chosen here is "Get". (Casi cualquier tipo de cmdlet que sea capaz de recuperar información puede procesar la entrada de la línea de comandos). Para obtener más información sobre los verbos de cmdlet aprobados, consulte nombres de verbos de cmdlet.(Almost any sort of cmdlet that is capable of retrieving information can process command-line input.) For more information about approved cmdlet verbs, see Cmdlet Verb Names.

A continuación se ofrece la definición de este cmdlet Get-proc.The following is the definition for this Get-Proc cmdlet. Los detalles de esta definición se proporcionan al crear el primer cmdlet.Details of this definition are given in Creating Your First Cmdlet.

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

Definir la entrada de la canalizaciónDefining Input from the Pipeline

En esta sección se describe cómo definir la entrada desde la canalización para un cmdlet.This section describes how to define input from the pipeline for a cmdlet. Este cmdlet Get-proc define una propiedad que representa el Name parámetro tal y como se describe en agregar parámetros que procesan la entrada de la línea de comandos.This Get-Proc cmdlet defines a property that represents the Name parameter as described in Adding Parameters that Process Command Line Input. (Vea ese tema para obtener información general sobre la declaración de parámetros).(See that topic for general information about declaring parameters.)

Sin embargo, cuando un cmdlet necesita procesar la entrada de canalización, el tiempo de ejecución de Windows PowerShell debe enlazar sus parámetros a los valores de entrada.However, when a cmdlet needs to process pipeline input, it must have its parameters bound to input values by the Windows PowerShell runtime. Para ello, debe agregar la ValueFromPipeline palabra clave o agregar la ValueFromPipelineByProperty palabra clave a la declaración del atributo System. Management. Automation. Parameterattribute .To do this, you must add the ValueFromPipeline keyword or add the ValueFromPipelineByProperty keyword to the System.Management.Automation.Parameterattribute attribute declaration. Especifique la ValueFromPipeline palabra clave si el cmdlet tiene acceso al objeto de entrada completo.Specify the ValueFromPipeline keyword if the cmdlet accesses the complete input object. Especifique ValueFromPipelineByProperty si el cmdlet tiene acceso solo a una propiedad del objeto.Specify the ValueFromPipelineByProperty if the cmdlet accesses only a property of the object.

Esta es la declaración de parámetro para el Name parámetro de este cmdlet Get-proc que acepta la entrada de canalización.Here is the parameter declaration for the Name parameter of this Get-Proc cmdlet that accepts pipeline input.

[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

La declaración anterior establece la ValueFromPipeline palabra clave en de true modo que el tiempo de ejecución de Windows PowerShell enlace el parámetro al objeto entrante si el objeto es del mismo tipo que el parámetro, o si se puede convertir en el mismo tipo.The previous declaration sets the ValueFromPipeline keyword to true so that the Windows PowerShell runtime will bind the parameter to the incoming object if the object is the same type as the parameter, or if it can be coerced to the same type. La ValueFromPipelineByPropertyName palabra clave también se establece en para true que el tiempo de ejecución de Windows PowerShell Compruebe el objeto de entrada de una Name propiedad.The ValueFromPipelineByPropertyName keyword is also set to true so that the Windows PowerShell runtime will check the incoming object for a Name property. Si el objeto entrante tiene este tipo de propiedad, el tiempo de ejecución enlazará el Name parámetro a la Name propiedad del objeto entrante.If the incoming object has such a property, the runtime will bind the Name parameter to the Name property of the incoming object.

Nota

La configuración de la ValueFromPipeline palabra clave Attribute para un parámetro tiene prioridad sobre la configuración de la ValueFromPipelineByPropertyName palabra clave.The setting of the ValueFromPipeline attribute keyword for a parameter takes precedence over the setting for the ValueFromPipelineByPropertyName keyword.

Reemplazar un método de procesamiento de entradaOverriding an Input Processing Method

Si el cmdlet controla la entrada de canalización, debe invalidar los métodos de procesamiento de entrada adecuados.If your cmdlet is to handle pipeline input, it needs to override the appropriate input processing methods. Los métodos de procesamiento de entrada básicos se introducen en crear el primer cmdlet.The basic input processing methods are introduced in Creating Your First Cmdlet.

Este cmdlet Get-proc invalida el método System. Management. Automation. cmdlet. ProcessRecord para controlar la entrada de Name parámetro proporcionada por el usuario o un script.This Get-Proc cmdlet overrides the System.Management.Automation.Cmdlet.ProcessRecord method to handle the Name parameter input provided by the user or a script. Este método obtendrá los procesos de cada nombre de proceso solicitado o de todos los procesos si no se proporciona ningún nombre.This method will get the processes for each requested process name or all processes if no name is provided. Tenga en cuenta que en System. Management. Automation. cmdlet. ProcessRecord, la llamada a writeObject (System. Object, System. Boolean) es el mecanismo de salida para enviar objetos de salida a la canalización.Notice that within System.Management.Automation.Cmdlet.ProcessRecord, the call to WriteObject(System.Object,System.Boolean) is the output mechanism for sending output objects to the pipeline. El segundo parámetro de esta llamada, enumerateCollection , se establece en true para indicar al tiempo de ejecución de Windows PowerShell que Enumere la matriz de objetos de proceso y que escriba un proceso cada vez en la línea de comandos.The second parameter of this call, enumerateCollection, is set to true to tell the Windows PowerShell runtime to enumerate the array of process objects, and write one process at a time to the command line.

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

Ejemplo de códigoCode Sample

Para obtener el código de ejemplo de C# completo, vea el ejemplo GetProcessSample03.For the complete C# sample code, see GetProcessSample03 Sample.

Definir tipos de objeto y formatoDefining Object Types and Formatting

Windows PowerShell pasa información entre cmdlets mediante objetos .net.Windows PowerShell passes information between cmdlets using .Net objects. Por lo tanto, es posible que un cmdlet tenga que definir su propio tipo o que el cmdlet tenga que extender un tipo existente proporcionado por otro cmdlet.Consequently, a cmdlet may need to define its own type, or the cmdlet may need to extend an existing type provided by another cmdlet. Para obtener más información sobre la definición de nuevos tipos o la extensión de tipos existentes, vea extender tipos de objeto y formato.For more information about defining new types or extending existing types, see Extending Object Types and Formatting.

Compilación del cmdletBuilding the Cmdlet

Después de implementar un cmdlet, debe registrarse con Windows PowerShell a través de un complemento de Windows PowerShell.After implementing a cmdlet it must be registered with Windows PowerShell through a Windows PowerShell snap-in. Para obtener más información acerca del registro de cmdlets, consulte Cómo registrar cmdlets, proveedores y aplicaciones host.For more information about registering cmdlets, see How to Register Cmdlets, Providers, and Host Applications.

Prueba del cmdletTesting the Cmdlet

Cuando el cmdlet se haya registrado con Windows PowerShell, pruébelo en la línea de comandos.When your cmdlet has been registered with Windows PowerShell, test it by running it on the command line. Por ejemplo, pruebe el código para el cmdlet de ejemplo.For example, test the code for the sample cmdlet. Para obtener más información sobre el uso de cmdlets desde la línea de comandos, consulte la Introducción con Windows PowerShell.For more information about using cmdlets from the command line, see the Getting Started with Windows PowerShell.

  • En el símbolo del sistema de Windows PowerShell, escriba los siguientes comandos para recuperar los nombres de los procesos a través de la canalización.At the Windows PowerShell prompt, enter the following commands to retrieve the process names through the pipeline.

    PS> type ProcessNames | get-proc
    

    Aparece el siguiente resultado.The following output appears.

    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
    
  • Escriba las líneas siguientes para obtener los objetos de proceso que tienen una Name propiedad de los procesos denominados "iexplore".Enter the following lines to get the process objects that have a Name property from the processes called "IEXPLORE". En este ejemplo se usa el Get-Process cmdlet (proporcionado por Windows PowerShell) como un comando de nivel superior para recuperar los procesos de "iexplore".This example uses the Get-Process cmdlet (provided by Windows PowerShell) as an upstream command to retrieve the "IEXPLORE" processes.

    PS> get-process iexplore | get-proc
    

    Aparece el siguiente resultado.The following output appears.

    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 tambiénSee Also

Agregar parámetros que procesan la entrada de la línea de comandosAdding Parameters that Process Command Line Input

Creación del primer cmdletCreating Your First Cmdlet

Extender tipos de objeto y formatoExtending Object Types and Formatting

Cómo registrar cmdlets, proveedores y aplicaciones hostHow to Register Cmdlets, Providers, and Host Applications

Referencia de Windows PowerShellWindows PowerShell Reference

Ejemplos de cmdletCmdlet Samples