Adición de mensajes de usuario al cmdlet

Los cmdlets pueden escribir varios tipos de mensajes que el entorno 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.

• Depuración de mensajes 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 tarda mucho tiempo.

No hay límites en el número de mensajes que el cmdlet puede escribir ni en el tipo de mensajes que escribe el cmdlet. Cada mensaje se escribe realizando una llamada específica desde el método de procesamiento de entrada del cmdlet.

Definición del cmdlet

El primer paso en la creación de cmdlets es asignar siempre un nombre al 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 mediante cualquier verbo que indique qué modificaciones del sistema realiza el cmdlet. Para obtener más información sobre los verbos de cmdlet aprobados, vea 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 de la clase .NET debe incluir la palabra clave SupportsShouldProcess attribute y establecerse en true .

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

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

Definir 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, vea Crear un cmdlet que modifica el sistema.

Esta es 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;

Invalidar un método de procesamiento de entrada

El cmdlet debe invalidar un método de procesamiento de entrada, con frecuencia será System.Management.Automation.Cmdlet.ProcessRecord. Este Stop-Proc cmdlet invalida 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, depurar mensajes y mensajes de advertencia.

Nota

Para obtener más información sobre cómo este método llama a los métodos System.Management.Automation.Cmdlet.ShouldProcess y System.Management.Automation.Cmdlet.ShouldContinue, vea Creating a Cmdlet that Modifes the System.

Escribir un mensaje detallado

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

El código siguiente de este cmdlet Stop-Proc muestra dos llamadas al método System.Management.Automation.Cmdlet.WriteVerbose desde la invalidació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.

Nota

Windows PowerShell define un Debug parámetro que presenta información detallada y de depuración. Si el cmdlet admite este parámetro, no es necesario llamar a System.Management.Automation.Cmdlet.WriteDebug en el mismo código que llama a System.Management.Automation.Cmdlet.WriteVerbose.

Las dos secciones de código siguientes 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 a System.Management.Automation.Cmdlet.WriteDebug a la infraestructura y los cmdlets de seguimiento. Esto permite realizar un seguimiento de las llamadas de método a la aplicación de hospedaje, 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> trace-expression stop-proc -file proc.log -command stop-proc notepad

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 código siguiente del cmdlet Stop-Proc 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 tardaron 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.

Nota

Este Stop-Proc cmdlet no incluye una llamada al método System.Management.Automation.Cmdlet.WriteProgress.

El código siguiente es un ejemplo de un mensaje de progreso escrito por un cmdlet que está intentando 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 ejemplo completo de C#, vea StopProcessSample02 Sample.

Definir 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 ampliar un tipo existente proporcionado por otro cmdlet. Para obtener más información sobre cómo definir nuevos tipos o ampliar los tipos existentes, vea Extender tipos de objetos y Aplicar formatoa .

Compilar el cmdlet

Después de implementar un cmdlet, se debe registrar con Windows PowerShell a través de un Windows PowerShell complemento. Para obtener más información sobre cómo registrar cmdlets, vea How to Register Cmdlets, Providers, and Host Applications.

Prueba del cmdlet

Cuando el cmdlet se haya registrado con Windows PowerShell, puede probarlo ejecutándose en la línea de comandos. Vamos a probar el cmdlet de Stop-Proc ejemplo. Para obtener más información sobre el uso de cmdlets desde la línea de comandos, vea el Tareas iniciales con Windows PowerShell.

• La siguiente entrada de línea de comandos usa 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.
  

Consulte también

Creación de un cmdlet que modifica el sistema

Cómo crear un cmdlet Windows PowerShell

Extensión de tipos de objeto y formato

Cómo registrar cmdlets, proveedores y aplicaciones host

Windows PowerShell SDK