Creación de un cmdlet sin parámetros

2025-03-25

En esta sección se describe cómo crear un cmdlet que recupere información del equipo local sin el uso de parámetros y, a continuación, escriba la información en la canalización. El cmdlet que se describe aquí es un cmdlet de 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.

Nota:

Tenga en cuenta que al escribir cmdlets, los ensamblados de referencia de Windows PowerShell® se descargan en el disco (de forma predeterminada en C:\Archivos de programa\Ensamblados de referencia\Microsoft\WindowsPowerShell\v1.0). No están instalados en la caché global de ensamblados (GAC).

Asignar un nombre al cmdlet

Un nombre de cmdlet consta de un verbo que indica la acción que realiza el cmdlet y un nombre que indica los elementos en los que actúa el cmdlet. Dado que este cmdlet de Get-Proc de ejemplo recupera objetos de proceso, usa el verbo "Get", definido por el System.Management.Automation.VerbsCommon enumeración y el nombre "Proc" para indicar que el cmdlet funciona en los elementos de proceso.

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

Elección de un nombre

Debe elegir un nombre específico. Es mejor usar un nombre único prefijo con una versión abreviada del nombre del producto. Un nombre de cmdlet de ejemplo de este tipo es "Get-SQLServer".

Elección de un verbo

Debe usar un verbo del conjunto de nombres de verbo de cmdlet aprobados. Para obtener más información sobre los verbos de cmdlet aprobados, consulte Nombres de verbo de cmdlet.

Definición de la clase de cmdlet

Una vez que haya elegido un nombre de cmdlet, defina una clase .NET para implementar el cmdlet. Esta es la definición de clase para este cmdlet de Get-Proc de ejemplo:

[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. Este es el único atributo necesario para todos los cmdlets y permite que el entorno de ejecución de Windows PowerShell los llame correctamente. Puede establecer palabras clave de atributo para declarar aún más la clase si es necesario. Tenga en cuenta que la declaración de atributo de la clase GetProcCommand de ejemplo declara solo los nombres de sustantivo y verbo del cmdlet Get-Proc.

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.

Al asignar un nombre a la clase del cmdlet, se recomienda reflejar el nombre del cmdlet en el nombre de clase. Para ello, use el formulario "VerbNounCommand" y reemplace "Verb" y "Sustantivo" por el verbo y el nombre que se usa en el nombre del cmdlet. Como se muestra en la definición de clase anterior, el cmdlet Get-Proc de ejemplo define una clase denominada GetProcCommand, que se deriva de la clase base System.Management.Automation.Cmdlet .

Importante

Si desea definir un cmdlet que acceda directamente al entorno de ejecución de Windows PowerShell, la clase .NET debe derivar de la clase base System.Management.Automation.PSCmdlet. Para obtener más información sobre esta clase, vea Creating a Cmdlet that Defines Parameter Sets.

Nota:

La clase de un cmdlet debe marcarse explícitamente como pública. Las clases que no están marcadas como públicas tendrán como valor predeterminado interno y el tiempo de ejecución de Windows PowerShell no lo encontrará.

Windows PowerShell usa el espacio de nombres Microsoft.PowerShell.Commands para sus clases de cmdlet. Se recomienda colocar las clases de cmdlet en un espacio de nombres Comandos del espacio de nombres de la API, por ejemplo, xxx.PS. Comandos.

Invalidación de un método de procesamiento de entrada

La clase System.Management.Automation.Cmdlet proporciona tres métodos de procesamiento de entrada principales, al menos uno de los cuales debe invalidar el cmdlet. Para obtener más información sobre cómo Windows PowerShell procesa los registros, vea Funcionamiento de Windows PowerShell.

Para todos los tipos de entrada, el entorno de ejecución de Windows PowerShell llama a System.Management.Automation.Cmdlet.BeginProcessing para habilitar el procesamiento. Si el cmdlet debe realizar algún preprocesamiento o configuración, puede hacerlo invalidando este método.

Nota:

Windows PowerShell usa el término "registro" para describir el conjunto de valores de parámetro proporcionados cuando se llama a un cmdlet.

Si el cmdlet acepta entradas de canalización, debe invalidar el método System.Management.Automation.Cmdlet.ProcessRecord y, opcionalmente, el método System.Management.Automation.Cmdlet.EndProcessing. 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, funciona en la entrada como un todo en lugar de un elemento a la vez, como lo hace el cmdlet Sort-Object.

Si el cmdlet no toma la entrada de canalización, debe invalidar el método System.Management.Automation.Cmdlet.EndProcessing. Tenga en cuenta que este método se usa con frecuencia en lugar de System.Management.Automation.Cmdlet.BeginProcessing cuando el cmdlet no puede funcionar en un elemento a la vez, como sucede con un cmdlet de ordenación.

Dado que este cmdlet de Get-Proc de ejemplo debe recibir entradas 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. El System.Management.Automation.Cmdlet.ProcessRecord invalida recupera los procesos y los escribe en la línea de comandos mediante el método System.Management.Automation.Cmdlet.Write Object.

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

Cosas que recordar sobre el procesamiento de entrada

El origen predeterminado para la entrada es un objeto explícito (por ejemplo, una cadena) proporcionado por el usuario en la línea de comandos. Para obtener más información, consulte Creación de un cmdlet para procesar la entrada de la línea de comandos.
Un método de procesamiento de entrada también puede recibir entradas del objeto de salida de un cmdlet ascendente en la canalización. Para obtener más información, consulte Creación de un cmdlet para procesar la entrada de canalización. Tenga en cuenta que el cmdlet puede recibir entradas de una combinación de orígenes de canalización y línea de comandos.
Es posible que el cmdlet de nivel inferior no devuelva durante mucho tiempo o que no lo haga. Por ese motivo, el método de procesamiento de entrada del cmdlet no debe contener 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.

Importante

Los cmdlets nunca deben llamar a System.Console.Writeline* o a su equivalente.

Es posible que el cmdlet tenga variables de objeto para limpiar cuando termine de procesarse (por ejemplo, si abre un identificador de archivo en el método System.Management.Automation.Cmdlet.BeginProcessing y mantiene el identificador abierto para su uso por System.Management.Automation.Cmdlet.ProcessRecord). Es importante recordar que el tiempo de ejecución de Windows PowerShell no siempre llama al método System.Management.Automation.Cmdlet.EndProcessing, que debe realizar la limpieza de objetos.

Por ejemplo, es posible que no se llame a System.Management.Automation.Cmdlet.EndProcess ing si el cmdlet se cancela a mitad de camino o si se produce un error de terminación en cualquier parte del cmdlet. Por lo tanto, un cmdlet que requiere la limpieza de objetos debe implementar el patrón completo de System.IDisposable, incluido el finalizador, para que el runtime pueda llamar a System.Management.Automation.Cmdlet.EndProcessing y System.IDisposable.Dispose* al final del procesamiento.

Ejemplo de código

Para obtener el código de ejemplo de C# completo, consulte Ejemplo GetProcessSample01.

Definición de tipos de objeto y formato

Windows PowerShell pasa información entre cmdlets mediante objetos .NET. 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. Para obtener más información sobre cómo definir nuevos tipos o ampliar tipos existentes, vea Extensión de tipos de objeto y formato.

Compilación del cmdlet

Después de implementar un cmdlet, debe registrarlo con Windows PowerShell a través de un complemento de Windows PowerShell. Para obtener más información sobre el registro de cmdlets, consulte Registro de cmdlets, proveedores y aplicaciones host.

Prueba del cmdlet

Cuando el cmdlet se haya registrado con Windows PowerShell, puede probarlo ejecutándolo en la línea de comandos. El código de nuestro cmdlet Get-Proc de ejemplo es pequeño, pero sigue usando el entorno de ejecución de Windows PowerShell y un objeto .NET existente, lo que es suficiente para que sea útil. Vamos a probarlo para comprender mejor lo que Get-Proc puede hacer y cómo se puede usar su salida. Para obtener más información sobre el uso de cmdlets desde la línea de comandos, consulte la Introducción a Windows PowerShell.

Inicie Windows PowerShell y obtenga los procesos actuales que se ejecutan en el equipo.

Get-Proc

Aparece la salida siguiente.

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
...

Asigne una variable a los resultados del cmdlet para facilitar la manipulación.
```
$p=Get-Proc
```
Obtenga el número de procesos.
```
$p.Length
```
Aparece la salida siguiente.
```
63
```

Recuperar un proceso específico.

$p[6]

Aparece la salida siguiente.

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id    ProcessName
-------  ------  -----  -----  -----  ------  --    -----------
1033     3       2400   3336   35     0.53    1588  rundll32

Obtenga la hora de inicio de este proceso.

$p[6].StartTime

Aparece la salida siguiente.

Tuesday, July 26, 2005 9:34:15 AM

$p[6].StartTime.DayOfYear

Obtenga los procesos para los que el recuento de identificadores es mayor que 500 y ordene el resultado.

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

Aparece la salida siguiente.

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
...

Use el cmdlet Get-Member para enumerar las propiedades disponibles para cada proceso.

$p | Get-Member -MemberType Property

    TypeName: System.Diagnostics.Process

Aparece la salida siguiente.

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