Product documentation
XenServer
8 Citrix Hypervisor 8.2 CU1
View PDF

Getting Started

August 23, 2023
Contributed by: 
C C

XenServer includes a Remote Procedure Call (RPC) based API providing programmatic access to the extensive set of XenServer management features and tools. You can call the XenServer Management API from a remote system or from local to the XenServer host.

It’s possible to write applications that use the XenServer Management API directly through raw RPC calls. However, the task of developing third-party applications is greatly simplified by using a language binding. These language bindings expose the individual API calls as first-class functions in the target language. The XenServer SDK provides language bindings for the C, C#, Java, Python, and PowerShell programming languages.

System Requirements and Preparation

The first step towards using the SDK is to install XenServer. XenServer is available for download at https://www.xenserver.com/downloads. For detailed instructions on how to set up your development host, see the Install XenServer. When the installation is complete, note the host IP address and the host password.

Downloading

The SDK is packaged as a ZIP file and is available as a free download from https://www.xenserver.com/downloads.

The Python module is also available as a package on PyPi. See section SDK Languages - Python for details.

SDK Languages

The extracted contents of the SDK ZIP file are in the XenServer-SDK directory. The following is an overview of its structure. Where necessary, subdirectories have their own individual README files.

Note:

The contents of the SDK ZIP consist of library binaries and their source code. Previous releases of the SDK ZIP included a number of examples for each of the SDK languages to help you get started with the SDK. These examples have now been removed from the SDK ZIP and are available at XenServer SDK usage examples on GitHub.

The examples provided aren’t the same across all the SDK languages. If you intend to use one language, it’s advisable to browse the sample code available in the others as well.

The top level of the XenServer-SDK directory includes the XenServer Management API Reference document. This document provides an overview of the API types and classes.

The API supports two wire formats, one based upon XML-RPC and one based upon JSON-RPC (v1.0 and v2.0 are both recognised). For more information on the API semantics and the wire protocol of the RPC messages, see section XenServer Management API. The format supported by each of the SDK languages is specified in the following paragraphs.

C

The XenServer-SDK directory contains the following folders that are relevant to C programmers:

  • libxenserver: The XenServer SDK for C.

    • bin: The libxenserver compiled library.

    • src: The libxenserver source code and a Makefile to build it. Every API object is associated with a header file, which contains declarations for all the object’s API functions. For example, the type definitions and functions required to invoke VM operations are all contained in xen_vm.h.

RPC protocol:

The C SDK supports the XML-RPC protocol.

Platform supported:

  • Linux
  • Windows (under cygwin)

Library:

The library is generated as libxenserver.so that is linked by C programs.

Note:

This library is not backwards compatible. To interact with hosts running older versions of XenServer or Citrix Hypervisor, it is advisable to use the library of the same version as the host.

Dependencies:

The library is dependent upon the XML toolkit from the GNOME project, by Daniel Veillard, et al. It is packaged as libxml2-devel on CentOS and libxml2-dev on Debian.

Examples:

Examples on the usage of the C SDK can be found at libxenserver usage examples on GitHub.

C #

The XenServer-SDK directory contains the following folders that are relevant to C# programmers:

  • XenServer.NET: The XenServer SDK for C#.NET.

    • XenServer.NET.x.y.z.nupkg: The compiled library shipped as a NuGet package.

    • src: XenServer.NET source code shipped as a Microsoft Visual Studio project. Every API object is associated with one C# file. For example, the functions implementing the VM operations are contained within the file VM.cs.

RPC protocol:

The C# SDK supports the JSON-RPC v2.0 protocol.

Platform supported:

  • Windows
  • Linux

The compiled library targets .NET Framework version 4.5 and .NET Standard 2.0.

Library:

The library is generated as a Dynamic Link Library XenServer.dll that C# programs can reference.

The C# SDK is backwards compatible and can be used to interact with hosts running all versions of XenServer or Citrix Hypervisor (from XenServer 7.3 and Citrix Hypervisor 8.0 onwards).

Dependencies:

Newtonsoft JSON.NET by James Newton-King. We use a patched version of the library (Newtonsoft.Json.CH.dll) shipped with XenServer.NET and recommend that you use this one, although others may work.

Examples:

Examples on the usage of the C# SDK can be found at XenServer.NET usage examples on GitHub.

Java

The XenServer-SDK directory contains the following folders that are relevant to Java programmers:

  • XenServerJava: The XenServer SDK for Java

    • xen-api-x.y.z.jar: Java archive file containing the compiled library.

    • xen-api-x.y.z-javadoc.jar: Java archive file containing the documentation.

    • xen-api-x.y.z-sources.jar: Java archive file containing the source code as a Maven project. Every API object is associated with one Java file. For example the functions implementing the VM operations are contained within the file VM.java.

RPC protocol:

The Java SDK supports the XML-RPC protocol.

Platform supported:

  • Linux
  • Windows

Library:

  • The library is a Java archive file xenserver.jar that is linked by Java programs.

Note:

This library is generally, but not fully, backwards compatible. To interact with hosts running older versions of XenServer or Citrix Hypervisor, it is advisable to use the library of the same version as the host.

Dependencies:

XenServerJava is dependent upon Apache XML-RPC by the Apache Software Foundation.

Examples:

Examples on the usage of the Java SDK can be found at XenServerJava usage examples on GitHub.

PowerShell

The XenServer-SDK directory contains the following folders that are relevant to PowerShell users:

  • XenServerPowerShell: The XenServer SDK for PowerShell.

    • XenServerPSModule: The XenServer PowerShell module.

    • src: C# source code for the XenServer PowerShell cmdlets.

Detailed installation instructions are provided within the README file accompanying the module. After the module is installed, you can obtain an overview of the cmdlets by typing:

PS> Get-Help about_XenServer

RPC protocol:

The PowerShell SDK supports the JSON-RPC v2.0 protocol.

Platform supported:

  • Windows
  • Linux

This library requires .NET 6.0 and PowerShell 7.2.

Library:

  • XenServerPSModule

Note:

This module is generally, but not fully, backwards compatible. To interact with hosts running older versions of XenServer or Citrix Hypervisor, it is advisable to use the module of the same version as the host.

Dependencies:

  • Newtonsoft JSON.NET by James Newton-King. We use a patched version of the library (Newtonsoft.Json.CH.dll) shipped with the XenServer PowerShell Module, although others may work.
  • XenServer.NET, the C# SDK for XenServer.

Examples:

Examples on the usage of the XenServer Powershell module can be found at XenServer PowerShell Module usage examples on GitHub.

Python

The XenServer-SDK directory contains the following folders that are relevant to Python developers:

  • XenServerPython: This directory contains the XenServer Python module XenAPI.py.

Alternative installation

The Python module is also available as a package on PyPi. To install the package, enable the virtual environment where it will be used and run

pip install XenAPI

Python module dependencies

The Python module supports the XML-RPC protocol.

Platform supported:

  • Linux
  • Windows

Library:

  • XenAPI.py

Dependencies:

  • xmlrpclib

Examples:

Examples on the usage of the XenServer Powershell module can be found at XenAPI.py usage examples on GitHub.

Command line interface (CLI)

Besides using raw RPC or one of the supplied SDK languages, third-party software developers can integrate with XenServer hosts by using the xe command line interface xe. The xe CLI is installed by default on XenServer hosts. A stand-alone remote CLI is also available for Linux. On Windows, the xe.exe CLI executable is installed along with XenCenter.

CLI dependencies

Platform supported:

  • Linux
  • Windows

Library:

  • None

Binary:

  • xe on Linux
  • xe.exe on Windows

Dependencies:

  • None

The CLI allows almost every API call to be directly invoked from a script or other program, silently taking care of the required session management. The xe CLI syntax and capabilities are described in detail in the Command line interface documentation. For more resources and examples, visit the Citrix Knowledge Center.

Note:

When running the CLI from a XenServer host console, tab completion of both command names and arguments is available.

Getting Started
August 23, 2023
Contributed by: 
C C
August 23, 2023
Contributed by: 
C C

In this article

Site feedback | Privacy and legal terms | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.