VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Adding Devices to Virtual Machines
Last Updated December 16, 2024

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 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 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 ESXi supports. For example,
    VirtualMachineConfigOption.hardwareOptions
     includes information about supported CPU and memory and an array of
    VirtualDeviceOption
     data objects.
    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);

Content feedback and comments