Dblock.org | Code

VMWare Tasks Library

Sat, 03 Jan 2009 14:15:00 GMT

The VMWare Tasks Library is a managed C# wrapper on top of VMWare COM ViX API that makes it really easy to use.

Download Latest Build (1.0.1604.0, updated Jan 03, 2009)
CodeProject Article
Live source code in SVN

Features:

a much more natural and easy programming model
supports virtual machine VI (ESX) and Workstation
enumerate and power Virtual Machines
enumerate, revert and power snapshots
execute commands in guest OS
list and delete files and directories with subdirectories in guest OS
manage shared folders
read and write guest and environment variables

Read | Updated 1/3/2009

Abstracting a cumbersome construct in VIX API: GetNumProperties + GetNthProperty

Sat, 27 Dec 2008 22:15:00 GMT

Did I tell you how much I love yield return?

One of the peculiar VIX COM API constructs is the combination that returns arrays of properties. This is done with two functions: GetNumProperties and GetNthProperties. The first returns the number of property arrays returned by the job and the second fetches a property array at a given index. The first obvious step is to wrap the functions within the job class.

public T GetNthProperties(int index, object[] properties){
   object result = null;   VMWareInterop.Check(_handle.GetNthProperties(
      index, properties, ref result));   return (T) result;}
 public int GetNumProperties(int property){
   return _handle.GetNumProperties(property);}

We can now write such properties as RunningVirtualMachines.

public IEnumerable RunningVirtualMachines{
   get   {
      VMWareJob job = new VMWareJob(_handle.FindItems(         Constants.VIX_FIND_RUNNING_VMS, null, -1, null));
      job.Wait(VMWareInterop.Timeouts.FindItemsTimeout);
      object[] properties = { Constants.VIX_PROPERTY_FOUND_ITEM_LOCATION };
      for (int i = 0; i < job.GetNumProperties((int) properties[0]); i++)
      {
         yield return this.Open(
            (string) job.GetNthProperties<object[]>(
               i, properties)[0]);
      }
   }
}

This is still not good enough. Let's combine the number of results and the results themselves in a YieldWait method.

public IEnumerable<object[]> YieldWait(object[] properties, int timeoutInSeconds){
   Wait(timeoutInSeconds);
   for (int i = 0; i < GetNumProperties((int)properties[0]); i++)   {
      yield return GetNthProperties<object[]>(i, properties);   }
}

This results in a nice improvement over the previous implementation: we're interating over a resultset rather than calling methods for how many results are available and to fetch each result.

public IEnumerable<VMWareVirtualMachine> RunningVirtualMachines{
   get   {
      VMWareJob job = new VMWareJob(_handle.FindItems(         Constants.VIX_FIND_RUNNING_VMS, null, -1, null));
      object[] properties = { Constants.VIX_PROPERTY_FOUND_ITEM_LOCATION };
      foreach (object[] runningVirtualMachine in job.YieldWait(
         properties, VMWareInterop.Timeouts.FindItemsTimeout))
      {
         yield return this.Open((string) runningVirtualMachine[0]);
      }
   }
}

Read | Updated 12/27/2008

Getting the display name of a VMWare snapshot

Fri, 26 Dec 2008 14:00:00 GMT

Looking at the source code of another VMWare C# wrapper on CodePlex, turns out that most VMWare interfaces represent VMWare handles. This is a good decision from the design point of view, but the implementation in VMWare VIX API is wrong: it should be returning objects that implement multiple interfaces, instead it returns one of the interfaces that you can happily cast to another.

This does answer the question of how to get the display name of a VMWare snapshot.

Let's add a wrapper for a VIX handle.


/// 
/// A wrapper for a VIX handle. Most VIX objects returned also implement IVixHandle.
/// 

public class VMWareVixHandle
{
 IVixHandle _handle = null;
 public VMWareVixHandle(IVixHandle handle)
 {
  _handle = handle;
 }

 /// 
 /// Get an array of properties.
 /// 

 /// properties to fetch
 /// an array of property values
 public object[] GetProperties(object[] properties)
 {
  object result = null;
  VMWareInterop.Check(_handle.GetProperties(properties, ref result));
  return (object[]) result;
 }
}

Then the snapshot's name is a cast to a IVixHandle which implements GetProperties.


public string DisplayName
{
 get
 {
  object[] properties = { Constants.VIX_PROPERTY_SNAPSHOT_DISPLAYNAME };
  return (string)new VMWareVixHandle((IVixHandle) _snapshot).GetProperties(properties)[0];
 }
}

Read | Updated 12/26/2008

Copying files to/from VMWare guest OS is slow: an alternate approach

Wed, 24 Dec 2008 05:45:00 GMT

I really like VMWare VIX API's CopyFileFromGuestToHost and CopyFileFromHostToGuest. These automatically copy a single file or an entire directory tree. Easy. Unfortunately I am copying large (150-300 Mb) files to/from a VMWare guest OS and it's taking an hour to copy a hundred megs. I bet VMWare API was developed by Russian developers, so it's probably sending UTF-8 encoded bytes in Russian via SOAP. You might remember that I am writing a tool that lets one test a cross-product of installers and virtual machine snapshots: three MSIs multipled by twenty snapshots equals days of file copying! It's not going to work.

I posted a question about this in VMWare Communities and got a satisfactory response: I don't think there is a workaround. We are aware of the issue (we run in to it internally) and hope to fix it in a future release.

In the meantime, I need a short term solution.

I decided to try and map the remote drive and use a simple File.Copy. The first challenge is to find out the remote server's IP address. VMWare exposes guest OS variables, including the ip, so I've extended VMWare Tasks to support those.


/// 
/// Environment, guest and runtime variables
/// 

/// name of the variable
[IndexerName("Variables")]
public string this[string name]
{
 get
 {
  VMWareJob job = new VMWareJob(_vm.ReadVariable(_variableType, name, 0, null));
  object[] properties = { Constants.VIX_PROPERTY_JOB_RESULT_VM_VARIABLE_STRING };
  return job.Wait<string>(properties, 0, VMWareInterop.Timeouts.ReadVariableTimeout);
 }
 set
 {
   VMWareJob job = new VMWareJob(_vm.WriteVariable(_variableType, name, value, 0, null));
   job.Wait(VMWareInterop.Timeouts.WriteVariableTimeout);
  }
}

Here's the IP address of a powered-on VM.


virtualMachine.GuestVariables["ip"];

We can make up a network path out of a local one.


public string PathToNetworkPath(string ip, string value)
{
 return string.Format(@"\\{0}\{1}", ip, value.Replace(":", "$"));
}

Mapping a network drive is implemented in mpr.dll with WNetAddConnection2. A wrapper class will do the job.


public class NetworkDrive
{
 [DllImport("mpr.dll")]
 public static extern int WNetAddConnection2(
   ref NETRESOURCE lpNetResource, string lpPassword, string UserName, int dwFlags);
 [StructLayout(LayoutKind.Sequential)]
 public struct NETRESOURCE
 {
  public int dwScope;
  public int dwType;
  public int dwDisplayType;
  public int dwUsage;
  public string lpLocalName;
  public string lpRemoteName;
  public string lpComment;
  public string lpProvider;
 }
 private const int RESOURCETYPE_DISK = 0x1;
 private string _localName;
 private string _remoteName;
 public NetworkDrive(string remoteName)
 {
  _remoteName = remoteName;
 }
 public NetworkDrive(string remoteName, string localName)
 {
  _remoteName = remoteName;
  _localName = localName;
 }
  public string LocalName
  {
   get { return _localName; }
   set { _localName = value; }
  }
  public string RemoteName
  {
   get { return _remoteName; }
   set { _remoteName = value; }
  }
 public void MapNetworkDrive(string username, string password)
 {
   NETRESOURCE netResource = new NETRESOURCE();
   netResource.dwScope = 2;
   netResource.dwType = RESOURCETYPE_DISK;
   netResource.dwDisplayType = 3;
   netResource.dwUsage = 1;
   netResource.lpRemoteName = _remoteName;
   netResource.lpLocalName = _localName;
   int rc = WNetAddConnection2(ref netResource, password, username, 0);
   if (rc != 0)
   {
    throw new Win32Exception(rc);
   }
 }
}

Let's put it all together.


public void CopyFileFromGuestToHost(string guestPath, string hostPath)
{
  string guestNetworkPath = PathToNetworkPath(_ip, guestPath);
  NetworkDrive guestNetworkDrive = new NetworkDrive(Path.GetPathRoot(guestNetworkPath));
  guestNetworkDrive.MapNetworkDrive(_username, _password);
  File.Copy(guestNetworkPath, hostPath, true);
}

The last thing that remains to be done to make the new copy compatible is to also copy directories and subdirectories. That's left as an exercise to the reader.

Read | Updated 12/26/2008

Announcing the VMWare Tasks Library

Sat, 20 Dec 2008 05:30:00 GMT

Now that I wrote various tools that interop with VMWare, I started working on a VMWare Tasks Library, a managed C# wrapper on top of VMWare COM ViX API that makes it really easy to use.

I checked in basic functionality of connecting to a virtual machine host, restoring snapshots, powering them up, executing commands, getting lists of files in a directory and subdirectories, etc.

At my day job we developed a tool that uses VMWare to test installers (executes a cross-product of virtual machine snapshots and installers). I plan to take an alternate approach here and write an MSBuild Task to control VMWare, which could enable more flexible automation scenarios.

Read | Updated 12/22/2008

HowTo: remote control, copy and run programs on a VMware Workstation or VI server using VIX APIs

Wed, 10 Dec 2008 20:15:00 GMT

I've been playing with VMware lately, both Workstation and VMware Infrastructure (VI). The company has really stepped up with the new SDKs and the level of programmable interfaces, making some excellent implementation decisions that enable us to drive virtual machines for primarily unit-testing purposes. The doc is a little light today, so this should help.

What do we use this for?

We (at my day job) developed a tool (in C#) that runs MSI installers to make sure the product installs on various knownly good or bad environments, sort of unit testing installers. We also have an ESX environment that we share.

VMWare Programming APIs

There're two types of APIs.

VMWare Virtual Infrastructure SDK: a set of tools and APIs to manage a VMWare Infrastructure environment. A toolkit has also been released that contains managed wrappers on top of the SOAP interface provided by a VMWare deployment. It's focused on VMWare ESX or VirtualCenter management and is beyond the scope of this post.
VMWare VIX API. The VIX API allows you to write programs and scripts that automate virtual machine operations, as well as the guests within virtual machines. It runs on both Windows and Linux and supports management of VMware Server, Workstation, and Virtual Infrastructure (both ESX and vCenter). Bindings are provided for C, Perl, and COM (Visual Basic, VBscript, C#). In this post I'll focus on the C# implementation.

What do you need?

Either VMWare Workstation 6.5, a VI environment (I use ESX), or both.
VMWare ViX. This is the SDK, obtained from http://www.vmware.com/download/sdk/vmauto.html. The new 1.6.2 version is required for VI support.

Connecting to a VMWare Workstation or ESX Server

Connecting to a local VMWare Workstation or an ESX server is virtually identical. The ESX server requires an URL to the SOAP SDK (eg. https://esxserver/sdk) and a username and password.


private void ConnectToVMWareWorkstation()
{
 Connect(Constants.VIX_SERVICEPROVIDER_VMWARE_WORKSTATION, string.Empty, 0, string.Empty, string.Empty);
}
private void ConnectToVMWareVIServer(string hostName, int hostPort, string username, string password)
{
 Connect(Constants.VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,  hostName, hostPort, username, password);
}

private void Connect(int hostType, string hostName, int hostPort, string username, string password)
{
 // Connect to a VMware Workstation
 IJob vmJob = VmwareVixInterop.vixLib.Connect(
  Constants.VIX_API_VERSION, hostType, hostName, hostPort, username, password, 0, null, null);
 // You need to get the IHost object that represents the host where your VM is located.
// Since COM allocates the pointer you need to use this funky mechanism to extract the IHosts array.
 object[] VIX_PROPERTY_JOB_RESULT_HANDLE =  new object[1];
 VIX_PROPERTY_JOB_RESULT_HANDLE[0] = Constants.VIX_PROPERTY_JOB_RESULT_HANDLE;
 // Wait for the operation to complete
 object hosts = VmwareVixInterop.Wait(vmJob, VIX_PROPERTY_JOB_RESULT_HANDLE);
 // Cast and retrieve the IHost object.
 object[] hostArray = hosts as object[];
 _host = (IHost) hostArray[0];
}

Locating a Virtual Machine

A virtual machine on a VMWare Workstation is a file with a standard path (eg. C:\Virtual Machines\myvirtualmachine.vmx). Unsurprisingly it is the same thing on an ESX server, but with a relative storage path. The latter can be found in the VMWare Infrastructure Client: right click on a virtual machine, choose Edit Settings, click the Options tab and note the Virtual Machine Configuration File (eg. [storage] virtualmachine/virtualmachine.vmx).


public void OpenFile(string fileName)
{
 // Open the VM from the path specified
 IJob vmJob = _host.OpenVM(fileName, null);
 object[] resultHandles = new object[1];
 resultHandles[0] = Constants.VIX_PROPERTY_JOB_RESULT_HANDLE;
 // Wait for the operation to complete
 object vms = VmwareVixInterop.Wait(vmJob, resultHandles);
 // Get the VM object returned
 Object[] vmArray = vms as Object[];
 _vm = (IVM) vmArray[0];
}

Power-on, power-off, copy and execute

These are straightforward operations supported by the SDK via the IVM interface returned set by the above-mentioned OpenFile method. Here're some examples.

IJob PowerOn(int powerOnOptions, IVixHandle propertyList, ICallback jobDoneCallback);
IJob RevertToSnapshot(ISnapshot snapshot, int options, IVixHandle propertyList, ICallback jobDoneCallback);
IJob CopyFileFromHostToGuest(string hostPathName, string guestPathName, int options, IVixHandle propertyList, ICallback jobDoneCallback);

It is now possible to execute commands synchronously and asynchronously, without having to involve WMI or another similar method.


public int Execute(string path, string parameters)
{
 IJob vmJob = _vm.RunProgramInGuest(path, parameters, VixCOM.Constants.VIX_RUNPROGRAM_ACTIVATE_WINDOW, null, null);
 object[] propertyIDs = new Object[] { Constants.VIX_PROPERTY_JOB_RESULT_GUEST_PROGRAM_EXIT_CODE };
 object results = VmwareVixInterop.Wait(vmJob, propertyIDs);
 return Convert.ToInt32(((object[])results)[0]);
}

I think the whole job-based API could use a nice .NET wrapper :)

Read | Updated 12/26/2008

WMI: Executing a remote process and waiting for its completion

Wed, 03 Dec 2008 21:45:00 GMT

This drove me crazy for an hour. I needed to execute a remote process via WMI and wait for it to finish. Lots of online resources are suggesting to use __InstanceCreationEvent, but that always threw access denied errors back at me. This is a workable straightforward solution, waiting for process to finish by quering the running processes.

ConnectionOptions connOptions = new ConnectionOptions();
connOptions.Impersonation = ImpersonationLevel.Impersonate;
connOptions.Authentication = AuthenticationLevel.Default;
connOptions.Username = ...;
connOptions.Password = ...;
connOptions.EnablePrivileges = true;
ManagementScope scope = new ManagementScope(@"\\" + machinename + @"\root\cimv2", connOptions);
scope.Connect();

ManagementPath mgmtPath = new ManagementPath("Win32_Process");
ManagementClass mgmtClass = new ManagementClass(_scope, mgmtPath, null);
ManagementBaseObject mgmtBaseObject = mgmtClass.GetMethodParameters("Create");
mgmtBaseObject["CommandLine"] = commandLine;
ManagementBaseObject outputParams = mgmtClass.InvokeMethod("Create", mgmtBaseObject, null);
uint pid = (uint) outputParams["processId"];
Console.Write("Pid: {0} ", pid);
while (Select("Win32_Process", string.Format("processId = {0}", pid)).Count > 0)
{
Console.Write(".");
Thread.Sleep(1000);
}
Console.WriteLine(" done.");

Read | Updated 12/3/2008

Count projections in NHibernate 1.2

Wed, 03 Dec 2008 14:45:00 GMT

For someone who got stuck with NHibernate 1.1 it was actually surprisingly hard to find much about projections. Before you had to do different queries for a COUNT or a SELECT and you couldn't use ICriteria.

 
int count = (int) session.CreateQuery(string.Format(
 "SELECT COUNT(instance) FROM Login instance WHERE Role='{0}'", 
 TransitLoginRole.Administrator.ToString()))
 .UniqueResult();

This is resolved with a projection.

int count = session.CreateCriteria(typeof(Login))
 .Add(Expression.Eq("Role", TransitLoginRole.Administrator.ToString()))
 .SetProjection(Projections.Count("Id"))
 .UniqueResult<int>();

IList<Login> logins = session.CreateCriteria(typeof(Login))
 .Add(Expression.Eq("Role", TransitLoginRole.Administrator.ToString()))
 .List<Login>();

Nice and easy.

Read | Updated 12/3/2008

Resetting a Canon MP460

Wed, 03 Dec 2008 04:25:03 GMT

This is going to be my first hardware post. We'll start simple - I do have a copy of The Art of Electronics and a welder, so there's a chance I might post something meaningful one day.

I was about to throw my MP460 Canon printer (80$) out of the window (8th floor, 10$ a flight of stairs). I was trying to setup a wireless print server and finally got that working, when the printer came back with an obscure 5100 error. I tried everything, including shaking it violently. What worked was a reset, and this page explains how.

Turn off the printer
Hold the Resume Button (red circle in the triangle), add a printer (click “Power”) an indicator light green.
Hold the Power Button, release the Resume Button.
Not releasing the Power Button, double click “Resume” and release Both Buttons.
Click “Resume” for Four times
Once you click “Power”, to confirm the selected action (reset counter absorber). To disable the printer “Power” button to click again.

On the wireless front, I got a Linksys WPS54G. None of the wizards worked, go figure. I ended up being able to connect to the printer's HTTP configuration interface, but couldn't configure it on Vista. It wasn't too hard to configure manually with some help.

Add the appropriate printer from Control Panel, Printers, Add Printer
Select Local Printer and select Create New Port, Standard TCP/IP Port
Device Type, TCP/IP Device.
HostName or IPAddress should be the IP Address of the Print Server Device. I configured it with a static IP.
After nothing is detected choose Custom, Settings
Select LPR, set Queue Name to L2 for USB printer.
Turn on LPR Byte Counting Enabled.
Select the printer, install the driver.

Easy? Ahem.

Read

DNI: setup (msi) bootstrapper 1.5 released

Sun, 26 Oct 2008 22:59:40 GMT

DNI 1.5 has been released > Read/Download. I've been contributing to this open-source project for a while. You can read about that here.

Read