VMware vSphere Web Services SDK 4.0 Release Notes
Last updated: 23-Aug-2012
This release of the vSphere Web Services SDK has the following known issues:
- API Issues
- General Documentation Issues
- vSphere API Reference Documentation Issues
- Interoperability Issues
- Performance Statistics Issue
- vCenter Server 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
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.
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.deviceIdvalue 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
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
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
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
Anomalous PropertyCollector Behavior for RetrieveProperties When PropertyFilterSpec[ ] Contains Overlapping Managed Object Type Instances
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
- Clone operation -
- Relocate -
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 Developers 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 name||Other name that might still exist in documentation|
|vSphere API 4.0||VI API 4.0|
vSphere API (without a version number)
|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%.
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
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.
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
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 statesidle 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 does not support URLs at this time. Only datastore paths are supported:
Incomplete Descriptions of UUID Properties in the vSphere API Reference
uuid property of the
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
hostUuid properties of the
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
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
FindByUuid methods of the
SearchIndex managed object type return actual virtual machines only, and do not return templates. The other
SearchIndex methods, such as
FindChild, do work with templates. Include the template's complete filename extension (
.vmtx) when using the
Incorrect values for HostMultipathInfoLogicalUnit.policy
The API Reference shows incorrect values for the
policy property of the
HostMultipathInfoLogicalUnit data object. The correct values are
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 onlynot 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
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
moveAllDiskBackingsAndAllowSharing. Depending upon your specific use case, this disk type might be inappropriate. When creating a
VirtualMachineRelocateSpec (for use with
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.