Salida y mensajes de runbooks
Publicada: junio de 2016
Se aplica a: Windows Azure Pack for Windows Server, System Center 2012 R2 Orchestrator
La mayoría de los runbooks de automatización generan alguna forma de salida, como un mensaje de error al usuario o un objeto complejo que será consumido por otro flujo de trabajo. Windows PowerShell ofrece varios flujos para enviar la salida desde un flujo de trabajo.Automatización de administración de servicios funciona con cada uno de estos flujos de forma diferente y hay que seguir los procedimientos recomendados sobre cómo usar cada uno de ellos cuando cree un runbook.
En la tabla siguiente se proporciona una breve descripción de cada uno de los flujos y su comportamiento en el Portal de administración cuando se ejecuta un runbook publicado y cuando se prueba un runbook. En las secciones siguientes se proporciona más información sobre cada flujo.
Transmitir |
Descripción |
Publicado |
Comprobación |
|---|---|---|---|
Salida |
Objetos destinados a ser consumidos por otros runbooks. |
Se escribe en el historial de trabajos. |
Se muestra en el panel de salida de la prueba. |
Advertencia |
Mensaje de advertencia destinado al usuario. |
Se escribe en el historial de trabajos. |
Se muestra en el panel de salida de la prueba. |
Error |
Mensaje de error destinado al usuario. A diferencia de una excepción, el runbook continúa después de un mensaje de error de forma predeterminada. |
Se escribe en el historial de trabajos. |
Se muestra en el panel de salida de la prueba. |
Detallado |
Proporciona información general o información para solucionar problemas. |
Se escribe en el historial de trabajos solo si el registro detallado está activado para el runbook. |
Se muestra en el panel de salida de la prueba solo si $VerbosePreference está establecida en Continue en el runbook. |
Progreso |
Registros que se generan automáticamente antes y después de cada actividad del runbook. El runbook no debe intentar crear sus propios registros de progreso porque están dirigidos a un usuario interactivo. |
Se escribe en el historial de trabajos solo si el registro del progreso está activado para el runbook. |
No se muestra en el panel de salida de la prueba. |
Depuración |
Mensajes dirigidos a un usuario interactivo. No debe usarse en runbooks. |
No se escribe en el historial de trabajos. |
No se escribe en el panel de salida de la prueba. |
Flujo de salida
El flujo de salida está diseñado para la salida de los objetos creados por un flujo de trabajo cuando se ejecuta correctamente. En Automatización, este flujo se utiliza principalmente para objetos destinados a ser consumidos por runbooks primarios que llaman al runbook actual. Cuando se llama a un runbook insertado desde un runbook primario, devuelve datos del flujo de salida al elemento primario. Solo debe usar el flujo de salida para comunicar información general al usuario si sabe que ningún otro runbook llamará nunca al runbook. Como procedimiento recomendado, normalmente deberá usar el Flujo detallado para comunicar información general al usuario.
Puede escribir datos en el flujo de salida mediante Write-Output o colocar el objeto en su propia línea en el runbook.
#The following lines both write an object to the output stream.
Write-Object –InputObject $object
$object
Salida de una función
Cuando se escribe en el flujo de salida de una función que está incluida en su runbook, la salida se devuelve al runbook. Si el runbook asigna esa salida a una variable, no se escribe en el flujo de salida. Si se escribe en cualquier otro flujo desde dentro de la función, se escribirá en el flujo correspondiente del runbook.
Considere el runbook de ejemplo siguiente.
Workflow Test-Runbook
{
Write-Verbose "Verbose outside of function"
Write-Output "Output outside of function"
$functionOutput = Test-Function
Function Test-Function
{
Write-Verbose "Verbose inside of function"
Write-Output "Output inside of function"
}
}
El flujo de salida del trabajo del runbook sería:
Output outside of function
El flujo detallado del trabajo del runbook sería:
Verbose outside of function
Verbose inside of function
La variable $functionOutput tendría el valor:
Output inside of function
Declarar los tipos de datos de salida
Un flujo de trabajo puede especificar el tipo de datos de su salida mediante el atributo OutputType. Este atributo no tiene ningún efecto en tiempo de ejecución, pero proporciona al autor del runbook una indicación de la salida esperada en tiempo de diseño. A medida que el conjunto de herramientas de runbooks evolucione, aumentará la importancia de la declaración de tipos de datos de salida en tiempo de diseño. Como resultado, es recomendable incluir esta declaración en los runbooks que cree.
El runbook de ejemplo siguiente genera un objeto de cadena e incluye una declaración de su tipo de salida. Si su runbook genera una matriz de un tipo determinado, todavía debe especificar el tipo en lugar de una matriz del tipo.
Workflow Test-Runbook
{
[OutputType([string])]
$output = "This is some string output."
Write-Output $output
}
Flujos de mensajes
A diferencia del flujo de salida, los flujos de mensajes están diseñados para comunicar información al usuario. Hay varios flujos de mensajes para los diferentes tipos de información y Automatización controla cada uno de forma diferente.
Flujos de error y de advertencia
Los flujos de error y de advertencia están diseñados para registrar los problemas que se producen en un runbook. Se escriben en el historial de trabajos cuando se ejecuta un runbook y se incluyen en el panel de salida de la prueba del Portal de administración cuando se prueba un runbook. De forma predeterminada, el runbook continuará ejecutándose después de un error o advertencia. Para especificar que el runbook debe suspenderse en caso de advertencia o error, puede establecer una variable de preferencia en el runbook antes de crear el mensaje. Por ejemplo, para hacer que un runbook se suspenda en caso de error, tal y como haría una excepción, establezca $ErrorActionPreference en Stop.
Cree un mensaje de advertencia o de error con los cmdlets Write-Warning o Write-Error. También se pueden escribir actividades en estos flujos.
#The following lines create a warning message and then an error message that will suspend the runbook.
$ErrorActionPreference = "Stop"
Write-Warning –Message "This is a warning message."
Write-Error –Message "This is an error message that will stop the runbook because of the preference variable."
Flujo detallado
El flujo de mensajes detallados se utiliza para proporcionar información general acerca del funcionamiento del runbook. Como en los runbooks no está disponible el flujo de depuración, deben utilizarse mensajes detallados para proporcionar información de resolución de problemas. De forma predeterminada, los mensajes detallados de runbooks publicados no se almacenarán en el historial de trabajos. Para almacenar mensajes detallados, configure los runbooks publicados para Escribir registros detallados en la pestaña Configurar del runbook, en el Portal de administración. En la mayoría de los casos, debe mantener el valor predeterminado de no escribir registros detallados para un runbook por motivos de rendimiento. Active esta opción solo para solucionar problemas o depurar un runbook.
El valor predeterminado de la variable $VerbosePreference es SilentlyContinue. No es necesario que cambie esta variable en un runbook publicado para almacenar los mensajes detallados. Sin embargo, si este valor se establece explícitamente en SilentlyContinue en un runbook publicado, los mensajes detallados no se almacenarán aunque el runbook esté configurado para escribir registros detallados.
Cuando se prueba un runbook, los mensajes detallados no se muestran aunque el runbook esté configurado para escribir registros detallados. Para mostrar mensajes detallados al probar un runbook, debe establecer la variable $VerbosePreference en Continue. Cuando esa variable está establecida, los mensajes detallados se muestran en el panel de salida de la prueba del Portal de administración.
Cree un mensaje detallado con el cmdlet Write-Verbose.
#The following line creates a verbose message.
Write-Verbose –Message "This is a verbose message."
Flujo de depuración
El flujo de depuración está diseñado para usarse con un usuario interactivo y no debe usarse en runbooks.
Registros de progreso
Si configura un runbook para escribir registros de progreso (en la pestaña Configurar del runbook, en el Portal de administración), se escribirá un registro en el historial de trabajos antes y después de la ejecución de cada actividad. En la mayoría de los casos, debe mantener el valor predeterminado para no escribir registros detallados para un runbook con el fin de maximizar el rendimiento. Active esta opción solo para solucionar problemas o depurar un runbook. Cuando se prueba un runbook, los mensajes de progreso no se muestran aunque el runbook esté configurado para escribir registros de progreso.
El cmdlet Write-Progress no es válido en un runbook porque está pensado para usarse con un usuario interactivo.
Variables de preferencia
Windows PowerShell usa variables de preferencia para determinar cómo responder a los datos enviados a diferentes flujos de salida. Puede establecer estas variables en un runbook para controlar cómo responderá a los datos enviados a diferentes flujos.
En la tabla siguiente se enumeran las variables de preferencia que pueden usarse en runbooks con sus valores válidos y predeterminados. Tenga en cuenta que esta tabla solo incluye los valores que son válidos en un runbook. Hay otros valores adicionales válidos para las variables de preferencia cuando se usan en Windows PowerShell fuera de Automatización de administración de servicios.
Variable |
Valor predeterminado |
Valores válidos |
|---|---|---|
WarningPreference |
Continue |
Stop |
ErrorActionPreference |
Continue |
Stop |
VerbosePreference |
SilentlyContinue |
Stop |
En la tabla siguiente se muestra el comportamiento de los valores de las variables de preferencia que son válidos en runbooks.
Valor |
Comportamiento |
|---|---|
Continue |
Registra el mensaje y continúa ejecutando el runbook. |
SilentlyContinue |
Continúa la ejecución del runbook sin registrar el mensaje. El efecto es que el mensaje se pasa por alto. |
Stop |
Registra el mensaje y suspende el runbook. |
Recuperar salidas de runbooks y mensajes
Portal de administración
Puede ver los detalles de un trabajo de runbook en el Portal de administración de la pestaña Trabajos de un runbook. El Resumen del trabajo mostrará los parámetros de entrada y el Flujo de salida, además de información general sobre el trabajo y las excepciones que se hayan producido. El Historial incluirá mensajes del flujo de salida y los Flujos de error y de advertencia, además del Flujo detallado y el Registros de progreso si el runbook está configurado para escribir registros detallados y de progreso.
Windows PowerShell
En Windows PowerShell, puede recuperar la salida y los mensajes de un runbook con el cmdlet Get SmaJobOutput. Este cmdlet requiere el identificador del trabajo y tiene un parámetro llamado Flujo donde debe especificar qué flujo se va a devolver. Puede especificar Cualquiera para devolver todos los flujos de trabajo.
En el ejemplo siguiente se inicia un runbook y se espera a que finalice. Una vez completado, se recopila su flujo de salida del trabajo.
$webServer = 'https://MyServer'
$port = 9090
$runbookName = "Test-Runbook"
$job = Start-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName
$doLoop = $true
While ($doLoop) {
$job = Get-SmaJob –WebServiceEndpoint $webServer –Port $port -Id $job.Id
$status = $job.Status
$doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped")
}
Get-SmaJobOutput –WebServiceEndpoint $webServer –Port $port -Id $job.Id –Stream Output
Vea también
Ampliación de Service Management Automation con Runbooks
Runbook Authoring