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

Важно!

Поддержка этой версии service Management Automation (SMA) завершена. Рекомендуется выполнить обновление до SMA 2022.

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

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

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

Поток вывода

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

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

#The following lines both write an object to the output stream.
Write-Object -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 после ошибки, как и для исключения, задайте для $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. Так как Stream отладки недоступен в модулю Runbook, для устранения неполадок следует использовать подробные сообщения. По умолчанию подробные сообщения от опубликованных модулей Runbook не сохраняются в журнале заданий. Чтобы сохранить подробные сообщения, настройте опубликованные модули Runbook в разделе Подробные записи в журнале во вкладке Настройка модуля Runbook на портале управления. В большинстве случаев для Runbook следует оставить значение по умолчанию, при котором подробные записи не добавляются в журнал. Это обусловлено вопросами производительности. Включайте этот параметр только для устранения неполадок и отладки Runbook.

Значение по умолчанию переменной $VerbosePreference — SilentlyContinue. Для хранения подробных сообщений не нужно изменять эту переменную в опубликованном модулю Runbook. Если для этого значения явно задано значение SilentlyContinue в опубликованном модусе 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 за пределами Service Management Automation.

Переменная	Значение по умолчанию	Допустимые значения
WarningPreference	Continue	Остановить Continue SilentlyContinue
ErrorActionPreference	Continue	Остановить Continue SilentlyContinue
VerbosePreference	SilentlyContinue	Остановить Continue SilentlyContinue

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

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

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

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

Сведения о задании модуля Runbook см. на портале управления, на вкладке Задания модуля Runbook. В разделе Сводка задания в дополнение к общей информации о задании и исключениях (если они есть) будут отображаться входные параметры и Output Stream . В раздел Журнал войдут сообщения из потока вывода и Warning and Error Streams , а также Verbose Stream и Progress Records , если модуль 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 службы автоматизации.