Posts Tagged ‘DataService’

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 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 server’s 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 runbook’s parameters. In addition, the runbook’s description will be appended to the method’s 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 path’s 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 runbook’s return values, you can use the created job Id with the following methods:

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


 public async Task GetNextVMName(string template)
   OrchestratorReference orchestratorReference = new OrchestratorReference();
   Guid jobId =
   Dictionary<string, string> 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 remark’s summary.


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


  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.
    Orchestrator Reference - add item template
  4. Type the Orchestrator server’s 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.
    Orchestrator Reference
  6. Click the “Add” button.
  7. Optional – Expand the template file to check the generated cs file.
  8. Happy developing!

Source & Binary

Read Full Post »