VMware vSphere Web Services SDK 4.0 Release Notes

Last updated:   23-Aug-2012

release notes   |   Known Issues   |   Deprecations   |   Behavior Changes

Known Issues

This release of the vSphere Web Services SDK has the following known issues:

API Issues

Host health system data not updated automatically.
In vCenter 4.0, host health system data that is available through vSphere API methods is not updated automatically. This is due to performance bottlenecks encountered when synchronizing the information in vCenter Server. Use the RefreshHealthStatusSystem method to update runtime host health information and then use the appropriate methods to retrieve the most recent data.

Certain PCI device properties might be represented as negative values.
The following HostPciDevice properties might be represented as negative values:


A vSphere Server uses an unsigned short integer to represent PCI device and vendor identifiers. The WSDL representation of the identifier is a signed short integer. If the identifier is greater than 32767, the Server will convert it to its two's complement for the WSDL representation.

  • When you specify a PCI device ID for a virtual machine (VirtualPCIPassthroughDeviceBackingInfo.deviceId), you must use the HostPciDevice.deviceId value as retrieved and convert it to a string.
  • When you specify a PCI vendor ID for a virtual machine (VirtualPCIPassthroughDeviceBackingInfo.vendorId), you must use the retrieved HostPciDevice.vendorId value.

EventFilterSpec properties type and eventTypeID do not work - ESX Server only.
For a client that is connected to a vCenter Server, event filtering based on the event type works correctly. For client that is connected to an ESX host, event filtering using the type or eventTypeID properties does not work.

ResignatureUnresolvedVmfsVolume_Task method returns invalid reference - vCenter Server only.
For a client that connects to an ESX host, the ResignatureUnresolvedVmfsVolume_Task method returns a valid managed object reference to the resolved datastore (the HostResignatureRescanResult.result property). For a client that is connected to a vCenter Server, the method returns an invalid reference. The vCenter Server client cannot use this reference and there is no workaround for this problem.

Linux virtual machines - Guest representation of disk data limited to boot partition.
The VirtualMachine.guest.disk property is an array of GuestDiskInfo data objects. The GuestDiskInfo objects provide information about virtual disks available to the guest operating system. On a Linux virtual machine, the disk information represents only the boot partition. It does not display information about any other partitions that may be configured. This will be fixed in a future release.

RemoveSnapshot_Task Operation Does Not Currently Support Removal of Entire Tree When VirtualMachineSnapshot Has Independent Disks
For a VirtualMachineSnapshot that has independent disks and a number of child snapshots associated with it, attempting to remove the child snapshots by setting the removeChildren property to true fails and raises a SystemError (“concurrent access”) error message.
To avoid this issue, remove each snapshot individually. Use RemoveSnapshot_Task with the removeChildren property set to false.

Anomalous PropertyCollector Behavior for RetrieveProperties When PropertyFilterSpec[ ] Contains Overlapping Managed Object Type Instances
When the PropertyFilterSpec[] passed to the RetrieveProperties operation includes PropertyFilterSpec definitions that select managed objects of the same type, the properties associated with the managed object type by the first PropertyFilterSpec in the array override the values of any subsequent PropertyFilterSpec objects used in the same call.
To avoid this issue, define a PropertyFilterSpec for the array containing every ObjectSpec and every PropertySpec for all the properties you want to obtain.

Certain VirtualMachineRelocateDiskMoveOptions Constants Inflate Delta Disk During Clone or Relocate Operations
If you invoke a clone or relocate operation on a virtual machine that has virtual disks with parent backings, such as a linked virtual machines or a virtual machine with snapshots, the operation might expand the delta disks to their maximum size in certain cases. The issue has been observed with the following VirtualMachineRelocateDiskMoveOptions.diskMoveType values.

  • Clone operation - moveAllDiskBackingsAndAllowSharing, moveChildMostDiskBacking
  • Relocate - moveAllDiskBackingsAndAllowSharing, moveAllDiskBackingsAndDisallowSharing, moveChildMostDiskBacking

Relocating a virtual machine with snapshots to a different datastore with the source and destination datastore both visible to at least one host also inflates the delta disks.

To avoid this issue, do not a relocate virtual machine configured as mentioned above unless needed. If you must relocate, create the parent and delta backings on a datastore and relocate to a second datastore such that the source and destination datastore are not both visible to any host in the datacenter . Any transport, including FC, iSCSI, block, parallel is fine as long as the source and destination datastore cannot both be seen by any host.

General Documentation Issues

The most recent documentation is available from the vSphere Web Services SDK documentation home page at http://www.vmware.com/support/developer/vc-sdk/index.html

SDK Package Readme Files Are Inaccurate   The readme files included in the SDK package do not contain current information. See the Developer’s Setup Guide for information about setting up your development environment for C# or Java.

Legacy Product Names Might Exist in API Reference and Other SDK Documentation:   This release of the SDK includes many product name changes. Some legacy product names might still exist in the documentation.

New nameOther name that might still exist in documentation
vSphere API 4.0VI API 4.0
vSphere API (without a version number)
API 4.0
vSphere Web Services SDK VMware Infrastructure SDK
vCenter Server VirtualCenter Server

Do not use Microsoft VisualStudio 2003 or Microsoft .NET 1.x Tools for .NET Samples.
The documentation for the vSphere Web Services SDK 4.0 might include information about legacy Microsoft programming tools, such as Microsoft VisualStudio 2003. The SDK requires Microsoft .NET 2.0 (or subsequent release) and more recent programming environments such as Microsoft VisualStudio 2005. Do not use Microsoft .NET 1.x or Microsoft VisualStudio 2003 (or previous releases).

Memory Statistic usage Counter Does Not Apply to Resource Pools
As of VirtualCenter Server 2.5U2, the memory counter for usage no longer applies to resource pool consumption. Results using this metric in releases prior to VirtualCenter Server 2.5U2 were not meaningful. For example, the VI Client would display memory usage for a resource pool at values well over 100%. However, the usage counter is still identified in the PerformanceManager  > Memory Counters page of the vSphere API Reference as applicable to ResourcePool. This information is not correct. Memory usage for a resource pool as a percent of available memory cannot be properly calculated because, by design, a resource pool does not have a non-varying maximum.

Information on diskMoveType for Storage VMotion not accurate.
VirtualMachineRelocateSpec in the SDK Programming Guide describes the diskMoveType property for Storage VMotion. However, diskMoveType are only relevant in conjunction with linked clones not currently used in conjunction with Storage VMotion. If you attempt to migrate a virtual machine using Storage VMotion, and if a disk backing with a parent is found( either because the virtual machine has snapshots or because it is a linked clone) the following error is thrown:
The virtual machine has virtual disk in link-cloned mode that prevents migration

vSphere API Reference Documentation Issues

Memory usage counter expressed as hundredth of a percent.
The document incorrectly states that memory usage is a percentage of the total configured or available memory. The usage counter value is expressed as a hundredth of a percent (1 = 0.01%), using a value between 0 and 10,000.

Different Path Formats for vCenter Server and ESX/ESXi systems in HostDatastoreBrowserSearchResults.
The file property of HostDatastoreBrowserSearchResults is defined as an array of FileInfo data objects. The path property of a FileInfo data from a vCenter Server includes a trailing forward-slash (/). This same property from an ESX/ESXi host does not. These details are not clear in the vSphere API Reference. If your client application targets both ESX/ESXi and vCenter Server systems, and you want to present results from either server type consistently, remove the trailing slash.

CPU Wait Time Counter Description Inaccurate in the vSphere API Reference
The PerformanceManager managed object type as described in the vSphere API Reference is incorrect. The wait counter captures total time (in milliseconds) spent in any of the possible idle states—idle state, wait state, or halted state.

FileManager Documentation Inaccurate in the vSphere API Reference
The vSphere API Reference provides documentation for using URLs with FileManager. However, FileManager does not support URLs at this time. Only datastore paths are supported:

Incomplete Descriptions of UUID Properties in the vSphere API Reference
The uuid property of the HostSystemInfo, HostHardwareSummary, VirtualMachineConfigSummary, VmUuidAssignedEvent, VmUuidConflictEvent, and VmUuidChangedEvent data objects lack information for the UUID format. They use 128-bit SMBIOS UUID represented as a hexadecimal string in a 12345678-abcd-1234-cdef-123456789abc format. The same format is used for the bundleUuid and hostUuid properties of the MismatchedBundle fault.

Ambiguous Description of ResourceAllocationInfo Property in the vSphere API Reference
In the vSphere API Reference, the description of the ResourceAllocationInfo data object shares property is ambiguous. The corrected description is "Optional. Relative allocation of resources that can be used to arbitrate resource contention. Shares are used to determine relative allocation between resource consumers."

Incorrect Description of FileManager Methods in the vSphere API Reference
The descriptions of CopyDatastoreFile_Task, DeleteDatastoreFile_Task, and MoveDatastoreFile_Task in the vSphere API Reference state that these methods do not support recursive folder operations, which is not true for VI SDK 2.5. CopyDatastoreFile_Task supports recursive folder copy, DeleteDatastoreFile_Task supports recursive folder delete operations, and MoveDatastoreFile_Task supports recursive folder move operations.

Inaccurate Description of SearchDatastoreSubFolders_Task Return Value in the vSphere API Reference
In the vSphere API Reference, the description of the ManagedObjectReference to a Task return value for the SearchDatastoreSubFolders_Task method is inaccurate. The corrected description is "This method returns a Task object with which to monitor the operation. The info.result property in the Task object contains the list of HostDatastoreBrowserSearchResults upon success."

Some SearchIndex Methods Do Not Return Templates
The FindByDnsName, FindByIp, and FindByUuid methods of the SearchIndex managed object type return actual virtual machines only, and do not return templates. The other SearchIndex methods, such as FindByDatastorePath, FindByInventoryPath, and FindChild, do work with templates. Include the template's complete filename extension (.vmtx) when using the FindByDatastorePath method.

Incorrect values for HostMultipathInfoLogicalUnit.policy
The API Reference shows incorrect values for the policy property of the HostMultipathInfoLogicalUnit data object. The correct values are VMW_PSP_MRU, VMW_PSP_RR, and VMW_PSP_FIXED.

Interoperability Issues

Scripts and client applications written using previous versions of the API may fail (raising “HostConnectFault” error) when adding hosts to vCenter Server [fresh install only].
By default, vCenter Server 4.0 (fresh installs only—not upgrades) verifies the SSL thumbprint of each host being added to the system. Client applications and scripts must provide an SSL thumbprint when adding hosts to vCenter Server 4.0 systems. Support for SSL thumbprints was introduced in VI API 2.5. If your client application or script was written using VI API 2.0, you must modify the client using API 2.5 (or subsequent API version), or disable the SSL thumbprint verification process on server.

vCenter Server Issues

vCenter Server Does Not Handle Errors Properly for diskMoveType Property of VirtualMachineRelocateSpec
The diskMoveType property of the VirtualMachineRelocateSpec data object must contain one of the VirtualMachineRelocateDiskMoveOptions enumerations. If you set the value of diskMoveType to anything other than one of these enumerations, the vCenter Server does not notify you of the error and instead, might set the diskMoveType to moveAllDiskBackingsAndAllowSharing. Depending upon your specific use case, this disk type might be inappropriate. When creating a VirtualMachineRelocateSpec (for use with CloneVM_Task or RelocateVM_Task operations) set the diskMoveType to the proper value from the VirtualMachineDiskMoveOptions enumerated type.
See the vSphere API ReferenceGuide for information about the VirtualMachineRelocateDiskMoveOptions enumerated type.

Performance Statistics Issue

Incorrect Value Returned for Non-existent Performance Metrics
If a performance metric for a specific time interval is non-existent or unavailable, its value is returned as -1 (rather than a null or unset value). A metric might be unavailable or non-existent for a number of reasons, such as hostd or vCenter Server is inoperative; the statistic was not collected; or the metric is not applicable for the specified time period. For example, metrics for a virtual machine are not collected when a virtual machine is powered off. Network metrics are not collected if the network adapter is disabled, and so on.