Выходные данные и сообщения модуля Runbook

 

Опубликовано: Июнь 2016

Применимо к:Windows Azure Pack for Windows Server, System Center 2012 R2 Orchestrator

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

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

Поток	Описание	Опубликован	Проверка
Вывод	Объекты, предназначенные для использования другими модулями Runbook.	Записывается в журнал заданий.	Отображается в тестовой области вывода.
Предупреждение	Сообщение с предупреждением, предназначенное для пользователя.	Записывается в журнал заданий.	Отображается в тестовой области вывода.
Ошибка	Сообщение об ошибке, предназначенное для пользователя. По умолчанию модуль Runbook продолжает работу после появления сообщения об ошибке в отличие от возникновения исключения.	Записывается в журнал заданий.	Отображается в тестовой области вывода.
Подробные сведения	Сообщения, предоставляющие общие сведения или сведения по устранению неполадок.	Записывается в журнал заданий, только если включено подробное ведение журнала для модуля Runbook.	Отображается в тестовой области вывода, только если в модуле Runbook для $VerbosePreference задано значение Continue.
Ход выполнения	Записи, автоматически созданные до и после каждого действия в модуле 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-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 выводит объект string и включает объявление выходного типа. Если модуль 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 для сохранения подробных сообщений. Однако если в опубликованном модуле 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	Stop Continue SilentlyContinue
ErrorActionPreference	Continue	Stop Continue SilentlyContinue
VerbosePreference	SilentlyContinue	Stop Continue SilentlyContinue

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

Значение	Поведение
Continue	Записывает в журнал сообщение и продолжает выполнять модуль Runbook.
SilentlyContinue	Продолжает выполнять модуль Runbook, не записывая сообщение. Это приводит к пропуску сообщения.
Stop	Записывает сообщение и приостанавливает модуль Runbook.

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

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

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

Windows PowerShell

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

В следующем примере запускается пример модуля 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

См. также

Расширение Service Management Automation с помощью модулей Runbook
Runbook Authoring