Agregar mensajes de usuario a su cmdlet

Los cmdlets pueden escribir varios tipos de mensajes que el tiempo de ejecución de Windows PowerShell puede mostrar al usuario. Estos mensajes incluyen los siguientes tipos:

• Mensajes detallados que contienen información general del usuario.

• Mensajes de depuración que contienen información de solución de problemas.

• Mensajes de advertencia que contienen una notificación de que el cmdlet está a punto de realizar una operación que puede tener resultados inesperados.

• Mensajes de informe de progreso que contienen información sobre cuánto trabajo ha completado el cmdlet al realizar una operación que lleva mucho tiempo.

No hay límites para la cantidad de mensajes que su cmdlet puede escribir ni para el tipo de mensajes que escribe su cmdlet. Cada mensaje se escribe realizando una llamada específica desde el método de procesamiento de entrada de su cmdlet.

Definición del cmdlet

El primer paso en la creación de un cmdlet es siempre nombrar el cmdlet y declarar la clase .NET que implementa el cmdlet. Cualquier tipo de cmdlet puede escribir notificaciones de usuario desde sus métodos de procesamiento de entrada; por lo tanto, en general, puede nombrar este cmdlet utilizando cualquier verbo que indique qué modificaciones del sistema realiza el cmdlet. Para obtener más información sobre los verbos de cmdlet aprobados, consulte Nombres de verbos de cmdlet.

El cmdlet Stop-Proc está diseñado para modificar el sistema; por lo tanto, la declaración System.Management.Automation.CmdletAttribute para la clase .NET debe incluir la palabra clave del atributo SupportsShouldProcess y establecerse en true.

El siguiente código es la definición de esta clase de cmdlet Stop-Proc. Para obtener más información sobre esta definición, consulte Creación de un cmdlet que modifica el sistema.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

Definición de parámetros para la modificación del sistema

El cmdlet Stop-Proc define tres parámetros: Name, Force y PassThru. Para obtener más información sobre cómo definir estos parámetros, consulte Creación de un cmdlet que modifique el sistema.

Aquí está la declaración de parámetros para el cmdlet Stop-Proc.

[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true
)]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

/// <summary>
/// Specify the Force parameter that allows the user to override
/// the ShouldContinue call to force the stop operation. This
/// parameter should always be used with caution.
/// </summary>
[Parameter]
public SwitchParameter Force
{
  get { return force; }
  set { force = value; }
}
private bool force;

/// <summary>
/// Specify the PassThru parameter that allows the user to specify
/// that the cmdlet should pass the process object down the pipeline
/// after the process has been stopped.
/// </summary>
[Parameter]
public SwitchParameter PassThru
{
  get { return passThru; }
  set { passThru = value; }
}
private bool passThru;

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

Su cmdlet debe anular un método de procesamiento de entrada; la mayoría de las veces será System.Management.Automation.Cmdlet.ProcessRecord. Este cmdlet Stop-Proc anula el método de procesamiento de entrada System.Management.Automation.Cmdlet.ProcessRecord. En esta implementación del cmdlet Stop-Proc, se realizan llamadas para escribir mensajes detallados, mensajes de depuración y mensajes de advertencia.

Escribir un mensaje detallado

El método System.Management.Automation.Cmdlet.WriteVerbose se utiliza para escribir información general a nivel de usuario que no está relacionada con condiciones de error específicas. Luego, el administrador del sistema puede usar esa información para continuar procesando otros comandos. Además, cualquier información escrita utilizando este método debe localizarse según sea necesario.

El siguiente código de este cmdlet Stop-Proc muestra dos llamadas al método System.Management.Automation.Cmdlet.WriteVerbose desde la anulación del método System.Management.Automation.Cmdlet.ProcessRecord.

message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);

message = String.Format("Stopped process \"{0}\", pid {1}.",
                        processName, process.Id);

WriteVerbose(message);

Escribir un mensaje de depuración

El método System.Management.Automation.Cmdlet.WriteDebug se usa para escribir mensajes de depuración que se pueden usar para solucionar problemas del funcionamiento del cmdlet. La llamada se realiza desde un método de procesamiento de entrada.

Las siguientes dos secciones de código del cmdlet Stop-Proc de ejemplo muestran llamadas al método System.Management.Automation.Cmdlet.WriteDebug desde la invalidación del método System.Management.Automation.Cmdlet.ProcessRecord.

Este mensaje de depuración se escribe inmediatamente antes de llamar a System.Management.Automation.Cmdlet.ShouldProcess.

message =
          String.Format("Acquired name for pid {0} : \"{1}\"",
                       process.Id, processName);
WriteDebug(message);

Este mensaje de depuración se escribe inmediatamente antes de llamar a System.Management.Automation.Cmdlet.WriteObject.

message =
         String.Format("Writing process \"{0}\" to pipeline",
         processName);
WriteDebug(message);
WriteObject(process);

Windows PowerShell enruta automáticamente cualquier llamada System.Management.Automation.Cmdlet.WriteDebug a la infraestructura de seguimiento y los cmdlets. Esto permite rastrear las llamadas al método hasta la aplicación de alojamiento, un archivo o un depurador sin tener que realizar ningún trabajo de desarrollo adicional dentro del cmdlet. La siguiente entrada de línea de comandos implementa una operación de seguimiento.

PS> expresión-rastreo stop-proc -archivo proc.log -comando stop-proc bloc de notas

Escribir un mensaje de advertencia

El método System.Management.Automation.Cmdlet.WriteWarning se usa para escribir una advertencia cuando el cmdlet está a punto de realizar una operación que podría tener un resultado inesperado, por ejemplo, sobrescribir un archivo de solo lectura.

El siguiente código del cmdlet Stop-Proc de ejemplo muestra la llamada al método System.Management.Automation.Cmdlet.WriteWarning desde la invalidación del método System.Management.Automation.Cmdlet.ProcessRecord.

 if (criticalProcess)
 {
   message =
             String.Format("Stopping the critical process \"{0}\".",
                           processName);
   WriteWarning(message);
} // if (criticalProcess...

Escribir un mensaje de progreso

System.Management.Automation.Cmdlet.WriteProgress se usa para escribir mensajes de progreso cuando las operaciones de cmdlet tardan mucho tiempo en completarse. Una llamada a System.Management.Automation.Cmdlet.WriteProgress pasa un objeto System.Management.Automation.Progressrecord que se envía a la aplicación de hospedaje para representarlo al usuario.

El siguiente código es un ejemplo de un mensaje de progreso escrito por un cmdlet que intenta copiar un elemento.

int myId = 0;
string myActivity = "Copy-item: Copying *.* to c:\abc";
string myStatus = "Copying file bar.txt";
ProgressRecord pr = new ProgressRecord(myId, myActivity, myStatus);
WriteProgress(pr);

pr.RecordType = ProgressRecordType.Completed;
WriteProgress(pr);

Ejemplo de código

Para obtener el código de muestra completo de C#, consulte Ejemplo StopProcessSample02.

Definir tipos de objetos y formato

Windows PowerShell pasa información entre cmdlets mediante objetos .NET. En consecuencia, es posible que un cmdlet deba definir su propio tipo o que el cmdlet deba ampliar un tipo existente proporcionado por otro cmdlet. Para obtener más información sobre cómo definir nuevos tipos o ampliar tipos existentes, consulte Ampliación de tipos de objetos y formato.

Construyendo el cmdlet

Después de implementar un cmdlet, se debe registrar en Windows PowerShell a través de un complemento de Windows PowerShell. Para obtener más información sobre el registro de cmdlets, consulte Cómo registrar cmdlets, proveedores y aplicaciones host.

Probando el cmdlet

Cuando su cmdlet se haya registrado en Windows PowerShell, puede probarlo ejecutándolo en la línea de comandos. Probemos el cmdlet Stop-Proc de muestra. Para obtener más información sobre el uso de cmdlets desde la línea de comandos, consulte Introducción a Windows PowerShell.

• La siguiente entrada de línea de comandos utiliza Stop-Proc para detener el proceso denominado "NOTEPAD", proporcionar notificaciones detalladas e imprimir información de depuración.

  PS> stop-proc -Name notepad -Verbose -Debug
  

  Aparece el siguiente resultado.

  VERBOSE: Attempting to stop process " notepad ".
  DEBUG: Acquired name for pid 5584 : "notepad"
  
  Confirm
  Continue with this operation?
  [Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"): Y
  
  Confirm
  Are you sure you want to perform this action?
  Performing operation "stop-proc" on Target "notepad (5584)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  VERBOSE: Stopped process "notepad", pid 5584.
  

Ver también

Crear un cmdlet que modifique el sistema

Cómo crear un cmdlet de Windows PowerShell

Ampliación de tipos de objetos y formato

Cómo registrar cmdlets, proveedores y aplicaciones host

SDK de Windows PowerShell