vSphere Web Services SDK 4.1 Release Notes
Last updated: 20-Jan-2011
VMware vSphere 4.1
Release date: 13 Jul 2010
vSphere Web Services SDK Build 251329
This document contains the following information:
vSphere Web Services SDK 4.1 supports the new features of
vCenter Server and ESX/ESXi 4.1 systems.
For information about additions and changes to the vSphere API, see
What's New in vSphere API 4.1
Non-secure communication with a vSphere Client Plug-in - in vSphere 4.1, there is a
new XML element defined for the vSphere Client Plug-in configuration file.
<supportNonSecureCommunication> tag specifies a non-secure
HTTP connection between a vSphere Client and a plug-in Web server.
The vSphere Web Services SDK release 4.1 has the following known issues:
ESXi Performance metadata is available only from vCenter Server.|
On an ESXi Server, the
PerformanceManager defines a single performance interval that specifies
rollup data collection every 5 minutes. This ESXi performance interval metadata is available
from a vCenter Server in the
PerformanceManager.historicalInterval list of
When you retrieve the
historicalInterval property from an ESXi Server,
the ESXi Server returns an empty property.
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.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
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
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.
Discrepancy for virtual machine guest heartbeat status values - vCenter Server only.
For a client that connects to an ESX host, the guest heartbeat status for a virtual machine
on that host is correct (VirtualMachine.guestHeartbeatStatus). A client that connects
to a vCenter Server will see changing guest heartbeat status values for that same
virtual machine. The vCenter Server reports incorrect status values that cycle between
ManagedEntityStatus values of green and yellow or green and red. The value can change every
20 seconds. Currently, there is no workaround for this problem.
Duplicate data in performance counter database for certain counters - vCenter Server only.
Client applications that connect to a vCenter Server can see duplicate performance data
for some counters due to incorrect names. The vSphere statistics database contains duplicate data
for the memory counters |
swapout. The duplicate data
is identified by slightly different and incorrect names that use the wrong character case -
You may encounter this if you use the
QueryAvailablePerfMetrics method to obtain performance
counter identifiers. The method will return two different identifiers for the same (duplicate) data. Each
identifier is associated with a different name. You can also see duplicate data for these counters
PerfCounterInfo array for the
There are other counters that previously showed the same duplication. These have been
fixed in vSphere 4.1, however if you have a client that connects to an earlier version
you will see the duplication. This affects the following counters:
- CPU - reservedCapacity (incorrect counter name is reservedcapacity)
- Memory - reservedCapacity (incorrect counter name is reservedcapacity)
- ManagementAgent - swapin, swapout (incorrect counter names are swapIn and swapOut)
vSphere Web Services SDK sample program file SSPI.cpp does not compile
on the supported platforms (Microsoft Visual Studio 2005 and
Microsoft Visual Studio 2008).
The SDK sample SSPICIMClient requires the SSPI.dll file to perform
pass through authentication. For information about how to fix this, see
the VMware Knowledge Base article about the
SSPI.cpp sample file.
HA (High Availability) event |
HostDasOkEvent not generated.
When an HA error occurs on a host, the ESX Server generates the event
HostDasErrorEvent. The vSphere API Reference indicates that
the Server generates
HostDasOkEvent when the HA service
returns to its normal state, but the Server does not generate this event.
Virtual machine VMCI communication setting not propagated until restart.
You can set the |
property to control VMCI socket access, but any change to the property
will not take effect until the virtual machine is restarted.
WSDL incompatibility between 2.5 (and earlier) clients and
vCenter Server 4.0 (and later). When vCenter Server performs
a group power on, if there is more than one fault thrown per VM,
the Server generates a |
Pre-4.0 clients cannot handle this fault (the client will exit).
There is no workaround for this situation. The best solution is to upgrade
to vSphere client 4.0 or later.
|vSphere API Reference issues:|
You cannot remove an existing VirtualMachineConfigSpec.extraConfig option.
The description of the |
VirtualMachineConfigSpec.extraConfig property states that
you can remove an extra config option. The documentation is not correct. You can add a new option
and you can reset the value for an existing option. You cannot remove an existing option.
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.
API versions reference page not updated in the vSphere Web Services SDK
distribution. The vSphere API Reference contains a page that shows
which versions of the API support the various elements. The SDK distribution
contains the vSphere 4.0 version of that page; it does not show the elements
added for 4.1. You can see the 4.1 version on the API Versions Reference page
Context not identified for the |
DistributedVirtualSwitch objects are located in network
folders in the vSphere inventory. When you call the
method, you must provide a reference to a network folder. For more information
about inventory structure, see the description of the
ServiceInstance managed object in the vSphere API Reference.
DVPortgroupConfigSpec.type required for AddDVPortgroup_Task method.
You must specify a portgroup type when you add a portgroup
to a |
indicates that the
type property is optional.
Memory Counters - swapin.
The table in the vSphere API Reference shows an incorrect collection level for the |
counter. The correct level for the counter is 2.
API Behavior Changes
The features described on this page were available in the 4.0 release of the API,
but they function differently in the vSphere API 4.1.
Behavior Changes for vSphere 4.1 ESXi Servers
300 second sampled performance data is available only from a vCenter Server.
The vSphere Web Services SDK Programming Guide v4.1 describes the system-defined performance
interval for ESX/ESXi hosts. This performance interval specifies rollup data collection every
5 minutes. You cannot retrieve 5‐minute rollup data from an ESXi Server directly. You can use
a vCenter Server connection to obtain 5‐minute rollup data for an ESXi Server.
Behavior Changes for All vSphere 4.1 Servers
WaitForUpdates and CheckForUpdates methods deprecated.
have been deprecated in vSphere 4.1. Use the
method, which allows you to set a time limit to wait for a non-empty result
and to set a limit on the size of a single response.
CheckForUpdates method returns null to indicate no property updates.
CheckForUpdates method is documented as returning null
if there are no updates for the specified properties. In versions prior to vSphere 4.1,
CheckForUpdates returns an
UpdateSet object with a zero-length
filterSet update list. In 4.1, the method returns null, as documented.
If you have written code based on the original incorrect behavior, it will no longer work.
CheckForUpdates has been deprecated; use the
WaitOptions.maxWaitSeconds set to zero.
RetrieveProperties and RetrieveContents methods deprecated.
have been deprecated in vSphere 4.1. Use the
RetrieveContentsEx methods, which allow you to set a limit
on the size of a single response.
New property for PropertyFilterSpec data object.
In vSphere 4.1, the property
has been added to the
PropertyFilterSpec data object.
This affects filter creation (the
update sets (the
WaitForUpdatesEx method), and
the results of property retrieval (the
DistributedVirtualPortgroup - ESX and vCenter differentiation.
On ESX hosts, the ESX Server provides information about port groups
that are referenced by local virtual machines or the host service console.
This is a change from previous releases in which an ESX Server
provides information about all port groups associated
with the virtual distributed switch containing the relevant port group(s).
vCenter Server handling of port group representation has not changed.
A vCenter Server will provide information about all port groups in
all datacenters that it manages.
DVPortgroupConfigInfo for different port group types.
An ESX Server will provide complete |
only if the port group type (
ephemeral. For other port group types (
lateBinding), the configuration data only includes
the name and type of the port group. In previous releases, the Server
provides complete configuration data regardless of the port group type.
DistributedVirtualSwitch MoveDVPort_Task method.
When you move a distributed virtual port to another
DistributedVirtualPortgroup, a virtual machine
that uses the port will reconfigure its network
interface so that it is bound to the destination port group.
portConfigResetAtDisconnect default value.
The default value of |
DistributedVirtualSwitch performProductSpecOperation method.
Previously, the |
performProductSpecOperation method only
updated the Nexus 1000v
The method now also upgrades the version of the VMware virtual switch.
IPV6 stack enabled by default.
In ESX 4.1, the IPv6 stack is enabled by default. (Both IPv4 and IPv6
are enabled by default.) Previously, you had to enable IPv6 explicitly.
Host IPv6 addresses are not initialized.
The host network configuration data includes a list of
data objects describing the vNic adapters on the host.
This data includes IPv6 address properties for both
host and service console adapters.
Previously, the ESX Server used default values from the IPv6 stack
to initialize the IPv6 addresses. Now, the Server does not set
the properties. To retrieve the network addresses, use the
Database Size Estimates.
uses an updated algorithm to compute an estimated database size
based on a particular inventory description and performance interval.
Compared to output from the 4.0 algorithm, the current method produces
a different estimate for a particular set of input data.
Changed statistics levels for performance counters.
The following counters for the resource groups CPU and Memory have
different default levels for vSphere 4.1.
These counters have been deprecated.
|Resource Group||Counter||Old Level||New Level
Out-of-range handling (UpdateProgress method).
fault if you specified a
outside the range of 0..100. As of vSphere 4.0, the method
behavior changed so that it adjusted the percent done value
to the closest boundary. This change was not described
in the 4.0 documentation.
Behavior Changes for vSphere 4.1 vCenter Servers
Events and Tasks
Fault tolerance events - virtual machine name suffix for primary/secondary.
As of vSphere 4.1, event objects encode information that allows you
to distinguish events generated for a fault tolerance primary
virtual machine from those generated for its secondary. Events generated for
virtual machines include the
VmEventArgument object, which
includes the name of the virtual machine. In vSphere 4.1, if the event
corresponds to a primary virtual machine, the name includes the suffix "\p".
If the event corresponds to a secondary virtual machine, the name includes
the suffix "\s".
Filtering events for primary and secondary fault tolerance virtual machines.
You can filter events for a primary fault tolerance virtual machine and all
of its secondary fault tolerance virtual machines. When you call the
method, use the
property in the
EventFilterSpec data object to set the
EventFilterSpecByEntity fields. Set the
property to the primary fault tolerance virtual machine, and set the
recursion property to "all".
Event Manager processing.
Event Manager now processes new events in batches.
This change reduces the load on the repository and improves the scalability
of vCenter. Batch processing increases the interval before
availability. It may take up to 5 seconds before you can successfully
query for newly posted events (for example, using event collectors).
In previous releases, the Event Manager processed each event individually
and wrote it to the repository immediately. The event was available
immediately after the repository posting.
EVC-enabled clusters required for FT pairs.
In vSphere 4.0 and later, you must enable EVC (Enhanced vMotion Compatibility)
in a cluster to use DRS (Distributed Resource Scheduling) for FT (Fault Tolerance)
primary and secondary virtual machine pairs in that cluster. You must use
the vSphere Client to enable EVC for a cluster.
If EVC is not enabled, vCenter automatically creates overrides to disable DRS
for FT primary/secondary pairs in the cluster
ClusterConfigSpecEx.drsVmConfigSpec.info.enabled = "false").
Attempts to remove the overrides or to enable DRS operations will fail.
DRS override specification for secondary FT virtual machines not supported.
You can specify a DRS behavior override
for a primary FT virtual machine, but you cannot specify a DRS override
for a secondary FT virtual machine.
The secondary virtual machine will inherit whatever setting applies
to its primary virtual machine.
You configure a DRS override when you reconfigure cluster compute resources.
spec parameter to the
method is a
ClusterConfigSpecEx object. Among other
things, this object specifies the DRS behavior and configuration
for individual virtual machines.
is an array of
each of which corresponds to the virtual machine
identified by the
The array cannot contain DRS configuration information
ClusterDrsVmConfigInfo object) that refers to
a secondary virtual machine. The reconfigure method will throw the fault
In previous versions, it was possible to include an override for
a secondary if the configuration specification also disabled DRS
for the virtual machine.
Initial placement of virtual machines in EVC-enabled cluster.
If a cluster has EVC enabled, DRS can now initially place
FT primary virtual machines. In an EVC-enabled cluster, the DRS behavior
of a primary FT VM is governed by the following settings:
When you use the
- The override specified for the primary FT virtual machine.
The override applies to both the primary and its secondary virtual machine.
- If there is no override specified for the virtual machine, DRS uses
the cluster default behavior
DRS will treat a primary FT virtual machine as it does any other
virtual machine. Once the primary is powered on, vSphere Center
will attempt to place the secondary.
As in vSphere 4.0, when you use the
method to power on an FT virtual machine, DRS
attempts to find an initial placement for both the primary and
secondary virtual machines. If the attempt fails, vCenter
will attempt to place and power on only the primary FT virtual machine.
If it can power on the primary but not the secondary, it will then disable FT
for the virtual machine, and it will generate a config issue
alerting the user that it has taken this action.
See the description of the
DRS Load Balancing of Primary and Secondary FT Virtual Machines in an EVC-enabled Cluster
In an EVC-enabled cluster (Enhanced VMotion Compatability),
DRS (Distributed Resource Scheduling) can now load balance powered-on
primary and secondary FT virtual machines in the cluster.
The DRS behavior is governed by the DRS behavior setting for each
virtual machine. If there is no DRS override configured for
an FT virtual machine, DRS uses the cluster default.
Disabling High Availability with active FT hosts in a cluster.
In vSphere 4.1, you can disable HA (High Availability) in a cluster while there are
FT virtual machines registered on hosts in the cluster. To disable HA for a cluster, set
and specify the cluster configuration specification in a call to
While HA is disabled, powered on FT virtual machines will continue
to run, but HA will not restart any virtual machines after a failure.
When HA is disabled, the following operations are not supported
on FT virtual machines:
- Turn on FT (
- Enable FT (
- Power on an FT virtual machine (
- Test failover and test secondary restart
You cannot disconnect a host if only one virtual machine
of an FT pair is registered to the host.
If a host has FT virtual machines on it, the following conditions
must exist before you can disconnect the host
- The host must be in maintenance mode (existing behavior).
- Any primary FT virtual machines registered to the host must have
their corresponding secondary virtual machines also registered to the
- Any secondary FT virtual machines registered to the host must have
their corresponding primary virtual machines also registered to the
HA override for secondary virtual machines not supported.
You cannot specify HA (High Availability)override behavior for secondary
virtual machines when you reconfigure cluster compute resources.
However, as in vSphere 4.0, an override specified for a primary virtual machine
will apply to its secondary as well.
spec parameter to the
method is a
ClusterConfigSpecEx object. Among other
things, this object specifies high availability
behavior and configuration for individual virtual machines.
contains an array of
each of which provides access to a virtual machine
The array cannot contain HA configuration information
that refers to a secondary virtual machine.
The reconfigure method will throw the fault
In previous versions, it was possible to include an override
for a secondary, but the override was ignored.
Powering On Virtual Machines - InsufficientResourcesException fault.
DRS now checks for the number of network ports available on the host
while powering on virtual machines. Before this, DRS would power on
virtual machines even if there were too few network ports to accomodate them.
DRS now tracks the number of network ports, and will throw
the fault |
if there are too few network ports.
VirtualMachine.runtime.memoryOverhead property updated every 10 minutes.
VirtualMachine.runtime.memoryOverhead property is now updated
every 10 minutes instead of every 20 seconds. This is for scalability reasons.
If you want to see changes more quickly, use the
statistic that is available as one of the Performance Manager memory counters.
Saving ResourcePool.runtime.memory data.
By default, the |
are no longer saved to the database for performance reasons.
If you want to read these values directly from the database,
you can direct the Server to store them in the database
by setting the value
True in the file
You must restart the vpxd daemon for the updated configuration
to take effect.
Generating a new UUID for a virtual machine.
You can generate a new UUID for a virtual machine when you
reconfigure the virtual machine.
Specify an empty string for the |
property of the
object when you call the
Virtual Center will generate a new instance UUID
for the virtual machine.
Profile.export (new privilege)
exportProfile method requires the privilege
Several properties and types defined for the API have been deprecated in vSphere 4.1.
This table lists each deprecated API element and identifies the new feature that
takes its place.
|Name of deprecated type, method, or property
||As of vSphere API 4.1, use instead...|
|Data Object Properties
PerformanceManager memory overhead counter