vSphere Web Services SDK 6.0 Release Notes

Released 12 MAR 2015

Release notes updated 10 AUG 2015

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

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-6.0.0-2561048.zip
    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 6.0?" (This is the second large section on the page).

Behavior Changes

  • The vSphere Management SDK now supports Java version 8.

Known Issues

The following section describes the known issues for the vSphere Web Services SDK in release 6.0.

  • Java version 6 incompatible with Web Services SDK version 6.0.

    You must install Java version 7 or greater to interface with the Web Services API in vSphere 6.0. Java 6 produces an UnsupportedClassVersionError when your client attempts to connect.

  • VVol destination disk type defaults to thick.

    When using the vSphere Web Services API to migrate or clone a virtual machine to a VVol datastore, the default provisioning type for a virtual disk is thick. Some vendors do not support thick VVol provisioning.

    To work around this issue, use one of the following options:

    1. Use the 6.0 vSphere Web Client to format the VM, so you can set the provisioning to ‘Thin’.
    2. If the destination disk is a flat disk, use the vSphere Web Services API to specify a VirtualDiskFlatVer2BackingInfo data object for the diskBackingInfo property of the VirtualMachineRelocateSpecDiskLocator data object in the array at VirtualMachineRelocateSpec.disk, and set the thinProvisioned property to true.

  • FindByDnsName case sensitivity.

    The FindByDnsName operation expects a dnsName argument to specify a target domain name. For requests to vCenter Server, the argument value is case insensitive. For requests to ESX hosts, the argument value is case sensitive.

  • Java samples for guest operations failure

    You may see the following error when you run the Java samples for guest operations. The samples are in SDK/vsphere-ws/java/JAXWS/samples/com/vmware/guest/.
    ERROR: The guest operations agent is out of date.

    If you encounter this error, update the virtual machine to a more recent version of VMware Tools.

  • HTTP file download performance.

    HTTP file download performance using a vCenter client connection takes longer than the same file transfer using an ESXi connection. A similar issue with HTTP file upload has been resolved.

  • 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.

  • Java sample warnings

    Some Java sample programs generate security policy warnings when you run them with JDK 1.7 or higher.

    Use the following steps to suppress the runtime warnings:

    • 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

    Documentation Issues

    • VirtualMachine.CloneVM_Task method failure

      When the VirtualMachine.CloneVM_Task method fails, it produces the following error,"The specified delta disk format 'nativeFormat' is not supported." The vCenter Server returns this error in the following situations:

      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.

      If you are 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.

    • The fault parameter is required when setting the SetTaskState method

      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)

      The documentation does not specify internal use only.

    • Performance counter documentation table incomplete

      The performance counter tables show the list of performance counters that are available. For some counters, the documentation is not complete.

    Resolved Issues

    • SSO URL change - Java samples login failure has been fixed

      The samples have been updated to use the new Single Sign On Service URL.

    • OVF Manager sample failure has been fixed

      The following OVF Manager samples execute correctly. These files are located in:
      SDK/vsphere-ws/java/JAXWS/samples/com/vmware/vapp/.

      • OVFManagerExportVAPP.java
      • OVFManagerExportVMDK.java
      • OVFManagerImportLocalVApp.java

    • The delta disk format conversion failure during Storage vMotion has been fixed

      You can use vMotion to convert a linked clone with a delta disk format of seSparseFormat or redoLogFormat to a native snapshot.

    • HTTP file upload performance using a vCenter client connection has been improved

      In vSphere 5.0, an HTTP file upload 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 upload transactions initiated on a vCenter connection is comparable to the performance on an ESXi connection.

      There is still an issue with HTTP download performance using a vCenter client connection.

    Miscellaneous

    • Need to specify vCenter Single Sign-On URL for some configurations

      The vSphere 6.0 release introduces a Platform Services Controller that can run on the same host as the vCenter Server, or can be configured on a separate host. At this time, the two possible configurations are:

      1. vCenter Server with an embedded Platform Services Controller (vCenter Single Sign-On Server, Lookup Service Server,...). This is like traditional vSphere deployments.
      2. vCenter Server with an external Platform Services Controller.

      You will have to provide the vCenter Single Sign-On URL explicitly in order to run samples with the second configuration. With the first configuration, there is no need to provide the vCenter Single Sign-On URL (since the vCenter Single Sign-On service is embedded in the management node) and our SDK will continue to work as before.

      The SDK samples have always had the option to explicitly specify the vCenter Single Sign-On URL (whether the vCenter Single Sign-On service is running inside or outside the management node). This is useful in cases where the vCenter Single Sign-On service is deployed outside the vSphere management node like the second configuration above.

      When you log in to a vCenter Single Sign-On Server, you must be in a domain that has been added as a vCenter Single Sign-On identity source. If that domain is not the default domain, you must include the domain name as part of your user name, such as, [email protected]. To learn more about configuring the vCenter Single Sign-On Server, see vSphere Security.

    • Axis samples removed

      The vSphere Web Services SDK no longer provides libraries or samples based on the Axis Web Services toolkit. As of vSphere 5.1, the SDK provides libraries and samples based on the JAX-WS toolkit.

    Deprecations Table

    Several properties and types defined for the API have been deprecated as of vSphere API 6.0. You can see all of the objects, methods, and parameters with indicators to show when they were added and/or deprecated by reviewing the API Versions Reference table in the vSphere Web Services API Reference.