Executing System Center Orchestrator 2012 Runbooks from C#

The Problem:

System Center Orchestrator 2012 exposes a data service that enables to query and execute runbooks. But working directly with the data service is like executing a WCF service by manually composing the SOAP messages. There are no type-safe parameters, no intellisense and you need to type the exact path of the runbook or even worse, specify GUIDs . Developing and testing a code that is involved with Orchestrator runbooks execution quickly becomes a cumbersome and tedious task.

The Solution:

The solutions is a Visual Studio item template. When you add it to an existing project, it will ask for the Orchestrator servers details and generate hierarchy of proxy classes that match-up with the Orchestrator server folders hierarchy, and within every class there will be methods that will match-up with the runbooks on said folder that accept the runbooks parameters. In addition, the runbooks description will be appended to the methods remark summary, which makes the Visual Studio intellisense more helpful. Every class that contains runbooks also implements an interface named I{ClassName} that include these methods for easier testing. After adding this item to your project you will be able to execute a runbook as seen in the following code:

OrchestratorReference orchestratorReference = new OrchestratorReference();
Guid jobId = orchestratorReference.Development.Utils.WriteErrorLog(message, activity, runbook);

The OrchestratorReference object can be initialized with the credentials for accessing the Orchestrator web services.Ex:

OrchestratorReference orchestratorReference = new OrchestratorReference();
NetworkCredential cred = new NetworkCredential(userName, password, domain);
orchestratorReference.OrchestratorServiceCredentials = cred;

In case the runbook paths prefix depends on development environments you can use the AddReplaceFolderPrefix method to dynamically replace the path prefix. Ex:

OrchestratorReference orchestratorReference = new OrchestratorReference();
orchestratorReference.AddReplaceFolderPrefix(@"Development", @"Production");

All the runbooks functions return the job Id that was created on the Orchestrator server. The execution of the runbooks is asynchronized, to wait for the runbook completion and optionally collect the runbooks return values, you can use the created job Id with the following methods:

Guid jobId = orchestratorReference.Development.VMManager.VM.GetNextVMName("Test##");
Dictionary result = orchestratorReference.GetJobResult(jobId);
string nextVMName = result["nextVMName"];

public async Task GetNextVMName(string template)
{
   OrchestratorReference orchestratorReference = new OrchestratorReference();
   Guid jobId = orchestratorReference.Development.VMManager.VM.GetNextVMName(template);
   Dictionary result = await orchestratorReference.GetJobResultAsync(jobId);
   return result["nextVMName"];
}

The T4 template, responsible for generating the code, removes any classes/methods duplication and will name classes/methods with Pascal-case and methods parameters with camel-case. It also removes from the class/methods name any un-letter prefix characters, so if the folder name includes an index number prefix, this index will be truncate and will be visible only from the class/methods remarks summary.

Deployment:

1. Extract the zip file available for download at the bottom of this post.
2. Execute the “DeployItemTemplate.cmd” file.

Using:

1. Open Visual Studio 2010
2. Click on add -> new item, in a project from which you need to execute a runbook
3. Choose the Orchestrator Reference template from the template list, type in a file name and click OK
4. Type the Orchestrator servers name, port number where the Orchestrator service is listening (default 81) and if SSL is required
5. Click on the Load button. The wizard will load the folders structure from the Orchestrator service and will enable to specify which folders to include in the new generated class
6. Click the Add button.
7. Optional – Expand the template file to check the generated cs file.
8. Happy developing!

Source & Binary (107 KB)