Salida y mensajes de runbooksRunbook Output and Messages

Se aplica a: Paquete de Windows Azure para Windows Server, System Center 2016 - Service Management AutomationApplies To: Windows Azure Pack for Windows Server, System Center 2016- Service Management Automation

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.Most Automation runbooks will have some form of output such as an error message to the user or a complex object intended to be consumed by another workflow. Windows PowerShell ofrece varios flujos para enviar la salida desde un flujo de trabajo.Windows PowerShell provides multiple streams to send output from a workflow. Service Management Automation funciona con cada una de estas secuencias de forma diferente, y debe seguir las prácticas recomendadas sobre cómo usar cada uno de ellos cuando se crea un runbook.Service Management Automation works with each of these streams differently, and you should follow best practices for how to use each when you are creating a runbook.

En la tabla siguiente 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 probar un runbook.The following table provides a brief description of each of the streams and their behavior in the Management Portal both when running a published runbook and when testing a runbook. En las secciones siguientes se proporciona más información sobre cada flujo.Further details on each stream are provided in subsequent sections.

TransmitirStream DescripciónDescription PublicadoPublished ComprobaciónTest
SalidaOutput Objetos destinados a ser consumidos por otros runbooks.Objects intended to be consumed by other runbooks. Se escribe en el historial de trabajos.Written to the job history. Se muestra en el panel de salida de la prueba.Displayed in the Test Output Pane.
AdvertenciaWarning Mensaje de advertencia destinado al usuario.Warning message intended for the user. Se escribe en el historial de trabajos.Written to the job history. Se muestra en el panel de salida de la prueba.Displayed in the Test Output Pane.
ErrorError Mensaje de error destinado al usuario.Error message intended for the user. A diferencia de una excepción, el runbook continúa después de un mensaje de error de forma predeterminada.Unlike an exception, the runbook continues after an error message by default. Se escribe en el historial de trabajos.Written to the job history. Se muestra en el panel de salida de la prueba.Displayed in the Test Output Pane.
DetalladoVerbose Proporciona información general o información para solucionar problemas.Messages providing general or troubleshooting information. Se escribe en el historial de trabajos solo si el registro detallado está activado para el runbook.Written to job history only if verbose logging is turned on for the runbook. Muestra en el panel de resultados de pruebas solo si $VerbosePreference está establecido en continuar en el runbook.Displayed in the Test Output pane only if $VerbosePreference is set to Continue in the runbook.
ProgresoProgress Registros que se generan automáticamente antes y después de cada actividad del runbook.Records automatically generated before and after each activity in the runbook. El runbook no debe intentar crear sus propios registros de progreso porque están dirigidos a un usuario interactivo.The runbook should not attempt to create its own progress records since they are intended for an interactive user. Se escribe en el historial de trabajos solo si el registro del progreso está activado para el runbook.Written to job history only if progress logging is turned on for the runbook. No se muestra en el panel de salida de la prueba.Not displayed in the Test Output Pane.
DepuraciónDebug Mensajes dirigidos a un usuario interactivo.Messages intended for an interactive user. No debe usarse en runbooks.Should not be used in runbooks. No se escribe en el historial de trabajos.Not written to job history. No se escribe en el panel de salida de la prueba.Not written to Test Output Pane.

Flujo de salidaOutput Stream

El flujo de salida está diseñado para la salida de los objetos creados por un flujo de trabajo cuando se ejecuta correctamente.The Output stream is intended for output of objects created by a workflow when it runs correctly. En la automatización, este flujo se utiliza principalmente para objetos destinados a ser consumidos por runbooks primarios que llaman al runbook actual.In Automation, this stream is primarily used for objects intended to be consumed by parent runbooks that call the current runbook. Cuando se llama a un runbook insertado desde un runbook primario, devuelve datos de la secuencia de salida al elemento primario.When you call a runbook inline from a parent runbook, it returns data from the output stream to the parent. 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.You should only use the output stream to communicate general information back to the user if you know the runbook will never be called by another runbook. Como práctica recomendada, sin embargo, normalmente debería usar el flujo detallado para comunicar información general al usuario.As a best practice, however, you should typically use the Verbose Stream to communicate general information to the user.

Puede escribir datos en el flujo de salida mediante Write-Output o colocar el objeto en su propia línea en el runbook.You can write data to the output stream using Write-Output or by putting the object on its own line in the runbook.

#The following lines both write an object to the output stream.
Write-Object "InputObject $object
$object

Salida de una funciónOutput from a Function

Cuando se escribe en el flujo de salida de una función que está incluida en su runbook, la salida se devuelve al runbook.When you write to the output stream in a function that is included in your runbook, the output is passed back to the runbook. Si el runbook asigna esa salida a una variable, no se escribe en el flujo de salida.If the runbook assigns that output to a variable, then it is not written to the output stream. Si se escribe en cualquier otro flujo desde dentro de la función, se escribirá en el flujo correspondiente del runbook.Writing to any other streams from within the function will write to the corresponding stream for the runbook.

Considere el runbook de ejemplo siguiente.Consider the following sample runbook.

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:The output stream for the runbook job would be:

Output outside of function

El flujo detallado del trabajo del runbook sería:The verbose stream for the runbook job would be:

Verbose outside of function
Verbose inside of function

La variable $functionOutput tendría el valor:The $functionOutput variable would have the value:

Output inside of function

Declarar los tipos de datos de salidaDeclaring Output Data Type

Un flujo de trabajo puede especificar el tipo de datos de su salida mediante el atributo OutputType.A workflow can specify the data type of its output using the OutputType attribute. 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.This attribute has no effect during runtime, but it provides an indication to the runbook author at design time of the expected output of the runbook. 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.As the toolset for runbooks continues to evolve, the importance of declaring output data types at design time will increase in importance. Como resultado, es recomendable incluir esta declaración en los runbooks que cree.As a result, it is a best practice to include this declaration in any runbooks that you create.

El runbook de ejemplo siguiente genera un objeto de cadena e incluye una declaración de su tipo de salida.The following sample runbook outputs a string object and includes a declaration of its output type. Si su runbook genera una matriz de un tipo determinado, todavía debe especificar el tipo en lugar de una matriz del tipo.If your runbook outputs an array of a certain type, then you should still specify the type as opposed to an array of the type.

Workflow Test-Runbook
{
   [OutputType([string])]

   $output = "This is some string output."
   Write-Output $output
}

Flujos de mensajesMessage Streams

A diferencia del flujo de salida, los flujos de mensajes están diseñados para comunicar información al usuario.Unlike the output stream, message streams are intended to communicate information to the user. Hay varios flujos de mensajes para los diferentes tipos de información y cada una se trata de forma diferente mediante la automatización.There are multiple message streams for different kinds of information, and each is handled differently by Automation.

Flujos de Error y advertenciaWarning and Error Streams

Los flujos de error y de advertencia están diseñados para registrar los problemas que se producen en un runbook.The Warning and Error streams are intended to log problems that occur in a 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.They are written to the job history when a runbook is executed, and are included in the Test Output Pane in the Management Portal when a runbook is tested. De forma predeterminada, el runbook continuará ejecutándose después de un error o advertencia.By default, the runbook will continue executing after a warning or error. Puede especificar que el runbook debe suspenderse en una advertencia o error estableciendo un variable de preferencia en el runbook antes de crear el mensaje.You can specify that the runbook should be suspended on a warning or error by setting a preference variable in the runbook before creating the message. 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.For example, to cause a runbook to suspend on an error as it would an exception, set $ErrorActionPreference to Stop.

Cree un mensaje de advertencia o de error con los cmdlets Write-Warning o Write-Error .Create a warning or error message using the Write-Warning or Write-Error cmdlet. También se pueden escribir actividades en estos flujos.Activities may also write to these streams.

#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 detalladoVerbose Stream

El flujo de mensajes detallados se utiliza para proporcionar información general acerca del funcionamiento del runbook.The Verbose message stream is for general information about the runbook operation. Puesto que la flujo de depuración no está disponible en un runbook, deben utilizarse mensajes detallados para obtener información de solución de problemas.Since the Debug Stream is not available in a runbook, verbose messages should be used for troubleshooting information. De forma predeterminada, los mensajes detallados de runbooks publicados no se almacenarán en el historial de trabajos.By default, verbose messages from published runbooks will not be stored in the job history. 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.To store verbose messages, configure published runbooks to Log Verbose Records on the Configure tab of the runbook in the Management Portal. En la mayoría de los casos, debe mantener el valor predeterminado de no escribir registros detallados para un runbook por motivos de rendimiento.In most cases, you should keep the default setting of not logging verbose records for a runbook for performance reasons. Active esta opción solo para solucionar problemas o depurar un runbook.Turn on this option only to troubleshoot or debug a runbook.

El valor predeterminado de la variable $VerbosePreference es SilentlyContinue.The $VerbosePreference variable defaults to a value of SilentlyContinue. No es necesario que cambie esta variable en un runbook publicado para almacenar los mensajes detallados.You do not need to change this variable in a published runbook for verbose messages to be stored. 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.If this value is explicitly set to SilentlyContinue in a published runbook though, then verbose messages will not be stored even if the runbook is configured to log verbose records.

Cuando probar un runbook, no se muestran los mensajes detallados incluso si el runbook esté configurado para registrar registros detallados.When testing a runbook, verbose messages are not displayed even if the runbook is configured to log verbose records. Para mostrar mensajes detallados al probar un runbook, debe establecer la variable $VerbosePreference en Continue.To display verbose messages while testing a runbook, you must set the $VerbosePreference variable to Continue. Cuando esa variable está establecida, los mensajes detallados se muestran en el panel de salida de la prueba del Portal de administración.With that variable set, verbose messages will be displayed in the Test Output Pane of the Management Portal.

Cree un mensaje detallado con el cmdlet Write-Verbose .Create a verbose message using the Write-Verbose cmdlet.

#The following line creates a verbose message.

Write-Verbose "Message "This is a verbose message."

Flujo de depuraciónDebug Stream

El flujo de depuración está diseñado para usarse con un usuario interactivo y no debe usarse en runbooks.The Debug stream is intended for use with an interactive user and should not be used in runbooks.

Registros de progresoProgress Records

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.If you configure a runbook to log progress records (on the Configure tab of the runbook in the Management Portal), then a record will be written to the job history before and after each activity is run. 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.In most cases, you should keep the default setting of not logging progress records for a runbook in order to maximize performance. Active esta opción solo para solucionar problemas o depurar un runbook.Turn on this option only to troubleshoot or debug a runbook. Cuando se prueba un runbook, los mensajes de progreso no se muestran aunque el runbook esté configurado para escribir registros de progreso.When testing a runbook, progress messages are not displayed even if the runbook is configured to log progress records.

El cmdlet Write-Progress no es válido en un runbook porque está pensado para usarse con un usuario interactivo.The Write-Progress cmdlet is not valid in a runbook, since this is intended for use with an interactive user.

Variables de preferenciaPreference Variables

Windows PowerShell usa variables de preferencia para determinar cómo responder a los datos enviados a diferentes flujos de salida.Windows PowerShell uses preference variables to determine how to respond to data sent to different output streams. Puede establecer estas variables en un runbook para controlar cómo responderá a los datos enviados a diferentes flujos.You can set these variables in a runbook to control how it will respond to data sent into different streams.

En la tabla siguiente se enumeran las variables de preferencia que pueden usarse en runbooks con sus valores válidos y predeterminados.The following table lists the preference variables that can be used in runbooks with their valid and default values. Tenga en cuenta que esta tabla solo incluye los valores que son válidos en un runbook.Note that this table only includes the values that are valid in a runbook. Valores adicionales son válidos para las variables de preferencia cuando se usa en Windows PowerShell fuera de Service Management Automation.Additional values are valid for the preference variables when used in Windows PowerShell outside of Service Management Automation.

VariableVariable Valor predeterminadoDefault Value Valores válidosValid Values
WarningPreferenceWarningPreference ContinueContinue StopStop
ContinueContinue
SilentlyContinueSilentlyContinue
ErrorActionPreferenceErrorActionPreference ContinueContinue StopStop
ContinueContinue
SilentlyContinueSilentlyContinue
VerbosePreferenceVerbosePreference SilentlyContinueSilentlyContinue StopStop
ContinueContinue
SilentlyContinueSilentlyContinue

En la tabla siguiente se muestra el comportamiento de los valores de las variables de preferencia que son válidos en runbooks.The following table lists the behavior for the preference variable values that are valid in runbooks.

ValorValue ComportamientoBehavior
ContinueContinue Registra el mensaje y continúa ejecutando el runbook.Logs the message and continues executing the runbook.
SilentlyContinueSilentlyContinue Continúa la ejecución del runbook sin registrar el mensaje.Continues executing the runbook without logging the message. El efecto es que el mensaje se pasa por alto.This has the effect of ignoring the message.
StopStop Registra el mensaje y suspende el runbook.Logs the message and suspends the runbook.

Recuperar salidas de runbooks y mensajesRetrieving Runbook Output and Messages

Portal de administraciónManagement Portal

Puede ver los detalles de un trabajo de runbook en el Portal de administración de la pestaña Trabajos de un runbook.You can view the details of a runbook job in the Management Portal from the Jobs tab of a runbook. El resumen del trabajo mostrará los parámetros de entrada y la flujo de salida además de información general sobre el trabajo y las excepciones que se hayan producido.The Summary of the job will display the input parameters and the Output Stream in addition to general information about the job and any exceptions if they occurred. El historial incluirá mensajes del flujo de salida y flujos de Error y advertencia además el flujo detallado y registros de progreso si el runbook está configurado para el registro detallado y registros de progreso.The History will include messages from the Output Stream and Warning and Error Streams in addition to the Verbose Stream and Progress Records if the runbook is configured to log verbose and progress records.

Windows PowerShellWindows PowerShell

En Windows PowerShell, puede recuperar la salida y los mensajes de un runbook con el cmdlet Get SmaJobOutput .In Windows PowerShell, you can retrieve output and messages from a runbook using the Get-SmaJobOutput cmdlet. Este cmdlet requiere el identificador del trabajo y tiene un parámetro llamado Flujo donde debe especificar qué flujo se va a devolver.This cmdlet requires the ID of the job and has a parameter called Stream where you specify which stream to return. Puede especificar Cualquiera para devolver todos los flujos de trabajo.You can specify Any to return all streams for the job.

En el ejemplo siguiente se inicia un runbook y se espera a que finalice.The following example starts a sample runbook and then waits for it to complete. Una vez completado, se recopila su flujo de salida del trabajo.Once completed, its output stream is collected from the job.

$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

Véase tambiénSee Also

Automation RunbooksAutomation Runbooks

Creación de runbooks de AutomationAuthoring Automation Runbooks