Tipos de salida de cmdlet
PowerShell proporciona varios métodos a los que los cmdlets pueden llamar para generar resultados. Estos métodos utilizan una operación específica para escribir su salida en un flujo de datos específico, como el flujo de datos de éxito o el flujo de datos de error. Este artículo describe los tipos de resultados y los métodos utilizados para generarlos.
Tipos de salida
Salida exitosa
Los cmdlets pueden informar el éxito al devolver un objeto que puede ser procesado por el siguiente comando de la canalización. Una vez que el cmdlet ha realizado correctamente su acción, llama al método System.Management.Automation.Cmdlet.WriteObject. Le recomendamos que llame a este método en lugar de a los métodos System.Console.WriteLine o System.Management.Automation.Host.PSHostUserInterface.WriteLine.
Puede proporcionar un parámetro de modificador PassThru para cmdlets que normalmente no devuelven objetos. Cuando se especifica el parámetro de modificador PassThru en la línea de comando, se solicita al cmdlet que devuelva un objeto. Para ver un ejemplo de un cmdlet que tiene un parámetro PassThru, consulte Agregar historial.
Salida de error
Los cmdlets pueden informar errores. Cuando se produce un error de terminación, el cmdlet genera una excepción. Cuando se produce un error que no termina, el cmdlet llama al método System.Management.Automation.Provider.CmdletProvider.WriteError para enviar un registro de error al flujo de datos de error. Para obtener más información sobre los informes de errores, consulte Conceptos de informes de errores.
Salida detallada
Los cmdlets pueden proporcionarle información útil mientras el cmdlet procesa registros correctamente llamando al método System.Management.Automation.Cmdlet.WriteVerbose. El método genera mensajes detallados que indican cómo se desarrolla la acción.
De forma predeterminada, no se muestran mensajes detallados. Puede especificar el parámetro Detallado cuando se ejecuta el cmdlet para mostrar estos mensajes. Detallado es un parámetro común que está disponible para todos los cmdlets.
Salida de progreso
Los cmdlets pueden proporcionarle información de progreso cuando el cmdlet realiza tareas que tardan mucho en completarse, como copiar un directorio de forma recursiva. Para mostrar información de progreso, el cmdlet llama al método System.Management.Automation.Cmdlet.WriteProgress.
Salida de depuración
Los cmdlets pueden proporcionar mensajes de depuración que resultan útiles a la hora de solucionar problemas del código del cmdlet. Para mostrar información de depuración, el cmdlet llama al método System.Management.Automation.Cmdlet.WriteDebug.
De forma predeterminada, los mensajes de depuración no se muestran. Puede especificar el parámetro Debug cuando se ejecuta el cmdlet para mostrar estos mensajes. Debug es un parámetro común que está disponible para todos los cmdlets.
Salida de advertencia
Los cmdlets pueden mostrar mensajes de advertencia llamando al método System.Management.Automation.Cmdlet.WriteWarning.
De forma predeterminada, se muestran mensajes de advertencia. Sin embargo, puede configurar mensajes de advertencia mediante la variable $WarningPreference o mediante los parámetros Verbose y Debug cuando se llama al cmdlet.
Mostrando salida
Para todas las llamadas al método de escritura, la visualización del contenido está determinada por variables de tiempo de ejecución específicas. La excepción es el método System.Management.Automation.Cmdlet.WriteObject. Al utilizar estas variables, puede realizar la llamada de escritura adecuada en el lugar correcto de su código y no preocuparse por cuándo o si se debe mostrar la salida.
Acceder a la funcionalidad de salida de una aplicación host
También puede diseñar un cmdlet para acceder directamente a la funcionalidad de salida de una aplicación host a través del tiempo de ejecución de PowerShell. El uso de las API de host proporcionadas por PowerShell en lugar de System.Console o System.Windows.Forms garantiza que su cmdlet funcionará con una variedad de hosts. Por ejemplo: el host de la consola powershell.exe, el host gráfico powershell_ise.exe, el host de comunicación remota de PowerShell y hosts de terceros.
Ver también
Conceptos de informes de errores
Descripción general del cmdlet
Escribir un cmdlet de Windows PowerShell