Runbook 输出和消息

  • 项目

重要

此版本的 Service Management Automation (SMA) 已终止支持。 建议 升级到 SMA 2022。

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

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

Stream 说明 已发布 测试
输出 对象旨在由其他 Runbook 使用。 写入作业历史记录。 显示在测试输出窗格中。
警告 面向用户的警告消息。 写入作业历史记录。 显示在测试输出窗格中。
错误 面向用户的错误消息。 与发生异常时不同，默认情况下，在出现错误消息后，Runbook 会继续执行。 写入作业历史记录。 显示在测试输出窗格中。
详细 提供常规或故障排除信息的消息。 仅当为 Runbook 启用了详细日志记录时，才写入作业历史记录。 仅当 $VerbosePreference 已在 Runbook 中设置为“继续”的情况下，才在“测试输出”窗格中显示。
进度 完成 Runbook 中每个活动之前和之后自动生成的记录。 Runbook 不应尝试创建自己的进度记录，因为它们适用于交互式用户。 仅当为 Runbook 启用了进度日志记录时，才写入作业历史记录。 不显示在测试输出窗格中。
调试 面向交互式用户的消息。 不应在 Runbook 中使用。 不会写入作业历史记录。 不会写入测试输出窗格。

输出流

输出流旨在用于工作流在正常运行时创建的对象的输出。 在 Automation 中，此流主要用于可供调用当前 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
}

消息流

与输出流不同，消息流旨在向用户传递信息。 有多个消息流可用于不同种类的信息，每个消息流由 Automation 以不同方式处理。

选择所需的选项卡以了解有关这些消息流的详细信息：

警告和错误流旨在记录 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 中有效的值。 preference 变量的其他值在 Service Management Automation 外部的 Windows PowerShell 中使用时有效。

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

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

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

检索 Runbook 输出和消息

管理门户

可以从管理门户中的 runbook 的“作业” 选项卡查看 runbook 作业的详细信息。 除了有关作业以及任何异常（如发生）的常规信息，作业的“摘要” 还显示输入参数和 Output Stream 。 如果将 Runbook 配置为记录详细记录和进度记录，则除了 Verbose Stream 和 Progress Records ，”历史记录” 还将包括来自输出流和 Warning and Error Streams 的消息。

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。