vSphere Web Services SDK 6.5 Release Notes

vSphere Web Services SDK 6.5 | 15 NOV 2016 | Build 4571253

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

This document contains the following information:

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.5.0-4237422.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.5?"

Behavior Changes

  • The vSphere Management SDK now supports Java version 8. Note: The SDK samples now require Java version 8.

Known Issues

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

  • Java samples unable to connect to server

    If you run Java samples in a JDK 7 environment, the samples will be unable to connect to vSphere services. The samples report the following error:

    ERROR: could not connect: login fault : Remote host closed connection during handshake

    The error results from a transport encryption mismatch. In the vSphere 6.5 release, vSphere services run with enhanced security, using TLS 1.2. JDK 1.7 does not support the stronger version of TLS.

    To run the samples, you must install JDK 1.8, which supports TLS 1.2. After you install JDK 1.8, set the JAVA_HOME environment variable to the location of JDK 8 on your system.

    If you are unable to install JDK 1.8, download and install build 4240471 of ESXi and build 4240472 of vCenter Server, which use the older TLS protocols.

  • .NET samples unable to connect to server

    If you run .NET samples without modification, the samples cannot connect to vSphere services. The samples report the following error:

    System.Net.WebException: The underlying connection was closed: An unexpected error occurred on a send. --->
System.IO.IOException: Authentication failed because the remote party has closed the transport stream.

    The error results from a transport encryption mismatch. In the vSphere 6.5 release, vSphere services run with enhanced security, using TLS 1.2. The .NET samples do not support the stronger version of TLS.

    To run the samples, you must make the following changes to support TLS 1.2:

    1. Install Visual Studio 2012 or newer.
    2. Open the solution file and upgrade it to the 2012 or newer version of Visual Studo.
    3. Change the .NET framework target of the sample project from 3.5 to 4.5. Version 3.5 does not support TLS1.2.
    4. Edit the file SvcConnection.cs in the AppUtil project as follows:
      1. Find the lines that retrieve the ServiceContent: 
        _sic = _service.RetrieveServiceContent(_svcRef);
        This statement occurs on lines 88, 113, 151, and 265 of SvcConnection.cs.
      2. Before each line that retrieves the ServiceContent, add the following line: 
        System.Net.ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;
        This line enables the sample to negotiate a TLS 1.2 connection with the server.
    5. Rebuild the AppUtil project.
    6. Rebuild the sample projects.

    If you are unable to install .NET 2012 or newer, download and install build 4240471 of ESXi and build 4240472 of vCenter Server, which use the older TLS protocols.

  • Visual Studio 2015 not supported for building C# DLLs.

    When you compile the C# DLLs for the Web Services API, you must use Visual Studio 2012 or 2013. Visual Studio 2015 is not supported for this purpose because it runs out of stack space while building the DLLs.

  • .NET samples fail to access vCenter Server by using an IPv6 address

    If you use an IPv6 address to access the vCenter Server system, the samples fail to connect to the vSphere services and the following error is logged:

    System.ServiceModel.EndpointNotFoundException: There was no endpoint listening at https://[fd01:0:101:2605:0:a:0:1a61]/sts/STSService that could accept the message. This is often caused by an incorrect address or SOAP action. See InnerException, if present, for more details. ---> System.Net.WebException: The remote server returned an error: (503) Server Unavailable.

    Workaround: Use an FQDN to access the vSphere services when running the .NET samples.

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

  • 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
  • SSO incompatible with vSphere 5.5

    The sample programs are unable to connect to vSphere 5.5 by default Changes in the samples to take advantage of newer behavior in vCenter Single Sign-On result in an incompatibility with vSphere 5.5 endpoints when authenticating with vCenter Single Sign-On. By default, the samples try to authenticate using vCenter Single Sign-On.

    Workaround: Authenticate with local credentials by supplying the command-line argument --basic-connection to the sample programs.

  • Disk chains of managed virtual disks not fully supported.

    In this release, vSphere does not fully support managed virtual disk chains.

    • When you delete a managed virtual disk chain, only the leaf disk file is deleted. The leaf disk is the last child disk in the chain, while the base disk is the earliest parent in the chain.

    • If your application manages disk chains that span datastores, the application must maintain its own mapping between child disks and datastores. You need the mapping to delete the entire disk chain correctly.

    • If your application manages disk chains that span datastores, certain situations can cause disk IDs to behave unexpectedly. vSphere maintains an association between disk ID and the file path of the leaf disk. When a child disk is created, the file path for the ID in the managed virtual disk inventory is updated to point to the newly created leaf disk.

      If you subsequently use an API method to reconcile a different datastore inventory that contains the base disk of the chain, or one of the parent disks in the interior of the chain, vSphere creates another association of the disk ID that points to the parent disk on that datastore. If you reconcile all datastores, vSphere creates another association with the disk ID for each datastore that backs the chain. For this reason, your application needs to keep track of the datastores, especially the datastore that contains the leaf disk of the chain.

    Workaround: To avoid creating duplicate disk ID associations for a chain of managed virtual disks, use a single datastore as a backing resource for all disks in a chain.

    If you already have a chain that spans multiple datastores, you can create a copy of the chain on a single datastore by using the CloneVStorageObject_Task() method of the VMware Web Services API. The parameters to the clone method must supply the datastore of the leaf disk as the source datastore. The datastore parameter resolves any ambiguity with the disk ID associations.

    If you need to verify the properties of a managed virtual disk ID, the associated datastore is uniquely identified by the property RetrieveVstorageObject().config.backing.datastore.summary.url, and the associated virtual disk file is located by the property RetrieveVstorageObject().config.backing.filePath.

    After you clone the disk chain, you can delete the old chain that spanned datastores. Deleting a managed virtual disk chain is described in the KB article 2147767.

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.

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

Resolved Issues

  • vCenter Server was ignoring group parameter in RetrieveUserGroups call.

    In earlier vSphere releases, the vCenter Server failed to return results in the belongsToGroup and belongsToUser parameters, as documented for the UserDirectory::RetrieveUserGroups API. This was fixed in the vSphere 6.5 release. Item added 6 FEB 2019.

  • VVol destination disk type defaulted 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 was thick. Some vendors do not support thick VVol provisioning.

    This problem has been corrected. The destination disk type now defaults to thin.

  • .NET sample build simplified.

    The procedure for building DLLs and samples for .NET applications has been simplified. The former procedure was tedious and error-prone. The new procedure is much easier to use.

Deprecations

Several properties and types defined for the API have been deprecated as of vSphere API 6.5. 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.