XenCenter Plugins - Hello World Example

Introduction

Here is a short example which will guide you through the creation of a XenCenter plugin.
Objective: We would like a new menu item in XenCenter which says "hello from ..." where "..." denotes the name of the object selected in the treeview.
In this example we shall achieve this by using the XenServerPSSnapIn PowerShell bindings.

Requirements

The first step is to install the following requirements:

XCPlugin file

Now we need to create a plugin descriptor file.
We start with the XenCenterPlugin node with the following attributes:

• xmlns - Specifies the schema of the XML file.
• version - The XenCenter Plugins version, we are using version 1.
• plugin_version - The version number of this plugin.

<XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
 version="1" plugin_version="1.0.0.0">

To create a menu item we add a MenuItem node under the XenCenterPlugin node. We give this three attributes:

• name - For identfying the menu item, used to reference the label in the resources file.
• menu - The name of the menu under which the menu item should appear. Let's use the 'View' menu.
• serialized - Decides if copies of the plugin running simutaneously are allowed for the same object. Here we do not limit this so we set to "none".

<MenuItem name="hello-menu-item" menu="view" serialized="none">

Next we add the XenServerPowerShell tag which points to a PowerShell script to run:

• filename - The filepath relative to the install directory of the XenCenter executable of a PowerShell script to run (or an absolute filepath).
• window - Show the console window which runs the script. We don't want this.

<XenServerPowerShell filename="Plugins\Citrix\HelloWorld\HelloWorld.ps1" window="false" />

Close off all the tags and save as HelloWorld.xcplugin.xml. The name of this file must be the same name as the name of the plugin directory in which it resides.

Resources

The next step is to add some resources which provide strings and images for the plugin. These are stored in DLLs so that the correct language (if other cultures are provided) can be loaded at run-time.

First we need to create the resx file. This can be done using Visual Studio. Add strings for the menu-item labels, copyright statements, filepaths to icons etc. The names of the resources strings should be <name>.<property>, where <name> is the name given to the tag and <property> is one of the properties found in the specification. Here is the resources table for this plugin.

 The final step is to convert this .resx into a DLL. We do this with two tools:

1. ResGen.exe - Creates a .resources file from the resx. This can be found in the .NET framework SDK.
2. Al.exe - Embeds the .resources file into a DLL. We specify we want to create a library, the file we wish to embed, that we need the invariant culture and the name of the DLL file. Al.exe is in the .NET framework directory. 

C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\ResGen.exe HelloWorld.resx
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\al.exe /t:lib /embed:HelloWorld.resources
 /culture:0x007F /out:HelloWorld.resources.dll

Attachments: HelloWorld.resx, HelloWorld.resources.dll

PowerShell

We can put any PowerShell in the script. This example makes use of the context sensitive data which is passed to the PowerShell script. XenCenter sets up the following variables before executing the script:

• $url - The URL of the server which owns the object selected in the tree view
• $uuid - An authenticated session ID for the server (allows the script to log into the server)
• $class - The type of the object selected: Server, VM etc
• $objUuid - The UUID for the selected object.

Before any server commands can be used create a new connection with the session. We can do this in PowerShell.

Connect-XenServer -url $url -opaqueref $uuid

We can then use XenServer commands without having to provide credentials for each PowerShell statement.

Get-XenServer:VM -properties @{ uuid='$uuid' } #gets the selected VM

 Finally we can also make .NET Windows Forms to create an alert box. We have to load the correct DLL before we request the MessageBox.

[Reflection.Assembly]::loadwithpartialname('system.windows.forms')
[System.Windows.Forms.MessageBox]::show("Hello from {0}!" -f $obj.name_label, "Hello World!")

 The full PowerShell script is HelloWorld.ps1

Deployment

The best way to distribute your XenCenter plugin is to package your plugin into a single MSI (Windows Installer) file.

Using a Windows Installer allows you to make sure the plugin is being installed into the correct place (by checking the XenCenter InstallDir registry key) and it gives versioning. A newer version will automatically uninstall the old version and then install the new one.

You can use the Create-PluginInstaller.ps1 PowerShell script to do this. The following command was used to make HelloWorld.msi:

 .\Create-PluginInstaller.ps1 -out HelloWorld.msi -title "XenCenter Hello World Plugin"
 -description "Sample plugin for XenCenter" -manufacturer Citrix -upgrade_code $([System.Guid]::NewGuid().ToString())

Screenshots