This project is read-only.

Project Description

This library wraps the VMware VixCOM-API into an object-orientated library in C# with IntelliSense support and exception throwing.

The current implementation uses VIX-API 1.10 and allows automating common tasks of Virtual Machines. For a list of functions see the included help.

Although the VIX-API provides a COM binding (called VixCOM) that can be used in .NET, the functions and especially their parameters look different from what we are used to in .NET languages (because the original API was written in C ).
This library wraps the VixCOM-API and allows you to control VMs in a way you are familiar with, including full IntelliSense support in Visual Studio. The description of the functions and parameters was taken directly from the VMware VIX documentation and was also extended where appropriate.

The functions of this library are implemented synchronously (that means they return when the action completes), which hides you from the need of using callback-functions or polling/blocking, like you had to with the original API. If you need to run severeral tasks at a time, I suggest putting each task in a thread. According to the documentation, the VIX-API should be thread-safe and handle calls from different thread appropriately.

Another benefit of this library is that it throws exceptions when an error in a VIX function occurs, while the original API only returns an error code.

If you need further information on the VIX-API itself, visit http://www.vmware.com/support/developer/vix-api/

Releases

Binaries: VixCOMWrapperBin.zip
Documentation: VixCOMWrapperDoc.chm (Note: if you have problems viewing the file, right-click on it and click Properties -> Unblock)
Sample application: VixCOMWrapperSampleApp.zip

Getting Started

  1. Download the latest release.
  2. Add a reference to VixCOMWrapper.dll to your project.
  3. Check the examples below or take a look at the sample application to learn how to use the library.

Note: The VMware VIX API has to be installed in order for the library to work correctly. When a VMware product like Workstation, Server 1.x or 2.x is already installed, the VIX API will be available as well. In other cases, get the redistributable of the API from here: http://www.vmware.com/support/developer/vix-api/

Code examples

The following examples will give you a short introduction about the possibilities of the library.

Connecting to a VMware host

Here is an example of how to connect to a VMware host and getting an instance of the Host class.

VIX.Host hostObject = VIX.VixCOMWrapper.Instance.Connect(
                                 VIX.Enums.VIX_SERVICEPROVIDER.VMWARE_VI_SERVER, 
                                 "https://servername:8333/sdk",
                                 0,
                                 "Username",
                                 "Password");
In the above example we are connecting to a VMware Server 2.x host. Remember to call hostObject.Disconnect() when you are done, otherwise VIX can't clean up handles etc.

Getting registered VMs

You can use the FindItems() function of the Host class to get the registered VMs.

List<string> vms = hostObject.FindItems(VIX.Enums.VIX_FIND.REGISTERED_VMS);
Similarily, if you want to get only the running VMs, pass VIX.Enums.VIX_FIND.RUNNING_VMS as parameter.

Starting a VM

You will need to connect to a host and retrieve a Host-object first, then you can call the OpenVMEx() function. You must pass the path to the .vmx file of the VM, in this case it is a VMware Server 2.x host, so we also need to specify the datastore (-> [standard] ).

VIX.VM vmObject = hostObject.OpenVMEx("[standard] VirtualMachine1.vmx", null);

vmObject.PowerOn(VIX.Enums.VIX_VMPOWEROP.NORMAL);
The PowerOn() function takes an enumeration as parameter, which specifies how the VM should be powered on. Check the documentation for details.

Running programs in the guest operating system

You can run any programs in the guest OS by using the RunProgramInGuest() function. Before calling this function, we need to establish an authentication context in the guest by calling LoginInGuest().

VIX.VM vmObject = hostObject.OpenVMEx("[standard] VirtualMachine1.vmx", null);

vmObject.LoginInGuest("Username", "Password", true);

vmObject.RunProgramInGuest(@"C:\Windows\system32\calc.exe", "", true, false, false);

Getting basic information about a VM

With the GetProperties() function you can retrieve basic information about a VM, like the power-state, if VMware Tools are installed, etc.

VIX.VM vmObject = hostObject.OpenVMEx("[standard] VirtualMachine1.vmx", null);

List<object> result = vmx.GetProperties(
new VIX.Enums.VIX_PROPERTY[] {     VIX.Enums.VIX_PROPERTY.VM_POWER_STATE, 
                                          VIX.Enums.VIX_PROPERTY.VM_TOOLS_STATE, 
                                          VIX.Enums.VIX_PROPERTY.VM_VMX_PATHNAME, 
                                          VIX.Enums.VIX_PROPERTY.VM_SUPPORTED_FEATURES, 
                                          VIX.Enums.VIX_PROPERTY.VM_MEMORY_SIZE, 
                                          VIX.Enums.VIX_PROPERTY.VM_NUM_VCPUS, 
                                          VIX.Enums.VIX_PROPERTY.VM_READ_ONLY }
);

MessageBox.Show("POWER_STATE: " + ( (VIX.Enums.VIX_POWERSTATE) result[0] ).ToString() );
...


Basically, you just pass the properties you want to retrieve in a VIX_PROPERTY array, the results will be stored in a list of objects. The first property requested matches the first value in the list and so on.

Links

VMware VIX-API homepage
VIX-API 1.10 Documentation

Last edited Aug 18, 2010 at 7:40 PM by akoeplinger, version 19