通过

Runbook 输出和消息

  • 项目

大多数自动化 Runbook 将具有某种形式的输出，例如向用户发送错误消息或要由另一个工作流使用的复杂对象。 Windows PowerShell 提供 多个流 ，从工作流发送输出。 Service Management Automation 与其中每个流的工作方式不同，在创建 Runbook 时，应遵循有关如何使用每个流的最佳做法。

下表提供每个流的简短说明，以及当运行已发布 runbook 时和 测试 runbook时它们在管理门户中的行为。 后续部分中提供了有关每个流的更多详细信息。

Stream 说明 已发布 测试
输出 对象旨在由其他 Runbook 使用。 写入作业历史记录。 显示在测试输出窗格中。
警告 面向用户的警告消息。 写入作业历史记录。 显示在测试输出窗格中。
错误 面向用户的错误消息。 与发生异常时不同，默认情况下，在出现错误消息后，Runbook 会继续执行。 写入作业历史记录。 显示在测试输出窗格中。
详细 提供常规或故障排除信息的消息。 仅当为 Runbook 启用了详细日志记录时，才写入作业历史记录。 仅当 $VerbosePreference 在 runbook 中设置为 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 将输出一个字符串对象，并包含其输出类型的声明。 如果 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 cmdlet 创建警告或错误消息。 活动可能也会向这些流写入数据。

#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 配置为记录进度记录，也不会显示进度消息。

Write-Progress cmdlet 在 Runbook 中无效，因为它适用于交互式用户。

Preference 变量

Windows PowerShell 使用首选项变量来确定如何响应发送到不同输出流的数据。 可以在 Runbook 中设置这些变量，以控制 Runbook 如何响应发送到不同流中的数据。

下表列出了可在 Runbook 中使用的 preference 变量及其有效值和默认值。

注意

此表仅包含在 Runbook 中有效的值。 在 Service Management Automation 外部的 Windows PowerShell 中使用时，其他值对首选项变量有效。

变量 默认值 有效值
WarningPreference 继续 停止
继续
SilentlyContinue
ErrorActionPreference 继续 停止
继续
SilentlyContinue
VerbosePreference SilentlyContinue 停止
继续
SilentlyContinue

下表列出了在 Runbook 中有效的 preference 变量值的行为。

值 行为
继续 记录消息并继续执行 Runbook。
SilentlyContinue 继续执行 Runbook 但不记录消息。 这会导致忽略消息。
停止 记录消息并挂起 Runbook。

检索 Runbook 输出和消息

管理门户

可以从管理门户中的 runbook 的“作业” 选项卡查看 runbook 作业的详细信息。 除了有关作业以及任何异常（如发生）的常规信息，作业的“摘要” 还显示输入参数和 Output Stream 。 “历史记录”包含来自输出流以及警告和错误流的消息，此外，如果 Runbook 已配置为记录详细记录和进度记录，则该选项卡还包含详细流和进度记录。

Windows PowerShell

在 Windows PowerShell 中，可以使用 Get-SmaJobOutput cmdlet 从 runbook 检索输出和消息。 此 cmdlet 需要作业 ID，并具有一个名为“Stream” 的参数（在其中指定要返回的流）。 可以指定 Any 来返回作业的所有流。

以下示例将启动一个示例 Runbook，然后等待该 Runbook 完成。 完成后，将从作业收集该 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。