处理图形 Runbook 中的错误Handle errors in graphical runbooks

对于 Azure 自动化图形 Runbook,需要考虑的一个关键设计原则是识别 Runbook 在执行期间可能会遇到的问题。A key design principle to consider for your Azure Automation graphical runbook is the identification of issues that the runbook might experience during execution. 这些情况可能包括:成功、预计的错误状态,以及意外的错误条件。These issues can include success, expected error states, and unexpected error conditions.

通常情况下,如果 Runbook 活动出现的是非终止错误,则 Windows PowerShell 会无视该错误,并继续处理该活动以及后续的任何活动。Often, if there is a non-terminating error that occurs with a runbook activity, Windows PowerShell handles the activity by processing any activity that follows, regardless of the error. 该错误可能会生成异常,但下一活动仍允许运行。The error is likely to generate an exception, but the next activity is still allowed to run.

图形 Runbook 应包含错误处理代码来处理执行问题。Your graphical runbook should include error handling code to deal with execution issues. 若要验证某个活动的输出或对错误进行处理,可以使用 PowerShell 代码活动,对活动的输出链接定义条件逻辑,或者应用其他方法。To validate the output of an activity or handle an error, you can use a PowerShell code activity, define conditional logic on the output link of the activity, or apply another method.

Azure 自动化图形 Runbook 在改进后可以进行错误处理。Azure Automation graphical runbooks have been improved with the capability to include error handling. 用户现在可以将例外变成非终止性错误,并在活动之间创建错误链接。You can now turn exceptions into non-terminating errors and create error links between activities. 这一经过改进的过程使 Runbook 可以捕获错误,并管理意料内或意料外的情况。The improved process allows your runbook to catch errors and manage realized or unexpected conditions.

PowerShell 错误类型PowerShell error types

Runbook 执行期间可能会发生的 PowerShell 错误的类型为终止性错误和非终止性错误。The types of PowerShell errors that can occur during runbook execution are terminating errors and non-terminating errors.

终止性错误Terminating error

终止性错误是执行期间发生的严重错误,该错误会导致命令或脚本的执行完全停止。A terminating error is a serious error during execution that halts a command or script execution completely. 示例包括:cmdlet 不存在、阻止某个 cmdlet 运行的语法错误,以及其他灾难性错误。Examples include nonexistent cmdlets, syntax errors that prevent a cmdlet from running, and other fatal errors.

非终止性错误Non-terminating error

非终止性错误是不严重的错误,尽管出现错误状况,但允许继续执行。A non-terminating error is a non-serious error that allows execution to continue despite the error condition. 示例包括:“找不到文件”之类的操作错误、权限问题。Examples include operational errors, such as file not found errors and permissions issues.

何时使用错误处理When to use error handling

当关键活动引发错误或异常时,可使用 Runbook 中的错误处理。Use error handling in your runbook when a critical activity throws an error or exception. 必须禁止处理 Runbook 中的下一个活动,并适当地处理错误。It's important to prevent the next activity in the runbook from processing and to handle the error appropriately. 当 Runbook 在为业务过程或服务运营过程提供支持时,处理错误尤其重要。Handling the error is especially critical when your runbooks are supporting a business or service operations process.

对于可能会生成错误的每个活动,可以添加指向其他任何活动的错误链接。For each activity that can produce an error, you can add an error link pointing to any other activity. 目标活动可属于任何类型,包括代码活动、调用 cmdlet、调用另一个 Runbook,等等。The destination activity can be of any type, including code activity, invocation of a cmdlet, invocation of another runbook, and so on. 目标活动还可以包含传出链接(常规链接或错误链接)。The destination activity can also have outgoing links, either regular or error links. 这些链接可让 Runbook 在不求助于代码活动的情况下,实现复杂的错误处理逻辑。The links allow the runbook to implement complex error handling logic without resorting to a code activity.

建议的做法是创建具有常用功能的专用错误处理 Runbook,但这种做法不是必需的。The recommended practice is to create a dedicated error handling runbook with common functionality, but this practice isn't mandatory. 例如,有一个 Runbook 尝试启动虚拟机并在其上安装应用程序。For example, consider a runbook that tries to start a virtual machine and install an application on it. 如果 VM 无法正常启动,将会:If the VM doesn't start correctly, it:

  1. 发送有关此问题的通知。Sends a notification about this problem.
  2. 改为启动另一个 Runbook 来自动预配新的 VM。Starts another runbook that automatically provisions a new VM instead.

一种解决方案是让 Runbook 中的一个错误链接指向处理步骤 1 的活动。One solution is to have an error link in the runbook pointing to an activity that handles step one. 例如,Runbook 可以将 Write-Warning cmdlet 连接到步骤 2 的活动(如 Start-AzAutomationRunbook cmdlet)。For example, the runbook can connect the Write-Warning cmdlet to an activity for step two, such as the Start-AzAutomationRunbook cmdlet.

还可以通过将这两个活动放在单独的错误处理 Runbook 中,来通用化此行为,以便在许多 Runbook 中使用。You can also generalize this behavior for use in many runbooks by putting these two activities in a separate error handling runbook. 在原始 Runbook 调用此错误处理 Runbook 之前,原始 Runbook 可以基于其数据构造自定义消息,然后将其作为参数传递给错误处理 Runbook。Before your original runbook calls this error handling runbook, it can construct a custom message from its data and then pass it as a parameter to the error handling runbook.

将异常转换为非终止性错误Turn exceptions into non-terminating errors

Runbook 中的每个活动都有一项可将异常转化为非终止性错误的配置设置。Each activity in your runbook has a configuration setting that turns exceptions into non-terminating errors. 此设置默认已禁用。By default, this setting is disabled. 对于 Runbook 要为其处理错误的任何活动,我们均建议启用此设置。We recommend enabling this setting on any activity where your runbook handles errors. 此设置可确保 Runbook 使用错误链接将活动中的终止性错误和非终止性错误作为非终止性错误进行处理。This setting ensures that the runbook handles both terminating and non-terminating errors in the activity as non-terminating errors, using an error link.

启用该配置设置后,请让 Runbook 创建一个处理错误的活动。After enabling the configuration setting, have your runbook create an activity that handles the error. 如果该活动生成了任何错误,将会打开传出错误链接。If the activity produces any error, the outgoing error links are followed. 不会打开常规链接,即使活动也生成了常规输出。The regular links are not followed, even if the activity produces regular output as well.

自动化 Runbook 错误链接示例

在以下示例中,一个 Runbook 检索了一个包含 VM 的计算机名称的变量。In the following example, a runbook retrieves a variable that contains the computer name of a VM. 然后,它尝试使用下一个活动启动该 VM。It then attempts to start the VM with the next activity.

自动化 Runbook 错误处理示例

Get-AutomationVariable 活动和 Start-AzVM cmdlet 已配置为将异常转换为错误。The Get-AutomationVariable activity and the Start-AzVM cmdlet are configured to convert exceptions to errors. 如果获取变量或启动 VM 时出现问题,代码会生成错误。If there are problems getting the variable or starting the VM, the code generates errors.

自动化 Runbook 错误处理活动设置Automation runbook error-handling activity settings.

错误链接从这些活动流向单个 error management 代码活动。Error links flow from these activities to a single error management code activity. 此活动是通过使用 throw 关键字的简单 PowerShell 表达式(用于停止处理)以及 $Error.Exception.Message(用于获取描述当前异常的消息)配置的。This activity is configured with a simple PowerShell expression that uses the throw keyword to stop processing, along with $Error.Exception.Message to get the message that describes the current exception.

自动化 Runbook 错误处理代码示例Automation runbook error handling code example

后续步骤Next steps