vSphere Web Services SDK 5.5 Release Notes

Released 22Sep2013

The vSphere Web Services SDK supports the development of vSphere client applications that use the vSphere API to manage virtual machines and other virtual infrastructure components (datacenters, datastores, networks, and so on).

• Distribution Kit
• New vSphere API Elements
• Java Development Kit
• Behavior Changes
• Known Issues
• Resolved Issues
• Deprecations Summary

Distribution Kit

The vSphere Web Services SDK is distributed as part of the vSphere Management SDK. The vSphere Management SDK is a collection of vSphere SDKs. When you extract the contents of the distribution kit, the vSphere WSSDK is contained in the SDK sub-directory:

VMware-vSphere-SDK-n.n.n-build-num
    SDK
        eam
        sms-sdk
        spbm
        ssoclient
        vsphere-ws


New vSphere API Elements

For information about additions to the vSphere API (new managed object types, data object types, properties, and methods), see the vSphere API Reference. The main landing page for the vSphere API Reference contains links to this information in the section "What's New in vSphere API 5.5?".

Java Development Kit

The vSphere Web Services SDK Java samples were built using the Java JDK 1.6. If you use JDK 1.7, the Server will generate runtime warnings.

Use the following steps to suppress vSphere runtime warnings based on the JDK 1.7 environment:

• Create the file named logging.properties in the following directory:
  
    SDK\vsphere-ws\java\JAXWS\
  
  
• Add the following line to the logging.properties file:
  
    com.sun.xml.ws.policy.EffectiveAlternativeSelector.level=OFF
  
  
• Modify the SAMPLE_PROPERTIES variable in the run.bat and run.sh files (located in the SDK\vsphere-ws\java\JAXWS\ directory). Use the following definition:
  
    set SAMPLE_PROPERTIES= -Dsamples.trustAll=true
 -Djava.util.logging.config.file=logging.properties

Behavior Changes

In vSphere 5.5, the ReconfigVM_Task method will throw an error when it attempts to change certain virtual machine properties while the virtual machine is powered on. In previous releases, the Server would modify the properties in the configuration specification and the changes would take effect after the virtual machine resets, reboots, or performs a fast suspend and resume. In vSphere 5.5, a reconfigure operation modifies the virtual machine in real time, so that the virtual machine properties have been changed by the time the method returns control to the client.

You cannot reconfigure a virtual machine successfully if you specify any of the following properties in the VirtualMachineConfigSpec when you call the ReconfigVM_Task method.

Known Issues

• Delta disk format conversion to nativeFormat fails during Storage vMotion. If you have a linked clone that uses seSparseFormat or redoLogFormat for its delta disk format, you cannot use vMotion to convert to a native snapshot. To convert the delta disk format, use the following steps to perform a cold relocation:
  1. Power off the virtual machine clone.
  2. Set the delta disk format to nativeFormat (VirtualMachineRelocateSpec.disk.diskBackingInfo.deltaDiskFormat).
  3. Call the RelocateVM_Task method.
  4. Power on the virtual machine clone.
• SCSI LUN queue depth is not available - the ESXi Server does not set the ScsiLun.queueDepth property. Modifications to this property will have no effect. Property retrieval will not produce a value.

Documentation Issues

• NFSV41 is not supported as a file system volume type (the HostFileSystemVolume.type property).
• As of vSphere 5.0, vSphere bulletins are not stored on ESXi hosts. As a consequence, the QueryHostPatch_Task method does not return any data about installed bulletins. To obtain information about installed patches, use the ESXCLI command "esxcli software vib list". This command returns the complete list of VIBs (vSphere Installation Bundles) installed on the host.

  To manipulate VIBs on ESXi hosts, use the following vSphere API method and ESXCLI commands:

  Task	Method or Command
  Install a VIB	HostPatchManager.InstallHostPatchV2_Task
  Uninstall a VIB	esxcli software vib remove
  Retrieve a list of VIBs	esxcli software vib list

• VirtualMachine.CloneVM_Task method fails, producing the following error - "The specified delta disk format 'nativeFormat' is not supported." The vCenter Server returns the error in the following situation:
  1. Create a VAAI NAS native linked clone virtual machine that uses nativeFormat for the delta disk format (VirtualMachineCloneSpec.location.disk.diskBackingInfo.deltaDiskFormat).
  
  
  2. Create a second-level clone from the first clone, such that the disk for the second-level clone is on a different datastore. If you do not specify seSparseFormat or redoLogFormat for the second-level clone delta disk format, the clone operation will fail.

  Using a virtual machine clone with a native delta disk format, you must specify either seSparseFormat or redoLogFormat for any clones that you create from the original native clone when the second-level clone is on a different datastore.

• Accuracy of VirtualDisk.capacityInKB property affected by mbralign tool - If you use the NetApp tool mbralign to align a virtual disk file (VMDK), the tool may produce a file, the size of which is not correctly represented by the vSphere API. If the disk size value is not evenly divisable by two, the Server rounds down the capacityInKB value.
• SetTaskState method - fault parameter is required when setting task error state. If you specify an error state when you call the SetTaskState method, you must also specify the fault parameter in the calling sequence.
• The seSparse virtual disk type is intended for internal use only (VirtualDiskType.seSparse).
• Performance counter documentation. The performance counter tables show the list of performance counters that are available. For some counters, the documentation is not complete.

Resolved Issues

• HTTP file transfer performance using a vCenter client connection has been improved. In vSphere 5.0, an HTTP file transfer initiated on a vCenter connection takes longer than the same file transfer initiated on an ESXi connection. This problem has been fixed for vSphere 5.5. The performance for HTTP transactions initiated on a vCenter connection is comparable to the performance on an ESXi connection.

Deprecations Summary

Several properties and types defined for the API have been deprecated as of vSphere API 5.5. This table lists each deprecated API element and identifies the new feature that takes its place, if there is one.