Creación de un cmdlet sin parámetrosCreating a Cmdlet without Parameters

En esta sección se describe cómo crear un cmdlet que recupera información del equipo local sin el uso de parámetros y, a continuación, escribe la información en la canalización.This section describes how to create a cmdlet that retrieves information from the local computer without the use of parameters, and then writes the information to the pipeline. El cmdlet descrito aquí es un cmdlet Get-Proc que recupera información sobre los procesos del equipo local y, a continuación, muestra esa información en la línea de comandos.The cmdlet described here is a Get-Proc cmdlet that retrieves information about the processes of the local computer, and then displays that information at the command line.

Nota

Tenga en cuenta que al escribir cmdlets, los ensamblados de referencia de® de Windows PowerShell se descargan en el disco (de forma predeterminada, en C:\Archivos de Programa\reference Assemblies\Microsoft\WindowsPowerShell\v1.0).Be aware that when writing cmdlets, the Windows PowerShell® reference assemblies are downloaded onto disk (by default at C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). No se instalan en la caché de ensamblados global (GAC).They are not installed in the Global Assembly Cache (GAC).

Asignar nombre al cmdletNaming the Cmdlet

Un nombre de cmdlet consta de un verbo que indica la acción que el cmdlet toma y un sustantivo que indica los elementos sobre los que actúa el cmdlet.A cmdlet name consists of a verb that indicates the action the cmdlet takes and a noun that indicates the items that the cmdlet acts upon. Dado que este cmdlet Get-Proc de ejemplo recupera objetos de proceso, utiliza el verbo "Get", definido por la enumeración System. Management. Automation. Verbscommon y el nombre "proc" para indicar que el cmdlet funciona en elementos de proceso.Because this sample Get-Proc cmdlet retrieves process objects, it uses the verb "Get", defined by the System.Management.Automation.Verbscommon enumeration, and the noun "Proc" to indicate that the cmdlet works on process items.

Al asignar nombres a los cmdlets, no use ninguno de los siguientes caracteres: #, () {} [] &-/\ $;: "' <> | ?When naming cmdlets, do not use any of the following characters: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .@ ` .

Elección de un SustantivoChoosing a Noun

Debe elegir un nombre específico.You should choose a noun that is specific. Es mejor usar un Sustantivo Singular precedido de una versión abreviada del nombre del producto.It is best to use a singular noun prefixed with a shortened version of the product name. Un nombre de cmdlet de ejemplo de este tipo es " Get-SQLServer ".An example cmdlet name of this type is "Get-SQLServer".

Elección de un verboChoosing a Verb

Debe usar un verbo del conjunto de nombres de verbo de cmdlet aprobados.You should use a verb from the set of approved cmdlet verb names. Para obtener más información sobre los verbos de cmdlet aprobados, consulte nombres de verbos de cmdlet.For more information about the approved cmdlet verbs, see Cmdlet Verb Names.

Definir la clase de cmdletDefining the Cmdlet Class

Una vez que haya elegido un nombre de cmdlet, defina una clase .NET para implementar el cmdlet.Once you have chosen a cmdlet name, define a .NET class to implement the cmdlet. Esta es la definición de clase de este cmdlet Get-Proc de ejemplo:Here is the class definition for this sample Get-Proc cmdlet:

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

Observe que antes de la definición de clase, el atributo System. Management. Automation. CmdletAttribute , con la sintaxis [Cmdlet(verb, noun, ...)] , se usa para identificar esta clase como un cmdlet.Notice that previous to the class definition, the System.Management.Automation.CmdletAttribute attribute, with the syntax [Cmdlet(verb, noun, ...)], is used to identify this class as a cmdlet. Este es el único atributo necesario para todos los cmdlets y permite que el tiempo de ejecución de Windows PowerShell los llame correctamente.This is the only required attribute for all cmdlets, and it allows the Windows PowerShell runtime to call them correctly. Puede establecer palabras clave de atributo para declarar más la clase si es necesario.You can set attribute keywords to further declare the class if necessary. Tenga en cuenta que la declaración de atributo para la clase GetProcCommand de ejemplo declara solo los nombres de nombre y verbo del cmdlet Get-Proc.Be aware that the attribute declaration for our sample GetProcCommand class declares only the noun and verb names for the Get-Proc cmdlet.

Nota

Para todas las clases de atributos de Windows PowerShell, las palabras clave que se pueden establecer corresponden a las propiedades de la clase de atributo.For all Windows PowerShell attribute classes, the keywords that you can set correspond to properties of the attribute class.

Al asignar un nombre a la clase del cmdlet, se recomienda reflejar el nombre del cmdlet en el nombre de clase.When naming the class of the cmdlet, it is a good practice to reflect the cmdlet name in the class name. Para ello, use el formato "VerbNounCommand" y reemplace "Verb" y "Sustantivo" por el verbo y el sustantivo usados en el nombre del cmdlet.To do this, use the form "VerbNounCommand" and replace "Verb" and "Noun" with the verb and noun used in the cmdlet name. Como se muestra en la definición de clase anterior, el cmdlet Get-Proc de ejemplo define una clase denominada GetProcCommand, que deriva de la clase base System. Management. Automation. cmdlet .As is shown in the previous class definition, the sample Get-Proc cmdlet defines a class called GetProcCommand, which derives from the System.Management.Automation.Cmdlet base class.

Importante

Si desea definir un cmdlet que tenga acceso directamente al tiempo de ejecución de Windows PowerShell, la clase .NET debe derivarse de la clase base System. Management. Automation. PSCmdlet .If you want to define a cmdlet that accesses the Windows PowerShell runtime directly, your .NET class should derive from the System.Management.Automation.PSCmdlet base class. Para obtener más información sobre esta clase, consulte crear un cmdlet que defina conjuntos de parámetros.For more information about this class, see Creating a Cmdlet that Defines Parameter Sets.

Nota

La clase de un cmdlet debe marcarse explícitamente como Public.The class for a cmdlet must be explicitly marked as public. Las clases que no están marcadas como públicas tendrán como valor predeterminado Internal y el tiempo de ejecución de Windows PowerShell no las encontrará.Classes that are not marked as public will default to internal and will not be found by the Windows PowerShell runtime.

Windows PowerShell usa el espacio de nombres Microsoft. PowerShell. Commands para sus clases de cmdlet.Windows PowerShell uses the Microsoft.PowerShell.Commands namespace for its cmdlet classes. Se recomienda colocar las clases de cmdlet en un espacio de nombres de comandos del espacio de nombres de la API, por ejemplo, xxx. PS. Commands.It is recommended to place your cmdlet classes in a Commands namespace of your API namespace, for example, xxx.PS.Commands.

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

La clase System. Management. Automation. cmdlet proporciona tres métodos de procesamiento de entrada principales, al menos uno de los cuales el cmdlet debe reemplazar.The System.Management.Automation.Cmdlet class provides three main input processing methods, at least one of which your cmdlet must override. Para obtener más información sobre cómo Windows PowerShell procesa los registros, vea Cómo funciona Windows PowerShell.For more information about how Windows PowerShell processes records, see How Windows PowerShell Works.

En el caso de todos los tipos de entrada, el tiempo de ejecución de Windows PowerShell llama a System. Management. Automation. cmdlet. BeginProcessing para habilitar el procesamiento.For all types of input, the Windows PowerShell runtime calls System.Management.Automation.Cmdlet.BeginProcessing to enable processing. Si el cmdlet debe realizar algún proceso de preprocesamiento o configuración, puede hacerlo invalidando este método.If your cmdlet must perform some preprocessing or setup, it can do this by overriding this method.

Nota

Windows PowerShell usa el término "registro" para describir el conjunto de valores de parámetro proporcionados cuando se llama a un cmdlet.Windows PowerShell uses the term "record" to describe the set of parameter values supplied when a cmdlet is called.

Si el cmdlet acepta la entrada de canalización, debe invalidar el método System. Management. Automation. cmdlet. ProcessRecord y, opcionalmente, el método System. Management. Automation. cmdlet. EndProcessing .If your cmdlet accepts pipeline input, it must override the System.Management.Automation.Cmdlet.ProcessRecord method, and optionally the System.Management.Automation.Cmdlet.EndProcessing method. Por ejemplo, un cmdlet podría invalidar ambos métodos si recopila toda la entrada mediante System. Management. Automation. cmdlet. ProcessRecord y, a continuación, opera en la entrada como un conjunto en lugar de un elemento a la vez, como Sort-Object hace el cmdlet.For example, a cmdlet might override both methods if it gathers all input using System.Management.Automation.Cmdlet.ProcessRecord and then operates on the input as a whole rather than one element at a time, as the Sort-Object cmdlet does.

Si el cmdlet no toma la entrada de canalización, debe invalidar el método System. Management. Automation. cmdlet. EndProcessing .If your cmdlet does not take pipeline input, it should override the System.Management.Automation.Cmdlet.EndProcessing method. Tenga en cuenta que este método se usa con frecuencia en lugar de System. Management. Automation. cmdlet. BeginProcessing cuando el cmdlet no puede operar en un elemento cada vez, como es el caso de un cmdlet de ordenación.Be aware that this method is frequently used in place of System.Management.Automation.Cmdlet.BeginProcessing when the cmdlet cannot operate on one element at a time, as is the case for a sorting cmdlet.

Dado que este ejemplo Get-Proc cmdlet debe recibir la entrada de canalización, invalida el método System. Management. Automation. cmdlet. ProcessRecord y usa las implementaciones predeterminadas para System. Management. Automation. cmdlet. BeginProcessing y System. Management. Automation. cmdlet. EndProcessing.Because this sample Get-Proc cmdlet must receive pipeline input, it overrides the System.Management.Automation.Cmdlet.ProcessRecord method and uses the default implementations for System.Management.Automation.Cmdlet.BeginProcessing and System.Management.Automation.Cmdlet.EndProcessing. La invalidación System. Management. Automation. cmdlet. ProcessRecord recupera los procesos y los escribe en la línea de comandos mediante el método System. Management. Automation. cmdlet. writeObject .The System.Management.Automation.Cmdlet.ProcessRecord override retrieves processes and writes them to the command line using the System.Management.Automation.Cmdlet.WriteObject method.

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}
Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

Aspectos que se deben recordar sobre el procesamiento de entradasThings to Remember About Input Processing

  • El origen predeterminado de la entrada es un objeto explícito (por ejemplo, una cadena) proporcionado por el usuario en la línea de comandos.The default source for input is an explicit object (for example, a string) provided by the user on the command line. Para obtener más información, vea crear un cmdlet para procesar la entrada de la línea de comandos.For more information, see Creating a Cmdlet to Process Command Line Input.

  • Un método de procesamiento de entrada también puede recibir la entrada del objeto de salida de un cmdlet de nivel superior en la canalización.An input processing method can also receive input from the output object of an upstream cmdlet on the pipeline. Para obtener más información, vea crear un cmdlet para procesar la entrada de canalización.For more information, see Creating a Cmdlet to Process Pipeline Input. Tenga en cuenta que el cmdlet puede recibir la entrada de una combinación de orígenes de línea de comandos y de canalización.Be aware that your cmdlet can receive input from a combination of command-line and pipeline sources.

  • Es posible que el cmdlet de nivel inferior no devuelva mucho tiempo o que no se encuentre en absoluto.The downstream cmdlet might not return for a long time, or not at all. Por ese motivo, el método de procesamiento de entrada del cmdlet no debe mantener bloqueos durante las llamadas a System. Management. Automation. cmdlet. writeObject, especialmente los bloqueos para los que el ámbito se extiende más allá de la instancia del cmdlet.For that reason, the input processing method in your cmdlet should not hold locks during calls to System.Management.Automation.Cmdlet.WriteObject, especially locks for which the scope extends beyond the cmdlet instance.

Importante

Los cmdlets nunca deben llamar a System. Console. WriteLine * ni a su equivalente.Cmdlets should never call System.Console.Writeline* or its equivalent.

Por ejemplo, no se puede llamar a System. Management. Automation. cmdlet. EndProcessing si el cmdlet se cancela a la mitad o si se produce un error de terminación en cualquier parte del cmdlet.For example, System.Management.Automation.Cmdlet.EndProcessing might not be called if the cmdlet is canceled midway or if a terminating error occurs in any part of the cmdlet. Por lo tanto, un cmdlet que requiera la limpieza de objetos debe implementar el patrón System. IDisposable completo, incluido el finalizador, de modo que el tiempo de ejecución pueda llamar a System. Management. Automation. cmdlet. EndProcessing y System. IDisposable. Dispose * al final del procesamiento.Therefore, a cmdlet that requires object cleanup should implement the complete System.IDisposable pattern, including the finalizer, so that the runtime can call both System.Management.Automation.Cmdlet.EndProcessing and System.IDisposable.Dispose* at the end of processing.

Ejemplo de códigoCode Sample

Para obtener el código de ejemplo de C# completo, vea el ejemplo GetProcessSample01.For the complete C# sample code, see GetProcessSample01 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 might need to define its own type, or the cmdlet might 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 registrarlo con Windows PowerShell a través de un complemento de Windows PowerShell.After implementing a cmdlet, you must register it 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 ha registrado con Windows PowerShell, puede probarlo mediante su ejecución en la línea de comandos.When your cmdlet has been registered with Windows PowerShell, you can test it by running it on the command line. El código de nuestro cmdlet Get-Proc de ejemplo es pequeño, pero todavía usa el tiempo de ejecución de Windows PowerShell y un objeto .NET existente, que es suficiente para que sea útil.The code for our sample Get-Proc cmdlet is small, but it still uses the Windows PowerShell runtime and an existing .NET object, which is enough to make it useful. Vamos a probarlo para comprender mejor lo que puede hacer Get-Proc y cómo puede usarse su salida.Let's test it to better understand what Get-Proc can do and how its output can be used. 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.

  1. Inicie Windows PowerShell y obtenga los procesos actuales que se ejecutan en el equipo.Start Windows PowerShell, and get the current processes running on the computer.

    get-proc
    

    Aparece el siguiente resultado.The following output appears.

    Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
    -------  ------  -----  -----  -----  ------  --   ----------
    254      7       7664   12048  66     173.75  1200  QCTRAY
    32       2       1372   2628   31       0.04  1860  DLG
    271      6       1216   3688   33       0.03  3816  lg
    27       2       560    1920   24       0.01  1768  TpScrex
    ...
    
  2. Asigne una variable a los resultados del cmdlet para facilitar la manipulación.Assign a variable to the cmdlet results for easier manipulation.

    $p=get-proc
    
  3. Obtiene el número de procesos.Get the number of processes.

    $p.length
    

    Aparece el siguiente resultado.The following output appears.

    63
    
  4. Recuperar un proceso específico.Retrieve a specific process.

    $p[6]
    

    Aparece el siguiente resultado.The following output appears.

    Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id    ProcessName
    -------  ------  -----  -----  -----  ------  --    -----------
    1033     3       2400   3336   35     0.53    1588  rundll32
    
  5. Obtiene la hora de inicio de este proceso.Get the start time of this process.

    $p[6].starttime
    

    Aparece el siguiente resultado.The following output appears.

    Tuesday, July 26, 2005 9:34:15 AM
    
    $p[6].starttime.dayofyear
    
    207
    
  6. Obtiene los procesos para los que el número de identificadores es mayor que 500 y ordena el resultado.Get the processes for which the handle count is greater than 500, and sort the result.

    $p | Where-Object {$_.HandleCount -gt 500 } | Sort-Object HandleCount
    

    Aparece el siguiente resultado.The following output appears.

    Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
    -------  ------  -----  -----  -----  ------  --   ----------
    568      14      2164   4972   39     5.55    824  svchost
    716       7      2080   5332   28    25.38    468  csrss
    761      21      33060  56608  440  393.56    3300 WINWORD
    791      71      7412   4540   59     3.31    492  winlogon
    ...
    
  7. Use el Get-Member cmdlet para mostrar las propiedades disponibles para cada proceso.Use the Get-Member cmdlet to list the properties available for each process.

    $p | Get-Member -MemberType property
    
        TypeName: System.Diagnostics.Process
    

    Aparece el siguiente resultado.The following output appears.

    Name                     MemberType Definition
    ----                     ---------- ----------
    BasePriority             Property   System.Int32 BasePriority {get;}
    Container                Property   System.ComponentModel.IContainer Conta...
    EnableRaisingEvents      Property   System.Boolean EnableRaisingEvents {ge...
    ...
    

Consulte tambiénSee Also

Crear un cmdlet para procesar la entrada de la línea de comandosCreating a Cmdlet to Process Command Line Input

Crear un cmdlet para procesar la entrada de canalizaciónCreating a Cmdlet to Process Pipeline Input

Cómo crear un cmdlet de Windows PowerShellHow to Create a Windows PowerShell Cmdlet

Extender tipos de objeto y formatoExtending Object Types and Formatting

Cómo funciona Windows PowerShellHow Windows PowerShell Works

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