使用 Azure 自动化图形 Runbook SDK(预览版)Use the Azure Automation graphical runbook SDK (preview)

图形 runbook 有助于管理基础 Windows PowerShell 或 PowerShell 工作流代码复杂性。Graphical runbooks help manage the complexities of the underlying Windows PowerShell or PowerShell Workflow code. Microsoft Azure 自动化图形创作 SDK 可让开发人员创建和编辑用于 Azure 自动化的图形 runbook。The Microsoft Azure Automation graphical authoring SDK enables developers to create and edit graphical runbooks for use with Azure Automation. 本文介绍了通过代码创建图形 runbook 的基本步骤。This article describes basic steps in creating a graphical runbook from your code.

先决条件Prerequisites

通过下载 SDK 导入 Orchestrator.GraphRunbook.Model.dll 包。Import the Orchestrator.GraphRunbook.Model.dll package by downloading the SDK.

创建 Runbook 对象实例Create a runbook object instance

引用 Orchestrator.GraphRunbook.Model 程序集,并创建 Orchestrator.GraphRunbook.Model.GraphRunbook 类的实例:Reference the Orchestrator.GraphRunbook.Model assembly and create an instance of the Orchestrator.GraphRunbook.Model.GraphRunbook class:

using Orchestrator.GraphRunbook.Model;
using Orchestrator.GraphRunbook.Model.ExecutableView;

var runbook = new GraphRunbook();

添加 Runbook 参数Add runbook parameters

实例化 Orchestrator.GraphRunbook.Model.Parameter 对象,并将其添加到 Runbook:Instantiate Orchestrator.GraphRunbook.Model.Parameter objects and add them to the runbook:

runbook.AddParameter(
 new Parameter("YourName") {
  TypeName = typeof(string).FullName,
   DefaultValue = "World",
   Optional = true
 });

runbook.AddParameter(
 new Parameter("AnotherParameter") {
  TypeName = typeof(int).FullName, ...
 });

实例化相应类型的活动,并将其添加到 Runbook:Instantiate activities of appropriate types and add them to the runbook:

var writeOutputActivityType = new CommandActivityType {
 CommandName = "Write-Output",
  ModuleName = "Microsoft.PowerShell.Utility",
 InputParameterSets = new [] {
  new ParameterSet {
   Name = "Default",
    new [] {
     new Parameter("InputObject"), ...
    }
  },
  ...
 }
};

var outputName = runbook.AddActivity(
 new CommandActivity("Output name", writeOutputActivityType) {
  ParameterSetName = "Default",
   Parameters = new ActivityParameters {
    {
     "InputObject",
     new RunbookParameterValueDescriptor("YourName")
    }
   },
   PositionX = 0,
   PositionY = 0
 });

var initializeRunbookVariable = runbook.AddActivity(
 new WorkflowScriptActivity("Initialize variable") {
  Process = "$a = 0",
   PositionX = 0,
   PositionY = 100
 });

活动由 Orchestrator.GraphRunbook.Model 命名空间中的以下类实现。Activities are implemented by the following classes in the Orchestrator.GraphRunbook.Model namespace.

Class 活动Activity
CommandActivityCommandActivity 调用 PowerShell 命令(cmdlet、函数等)。Invokes a PowerShell command (cmdlet, function, etc.).
InvokeRunbookActivityInvokeRunbookActivity 调用另一个内联 Runbook。Invokes another runbook inline.
JunctionActivityJunctionActivity 等待所有传入的分支完成。Waits for all incoming branches to finish.
WorkflowScriptActivityWorkflowScriptActivity 在 Runbook 的上下文中执行 PowerShell 或 PowerShell 工作流代码的块(具体取决于 Runbook 类型)。Executes a block of PowerShell or PowerShell Workflow code (depending on the runbook type) in the context of the runbook. 这是一个强大的工具,但不要滥用:UI 将以文本形式显示此脚本块;执行引擎会将提供的块视为黑盒,并且不会尝试分析其内容,但基本语法检查除外。This is a powerful tool, but do not overuse it: the UI will show this script block as text; the execution engine will treat the provided block as a black box, and will make no attempts to analyze its content, except for a basic syntax check. 如果只需调用单个 PowerShell 命令,请优先使用 CommandActivity。If you just need to invoke a single PowerShell command, prefer CommandActivity.

备注

请勿从提供的类派生自己的活动。Don't derive your own activities from the provided classes. Azure 自动化不能使用具有自定义活动类型的 runbook。Azure Automation can't use runbooks with custom activity types.

必须提供 CommandActivityInvokeRunbookActivity 参数作为值描述符,而不是直接值。You must provide CommandActivity and InvokeRunbookActivity parameters as value descriptors, not direct values. 值描述符指定如何生成实际的参数值。Value descriptors specify how to produce the actual parameter values. 目前提供以下值描述符:The following value descriptors are currently provided:

描述符Descriptor 定义Definition
ConstantValueDescriptorConstantValueDescriptor 引用硬编码的常量值。Refers to a hard-coded constant value.
RunbookParameterValueDescriptorRunbookParameterValueDescriptor 按名称引用 Runbook 参数。Refers to a runbook parameter by name.
ActivityOutputValueDescriptorActivityOutputValueDescriptor 引用上游活动输出,使一个活动能够“订阅”另一个活动生成的数据。Refers to an upstream activity output, allowing one activity to "subscribe" to data produced by another activity.
AutomationVariableValueDescriptorAutomationVariableValueDescriptor 按名称引用自动化变量资产。Refers to an Automation Variable asset by name.
AutomationCredentialValueDescriptorAutomationCredentialValueDescriptor 按名称引用自动化证书资产。Refers to an Automation Certificate asset by name.
AutomationConnectionValueDescriptorAutomationConnectionValueDescriptor 按名称引用自动化连接资产。Refers to an Automation Connection asset by name.
PowerShellExpressionValueDescriptorPowerShellExpressionValueDescriptor 指定自由格式的 PowerShell 表达式,调用活动之后,会紧接着计算该表达式。Specifies a free-form PowerShell expression that will be evaluated just before invoking the activity.
这是一个强大的工具,但不要滥用:UI 将以文本形式显示此表达式;执行引擎会将提供的块视为黑盒,并且不会尝试分析其内容,但基本语法检查除外。This is a powerful tool, but do not overuse it: the UI will show this expression as text; the execution engine will treat the provided block as a black box, and will make no attempts to analyze its content, except for a basic syntax check. 如果可能,请优先使用更具体的值描述符。When possible, prefer more specific value descriptors.

备注

请勿从提供的类派生自己的值描述符。Don't derive your own value descriptors from the provided classes. Azure 自动化不能使用具有自定义值描述符类型的 runbook。Azure Automation can't use runbooks with custom value descriptor types.

实例化连接活动的链接,并将其添加到 Runbook:Instantiate links connecting activities and add them to the runbook:

runbook.AddLink(new Link(activityA, activityB, LinkType.Sequence));

runbook.AddLink(
 new Link(activityB, activityC, LinkType.Pipeline) {
  Condition = string.Format("$ActivityOutput['{0}'] -gt 0", activityB.Name)
 });

将 Runbook 保存到文件Save the runbook to a file

使用 Orchestrator.GraphRunbook.Model.Serialization.RunbookSerializer 将 Runbook 序列化成字符串:Use Orchestrator.GraphRunbook.Model.Serialization.RunbookSerializer to serialize a runbook to a string:

var serialized = RunbookSerializer.Serialize(runbook);

可以将此字符串保存到扩展名为“.graphrunbook”的文件中。You can save this string to a file with the .graphrunbook extension. 相应的 runbook 可以导入到 Azure 自动化中。The corresponding runbook can be imported into Azure Automation. 可在将来的 Orchestrator.GraphRunbook.Model.dll 版本中更改序列化格式。The serialized format might change in the future versions of Orchestrator.GraphRunbook.Model.dll. 我们保证后向兼容性:使用旧版 Orchestrator.GraphRunbook.Model.dll 序列化的 Runbook 可由新版反序列化。We promise backward compatibility: any runbook serialized with an older version of Orchestrator.GraphRunbook.Model.dll can be deserialized by any newer version. 不保证前向兼容性:使用新版序列化的 Runbook 不一定能够由旧版反序列化。Forward compatibility is not guaranteed: a runbook serialized with a newer version may not be deserializable by older versions.

后续步骤Next steps

有关详细信息,请参阅在 Azure 自动化中创作图形 runbookFor more information, see Author graphical runbooks in Azure Automation.