Parameters Hints and Tips
Page edited by Stephen Turner
XenCenter provides parameter sets to your plugin to describe the current selection in the XenCenter resource list. See the plugin specification for the full details of the data in a parameter set.
This page details how to deal with this information using a Shell command, which requires some thought as there are no handy global variables separating everything out as is the case with the PowerShell commands.
Shell commands and parameters
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd"> <XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema" version="1"> <MenuItem name="hello-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="1, goodbye" /> </MenuItem> </XenCenterPlugin>
When using a Shell command, your parameters are passed directly as arguments to the plugin executable. In addition to the parameter sets, you will also receive any parameters you define in the param attribute on your XML. Outlined here are several approaches you might take to parse these arguaments, with examples in C#.
Option 1 - No extra params
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd"> <XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema" version="1"> <MenuItem name="hello-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" /> </MenuItem> </XenCenterPlugin>
This is the simple option. We know that parameter sets come in groups of four arguments so if none of the menu item commands which call that executable define anything in the param attribute we can just read them off in groups.
private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets) { ParamSets = new List<ParameterSet>(); for (int i = 0; i < args.Length; i += 4) { ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3])); } }
Option 2 - Fixed number of extra parameters
If you want to use extra parameters in your plugin commands, one option is to define a fixed number of extra parameters that each command must pass.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd"> <XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema" version="1"> <MenuItem name="goodbye-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="goodbye" /> </MenuItem> <MenuItem name="hello-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="hello" /> </MenuItem> <MenuItem name="quiet-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="BLANK_PARAM" /> </MenuItem> </XenCenterPlugin>
In this example you can see each command passes exactly one extra parameter, so we can read that off before moving onto the parameter sets. Commands that don't want to use all the parameters you are expecting can use a dummy keyword to keep the number of parameters consistent.
private static int numberOfExtraParams = 1; private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets, out List<string> ExtraParams) { ExtraParams = new List<string>(); for (int i = 0; i < numberOfExtraParams; i++) { ExtraParams.Add(args[i]); } ParamSets = new List<ParameterSet>(); for (int i = numberOfExtraParams; i < args.Length; i += 4) { ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3])); } }
Option 3 - Variable number of extra parameters
Here we are going to use some sort of indicator to help us know how many extra parameters there are going to be before the parameter sets start in our list of arguments. There are several ways to do this, but here we are going to use the first extra parameter as an indicator for how many further extra parameters we should expect.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd"> <XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema" version="1"> <MenuItem name="hello-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="1, goodbye" /> </MenuItem> <MenuItem name="busy-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="2, hello, goodbye" /> </MenuItem> </XenCenterPlugin>
private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets, out List<string> ExtraParams) { int numberOfExtraParams = 0; numberOfExtraParams = int.Parse(args[0]); ExtraParams = new List<string>(); for (int i = 0; i < numberOfExtraParams; i++) { ExtraParams.Add(args[i + 1]); } ParamSets = new List<ParameterSet>(); for (int i = numberOfExtraParams + 1; i < args.Length; i += 4) { ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3])); } }
This is a good technique as it only requires one extra parameter to encode the information and allows flexibility. Another alternative would be to have a marker which signifies that the extra parameters have finished:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd"> <XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema" version="1"> <MenuItem name="hello-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="goodbye, END_EXTRA_PARAMS" /> </MenuItem> <MenuItem name="busy-menu-item" menu="view" serialized="none"> <Shell filename="Plugins\Citrix\HelloWorld\HelloWorld.exe" window="true" param="hello, goodbye, END_EXTRA_PARAMS" /> </MenuItem> </XenCenterPlugin>
Changes between revision 3
and revision 4:
