Выходные данные и сообщения в runbook

Большинство модулей Runbook службы автоматизации имеют некоторую форму выходных данных, например сообщение об ошибке пользователю или сложному объекту, который будет использоваться другим рабочим процессом. Windows PowerShell предоставляет несколько потоков для отправки выходных данных из рабочего процесса. Автоматизация управления службами работает с каждым из этих потоков по-разному, и следует следовать рекомендациям по использованию каждого из них при создании модуля Runbook.

Следующая таблица содержит краткое описание каждого из потоков и их поведение на портале управления при выполнении опубликованного модуля Runbook и последующем тестировании модуля Runbook. Дополнительные сведения о каждом потоке приведены в последующих разделах.

Stream	Description	Опубликованные	Тест
Выходные данные	Объекты, предназначенные для использования другими Runbook.	Записывается в журнал заданий.	Отображается в области вывода теста.
Предупреждение	Предупреждающее сообщение, предназначенное для пользователя.	Записывается в журнал заданий.	Отображается в области вывода теста.
Ошибка	Сообщение об ошибке, предназначенное для пользователя. В отличие от исключения, по умолчанию Runbook продолжит работу после сообщения об ошибке.	Записывается в журнал заданий.	Отображается в области вывода теста.
Подробный	Сообщения, предоставляющие общие сведения или сведения по устранению неполадок.	Записывается в журнал заданий только в том случае, если для Runbook включено подробное ведение журнала.	Отображается в тестовой области вывода, только если в модуле Runbook для $VerbosePreference задано значение Continue .
Ход выполнения	До и после каждого действия в Runbook автоматически создаются записи. Модуль Runbook не должен пытаться создать собственные записи хода выполнения, так как они предназначены для интерактивного пользователя.	Записывается в журнал заданий только в том случае, если для Runbook включено ведение журнала хода выполнения.	Не отображается в области вывода теста.
Отладка	Сообщения, предназначенные для интерактивного пользователя. Не следует использовать в модулях runbook.	Не записывается в журнал заданий.	Не записывается в область вывода теста.

Поток вывода

Поток вывода предназначен для вывода объектов, созданного рабочим процессом при правильной работе. В службе автоматизации этот поток в основном используется для объектов, предназначенных для использования родительскими модулями Runbook, вызывающими текущий модуль Runbook. Если вы используете встроенный вызов Runbook из родительского Runbook, он возвращает данные из потока вывода в родительский Runbook. Для передачи информации пользователю следует использовать только поток вывода, если известно, что Runbook никогда не будет вызван другим Runbook. Однако в обычном случае для передачи информации пользователю рекомендуется использовать подробный поток .

Можно записать данные в поток вывода с помощью Write-Output или поместив объект в отдельную строку в Runbook.

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

Выходные данные функции

При записи в поток вывода в функции, которая находится в Runbook, выходные данные передаются обратно в Runbook. Если модуль Runbook назначает выходные данные переменной, он не записывается в выходной поток. Запись в любые другие потоки из функции приведет к записи в соответствующий поток для Runbook.

Рассмотрим следующий пример 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"
   }
}

Поток вывода для задания Runbook будет следующим:

Output outside of function

Подробный поток для задания Runbook будет следующим:

Verbose outside of function
Verbose inside of function

Переменная $functionOutput будет иметь значение

Output inside of function

Объявление типа выходных данных

Рабочий процесс может указать тип выходных данных с помощью атрибута OutputType. Этот атрибут не оказывает влияния во время выполнения, но содержит указание об ожидаемых выходных данных Runbook для автора Runbook во время разработки. Так как набор инструментов для Runbook продолжает увеличиваться, растет и важность объявления типов выходных данных во время разработки. Поэтому рекомендуется включать это объявление во все создаваемые вами модули runbook.

Следующий пример Runbook выводит строковый объект и включает в себя объявление типа выходных данных. Если Runbook выводит массив определенного типа, все равно следует указать его тип, а не массив типа.

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

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

Потоки сообщений

В отличие от потока вывода потоки сообщений предназначены для передачи информации пользователю. Существует несколько потоков сообщений для разных типов сведений, и каждая из них обрабатывается по-разному службой автоматизации.

Выберите необходимую вкладку, чтобы узнать больше об этих потоках сообщений:

Потоки предупреждений и ошибок

Потоки предупреждений и ошибок предназначены для ведения журнала проблем, возникающих в Runbook. Они записываются в журнал заданий при выполнении модуля Runbook и включаются в область выходных данных теста на портале управления при тестировании модуля Runbook. По умолчанию Runbook продолжит выполнение после предупреждения или ошибки. Можно указать, что Runbook должен быть приостановлен при предупреждении или ошибке, задав привилегированную переменную в Runbook перед созданием сообщения. Например, чтобы приостановить Runbook при ошибке, как при исключении, присвойте $ErrorActionPreference значение Stop.

Создайте предупреждение или сообщение об ошибке с помощью командлета Write-Warning или Write-Error. Действия также могут записывать данные в эти потоки.

#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."

Подробный поток

Поток подробных сообщений предназначен для общей информации о работе Runbook. Так как поток отладки недоступен в модулю Runbook, подробные сообщения должны использоваться для устранения неполадок. По умолчанию подробные сообщения из опубликованных модулей Runbook не будут храниться в журнале заданий. Чтобы сохранить подробные сообщения, настройте опубликованные модули Runbook в разделе Подробные записи в журнале во вкладке Настройка модуля Runbook на портале управления. В большинстве случаев для Runbook следует оставить значение по умолчанию, при котором подробные записи не добавляются в журнал. Это обусловлено вопросами производительности. Включайте этот параметр только для устранения неполадок и отладки Runbook.

Значение по умолчанию переменной $VerbosePreference — SilentlyContinue. Эта переменная не требуется изменять в опубликованном модулю Runbook для подробного хранения сообщений. Если это значение явно задано как SilentlyContinue в опубликованном модулю Runbook, то подробные сообщения не будут храниться даже в том случае, если модуль Runbook настроен для записи подробных записей журнала.

При тестировании модуля runbook подробные сообщения не отображаются, даже если для runbook настроено добавление подробных записей в журнал. Для отображения подробных сообщений при тестировании Runbookнеобходимо переменной $VerbosePreference присвоить значение Continue. Если эта переменная задана, подробные сообщения будут отображаться в тестовой области вывода портала управления.

Для создания подробного сообщения используется командлет Write-Verbose .

#The following line creates a verbose message.

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

Поток отладки

Поток отладки предназначен для использования с интерактивным пользователем и не должен использоваться в модулях Runbook.

Записи о ходе выполнения

Если модуль Runbook настроен для ведения записей журнала (на вкладке Настройка модуля Runbook на портале управления), то сообщение будет записано в журнал заданий до и после выполнения каждого действия. В большинстве случаев для Runbook следует оставить значение по умолчанию, при котором записи о ходе выполнения не добавляются в журнал. Это позволит получить максимальную производительность. Включайте этот параметр только для устранения неполадок и отладки Runbook. При тестировании модуля Runbook сообщения о ходе выполнения не отображаются, даже если модуль Runbook настроен для записи хода выполнения.

Командлет Write-Progress недействителен в runbook, так как он предназначен для использования с интерактивным пользователем.

Привилегированные переменные

Windows PowerShell использует привилегированные переменные, чтобы определить, как реагировать на данные, отправляемые в различные потоки вывода. Вы можете задать эти переменные в Runbook, чтобы управлять его реакцией на данные, отправляемые в разные потоки.

В следующей таблице перечислены привилегированные переменные, которые могут использоваться в модулях Runbook, а также их допустимые значения и значения по умолчанию.

Примечание.

Эта таблица содержит только значения, которые являются допустимыми в runbook. Дополнительные значения допустимы для переменных предпочтения при использовании в Windows PowerShell за пределами службы автоматизации управления службами.

«Переменная»	Значение по умолчанию	Допустимые значения
WarningPreference	Продолжить	Остановить Continue<\br> \SilentlyContinue
ErrorActionPreference	Продолжить	Остановить Продолжить SilentlyContinue
VerbosePreference	SilentlyContinue	Остановить Продолжить SilentlyContinue

В следующей таблице представлено поведение для соответствующих значений привилегированных переменных, допустимых в Runbook.

Значение	Поведение
Продолжить	Записывает сообщение в журнал и продолжает выполнение Runbook.
SilentlyContinue	Продолжает выполнение Runbook без добавления сообщения в журнал. То есть сообщение игнорируется.
Остановить	Записывает сообщение в журнал и приостанавливает выполнение Runbook.

Извлечение выходных данных и сообщений Runbook

Портал управления

Сведения о задании модуля Runbook см. на портале управления, на вкладке Задания модуля Runbook. В разделе Сводка задания в дополнение к общей информации о задании и исключениях (если они есть) будут отображаться входные параметры и Output Stream . Кроме подробного потока и записей о ходе выполнения журнал будет содержать сообщения из потока вывода и потоков предупреждений и ошибок, если для Runbook настроено добавление в журнал подробных сообщений и записей о ходе выполнения.

Windows PowerShell

В Windows PowerShell можно вернуть выходные данные и сообщения из модуля Runbook с помощью командлета Get-SmaJobOutput . Для командлета требуется идентификатор задания, и он включает параметр Stream , в котором указывается, какой поток следует вернуть. Можно указать значение Any для возврата всех потоков для задания.

В следующем примере запускается пример Runbook и ожидается его завершение. После завершения его поток вывода собирается из задания.

$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

Следующие шаги

Создание модулей Runbook службы автоматизации.