Adding Devices to Virtual Machines

You can add devices to a virtual machine during creation using the VirtualMachineConfigSpec.deviceChange property, which is a VirtualDeviceSpec. You specify the host device that the virtual device should map to by using a backing object. A backing object represents the host device associated with a virtual device.

■	Backing option objects – You can find out which devices the host supports by extracting the relevant backing option object.

■	Backing information object – The backing information object allows you to supply data for virtual device configuration. You access a VirtualDeviceBackinInfo object as follows:

VirtualMachineConfigSpec.deviceChange[].device.backing

To add a device to a virtual machine, you must first find out which devices are supported on the corresponding ESX/ESXi host, and then specify a VirtualDevice object. Perform these tasks to add a device to a virtual machine:

1

Find out which devices your ESX/ESXi system supports by calling the QueryConfigOption method, which you can access through the VirtualMachine.environmentBrowser property. The method returns a VirtualMachineConfigOption data object that specifies what the ESX/ESXi supports. For example, VirtualMachineConfigOption.hardwareOptions includes information about supported CPU and memory and an array of VirtualDeviceOption data objects.

Note You cannot use the QueryConfigOption method to create another instance of a default device. If you attempt to add a default device, such as an IDE controller, the server ignores the operation.

2

Specify the backing information object for the device. The actual process for defining the object differs for different objects. For example, for a CD-ROM passthrough device, you use a VirtualCdromPassthroughBackingInfo device. The VirtualDevice.backing property is a VirtualDeviceBackingInfo object which is extended by devices.

The following code fragment adds a CD-ROM passthrough device:

VirtualCdromPassthroughBackingInfo vcpbi = new VirtualCdromPassthroughBackingInfo();

// Does the virtual device have exclusive access to the CD-ROM device?

vcpbi.setExclusive(false);

// Specifies the device name.

vcpbi.setDeviceName('cdrom0');

3	Specify connection information for the device.

The VirtualDevice.connectable property is a VirtualDeviceConnectInfo data object. This object provides information about restrictions on removing the device while a virtual machine is running. This property is null if the device is not removable.

VirtualDeviceConnectInfo vdci = new VirtualDeviceConnectInfo();

// Allow the guest to control whether the virtual device is connected?

vdci.setAllowGuestControl(false);

// Is the device currently connected?

vdci.setConnected(true);

// Connect the device when the virtual machine starts?

vdci.setStartConnected(true);

 

4	Define the controller key, the virtual device key, and the unit number.

You define these items with the integer properties: controllerKey, key, and unitNumber. See the VirtualDevice data object in the API Reference.

5	Specify device Information.

The deviceInfo property is a Description data object that has a name property and a summary property. You can supply a string value for each, describing the device.

Description vddesc = new Description();

vddesc.setLabel('CD-ROM Device cdrom0');

vddesc.setSummary('The CD-ROM device for this virtual machine.');

6	Specify the virtual device as the device property of a VirtualDeviceConfigSpec.

7	Specify the VirtualDeviceConfigSpec as the deviceChange property to the VirtualMachineConfigSpec that you pass in to a Folder.CreateVM_Task or VirtualMachine.ReconfigVM_Task method.

Here’s the complete code fragment for a CD-ROM passthrough device:

VirtualDevice vd = new VirtualDevice();

vd.setBacking(vcpbi);

vd.setConnectable(vdci);

vd.setControllerKey(257);

vd.setDeviceInfo(vddesc);

vd.setKey(2);

vd.setUnitNumber(25);