深度解析 SMA 功能：通过控制 Runbook 流进行测试和故障诊断
当您使用 Service Management Automation（SMA）创建并运行 Runbooks 时，有两个关键任务：授权期间测试 Runbooks，以及在生产环境中运行 Runbook 作业时的故障诊断。在这两种情况下，都需要 Runbooks 来生成适当的信息，以便了解执行期间的情况。幸运的是，PowerShell 工作流作为给 SMA Runbooks 提供动力的引擎，拥有您可以控制的多个信息流，使您在测试及故障诊断时达到最佳效果。在这篇文章中，我将介绍几个关于控制 Runbook 流的概念和最佳实践，从而帮助您调试和排除 Runbooks 故障。
SMA 中的测试
您可以在 SMA Runbook 授权页面中创建 Runbook。该页面中有编辑 PowerShell 工作流代码窗格、查看测试输出窗格和插入活动、Runbooks、全局设置等控件（下图是调试 Runbook 输出的截图）。授权 SMA Runbook 时，您或许想在关键点处进行测试，以便保证其功能按预期运行。启动 Runbook 测试十分简单：只需单击 Test按钮。测试工作启动后会出现输出窗格，来自 Runbook 的大多数流会被写入该窗格中。当然，输入流中的信息和您使用的特定流决定着您能在多大程度上对 Runbook 进行调试。为了帮助解决这一问题，在下一节中我将展示如何控制 PowerShell 工作流所提供的各种流。
控制Runbook 输出
PowerShell 工作流支持 6 种不同的流，每个流都具有不同目的：包括 Output （输出流）、Progress （进度流）、Warning （警告流）、Error （错误流）、Verbose （冗长流）和 Debug （调试流）。输出流是输出 Runbook 的写入对象，而其他流则是有特定目的的信息流。Runbooks 可以通过 Write-Output、Write-Progress、Write-Warning、Write-Error、Write-Verbose 和 Write-Debug 等命令写入这些流中。通过学习何时使用每种流，您可以在创建 Runbook 的授权/调试阶段和排除生产 Runbook 作业故障时，最大限度地提高它们的效用。
在 SMA 中有两个地方可供您查看 Runbook 流—— Runbook 授权页面和 Runbook 作业页面。在 Runbook 授权页面中，在创建和测试 Runbook 期间，您可以在调试 Runbook 时查看流。在 Runbook 作业页面，您可以在发布 Runbook 并且运行在生产环境中之后，为了排除 Runbook 作业故障而查看流。
用于调试的Runbook 输出
在您测试和授权 Runbook 期间，只有输出流、警告流和错误流默认写入输出窗格。从下图中您就可以看到。
为什么只有这三种流才能写入呢？这与流的默认首选项设置有关。（更多信息参见 PowerShell 的首选项变量一文）。在下图中您可以看到，警告流、错误流和进度流的默认首选项都为“Continue”，而冗长流和调试流的首选项则为“SilentlyContinue”。这意味着，当使用 Write-Verbose 或 Write-Debug 命令时，信息将不会写入输出窗格（除非调用的命令包含 –Verbose 或 –Debug 开关）。
改变测试的默认设置
测试期间，您可以重写冗长流和调试流的首选项设置。
- 查看所有输出窗格内的冗长信息时，您可以在 Runbook 顶部设置 $VerbosePreference=”Continue”。
- 如果您只想查看冗长信息，可以在具体的 Write-Verbose 调用中（或任一冗长信息命令中）添加“-Verbose”开关。
- 查看输出窗格内的调试信息时，您可以在 Runbook 顶部设置 $DebugPreference=”Continue”。
- 如果您只想查看选择调试信息，可以在具体的 Write-Debug 调用中（或任一调试信息命令中）添加“-Debug”开关。
- 重要： 如果您在 Runbook 中设置 $DebugPreference=”Continue”，之后还必须设置 $WarningPreference=”Continue” 和 $ErrorActionPreference=”Continue”，以避免在调用 Write-Warning 或 Write-Error 时（这是一个正在调查的问题）发生终止异常（未处理的错误）
以下代码演示了在 Runbook 中设置首选项的过程。
最佳实践： 在 SMA Runbook 调试的授权期间使用 Write-Verbose。不要使用 Write-Debug 或 Write-Output 作为调试信息：因为目前使用 Write-Debug 还比较复杂，而 Write-Output 只可用于向其他活动、命令或 Runbook 中输入的输出对象。
最佳实践： 在测试和故障排除时，想让注释或进度信息出现在作业输出中的话，可以使用 Write-Verbose。再次强调，不要使用 Write-Output。
最佳实践： 在 Runbooks 中不要使用 Write-Progress。进度记录永远不会出现在测试输出窗格（因为这意味着它们要显示在进度条中），因此这对于调试毫无益处。在下一节的生产作业中，您会发现这可能在故障排除的进度记录中有些作用，但也只针对那些由 PowerShell 工作流引擎自动生成的进度记录。
用于生产作业日志的Runbook 输出
当您的 Runbook 完成授权并发布到生产环境中后，，还应记住两个与输出流日志有关的注意事项。（1）为每个作业存储在数据库中的大量数据；（2）排除 Runbook 作业故障时需要的大量信息。
生产作业（与测试作业一样）的默认设置是只有输出流、警告流和错误流记录才能写入每个作业的数据库中。只存储这些记录的原因在于它们是程序库所需的最重要信息。请注意，如果在 Runbook 中，您将以上讨论的流的首选项变量设置为“SilentlyContinue”并发布，那么在生产执行时，Runbook 将不再输出这些流的任何信息，即使 Runbook 的配置已经启用了这些流的日志记录。
以下两图是一个作业的仪表板页面和历史记录页面，说明了输出流、警告流和错误流记录是如何默认显示的。不默认存储进度流、冗长流和调试流记录是为了节省数据库存储空间。（更多信息可参见监控和排除你的 Runbooks 故障。）
改变生产故障排除的默认设置
您可以在配置页面为每个 Runbook 更改调试流、冗长流和进度流日志记录的默认设置。下图显示的是这些设置已更改为 True。
请注意，这些配置设置只适用于已发布的 Runbook 的生产运行期间，当 Runbook 处于草稿模式时，在 Runbook 授权/测试页面则无法更改。您还可以使用 Set-SmaRunbookConfiguration 命令更改这些设置。
重要： 如果您通过 Runbook 配置启用了调试日志记录，那么在 Runbook 中必须包含 $WarningPreference=”Continue” 和 $ErrorActionPreference=”Continue”，以避免写入错误或警告（正在研究的问题）后发生终止异常（未处理的错误）。
最佳实践： 在排除生产 SMA Runbooks 故障时，想让注释、进度或调试信息出现在作业历史记录中的话，可以使用 Write-Verbose。不要使用 Write-Debug 或 Write-Output。
在下图中您可以看到启用调试流、冗长流和进度流日志记录的结果。
您可以在作业历史记录中看到更多可用信息。这些额外信息对于排除 Runbook 的生产故障来说是必不可少的。然而，这些额外信息也是存储在数据库中，并且如果您有大量作业的话，它们还会迅速填充数据库。
最佳实践： 让调试流、冗长流和进度流的默认设置保持关闭（OFF），在您需要故障排除时再将其打开。
进度记录的数量很多。默认情况下，工作流引擎为工作流中的每个活动和命令写入两个进度记录——一个在活动开始时，一个在活动结束时。除非您需要用这些信息来跟踪排除 Runbook 故障的进度，否则您应确保进度日志记录是关闭的。
最佳实践： 在 Runbooks 中不要使用 Write-Progress。如果您需要在排除故障期间跟踪进度，由 PowerShell 工作流引擎自动生成的进度记录会提供大量信息。
总结
正如您所看到的，控制来自 Runbooks 的信息流，使其在最小化填充数据库的同时优化调试和故障排除是十分容易的。在草稿 Runbook 中尝试一下，看看可以如何控制这些流。