VMware Infrastructure (VI) SDK 2.0.1 Release Notes

Known Issues

This release of the VI SDK has the following issues.

• Compatibility Issues with SDK 1.x
• Sample Code, Performance Issues
• Errors and Exception Issues
• API and Object Model Issues

Sample Code, Performance Issues

• Sample Code May Have Limited Scope and Purpose. The sample applications included in the SDK do not always use the most recent APIs. Furthermore, some of the samples do not follow best practices.
  
  
• C# “Wrapper” Samples Perform Poorly. The C# wrapper samples (located in the \samples_2_0\DotNet\wrapper sub-directory of the SDK 2.0.1 package) make a round trip to the server for every method invocation, which can result in unacceptably poor performance. For best results, do not use these samples, and be careful when using this particular design pattern. For applications that require frequent access to a large number of objects or properties, use the PropertyCollector managed object type, which retrieves in batch mode, thus reducing round trips to the server. See Appendix A in the Getting Started Guide for a PropertyCollector tutorial.
  
  
• The C# (.NET) Samples Have Performance Issues Related to .NET Serialization. Generating the serialization code for the C# samples can take a long time. See KB 87402 for more information, and to obtain a patch for the Microsoft Visual Studio 2005 environment.
  
  
• Performance Issue (for VI SDK 2.0) with JDK Versions Prior to JDK 1.5.0_08. Using JDKs older than JDK 1.5.0_08 results in a significant performance degradation, when obtaining a Managed Object Reference to a virtual machine. See KB 2983901 for more information.
  
  

Errors or Exceptions Issues

• Creating a Virtual Machine May Throw Incorrect Exceptions. Incorrect exceptions might be thrown when you create a virtual machine, as shown in this table. The table lists error condition category, the exception that is expected to be thrown, and the exception actually thrown.
  
  

  Condition	Expected	Thrown
  Create a virtual machine with the controller key is set to 0.	InvalidDeviceSpec	MissingController
  Create a virtual machine with a device that is a virtual disk but the capacity is not set.	InvalidDeviceSpec	com.vmware.vc.VimFault
  Create a virtual machine with a device that is an Ethernet card disk but the Mac address is not set.	InvalidDeviceSpec	No exception thrown. The createVM task succeeds.
  Create a virtual machine with a device that is a Virtual Controller but the bus number is not set.	InvalidDeviceSpec	No exception thrown. The createVM task succeeds.
  Create a virtual machine with a device that is a virtual disk and the file operation is set to “replace.”	InvalidDeviceSpec	com.vmware.vc.VimFault

  
  
• CreateFilter Operation Throws a SystemError Exception  The CreateFilter operation throws a SystemError fault if its PropertyFilterSpec contains a PropertySpec with an incorrect property path in the pathSet property. An incorrect path is one that is not defined for the managed object type specified by the PropertySpec’s type property. You can correct the problem by fixing the incorrect PropertySpec.

API or Object Model Issues

• Client applications must access an ESX Server 2.x host system through a VirtualCenter Server 2.x system. In addition, ESX Server 3 introduces new API and object types that are not fully supported on ESX Server 2.x systems. Any non-supported features return “not supported.” For example, host configuration (HostSystem.ConfigManager.ConfigInfo) and related properties, such as multipathInfo, is not supported on ESX Server 2.x systems.
• CustomizationPassword data object does not support “false” as the value for the plaintext property. Do not set plaintext = false.
• When you add a device to a virtual machine, use a negative integer for the key property of the VirtualDevice data object to avoid conflicts with existing device keys. When adding multiple devices to a virtual machine, requirements for uniqueness vary by version number, as follows:
  • ESX Server 2.5 hosts require a unique key for each device.
  • ESX Server 3.0 hosts do not require a unique key.
• The RescanHba and RescanAllHba operations on the HostStorageSystem managed object in the VMware Infrastructure SDK return a Boolean value that indicates whether a new LUN was detected during the rescan. This Boolean does not report properly whether a new LUN was detected during the rescan.
• An error might result if you add a host to a VMware HA cluster from which the host had been removed previously. As a workaround:
  1. Disable HA on the cluster using ReconfigureCluster().
  2. Let all the "Config/Unconfigure HA on host" tasks complete.
  3. Re-enable HA on the cluster using ReconfigureCluster().
  4. Let all the "Config/Unconfigure HA on host" tasks complete.
  The tasks should now complete successfully.
• When using findByDatastorePath to search for a virtual machine, you must provide both a datastore name and path. For example, providing [MyDatastore]/MyVirtualMachines as a path returns the expected results, but simply using []/vmfs/volumes/MyDatastore/MyVirtualMachines/ does not. This is true even though an empty datastore name can be part of a valid datastore path. An empty datastore name can be part of a valid datastore path only if its host context is known, since an empty datastore name indicates the local path on a particular host.
• A CreateSnapshot_task works on a virtual machine associated with a host on an ESX 2.5 server only if there is no existing snapshot. Furthermore, the virtual machine must be powered-on, have no spaces in its name, and have only disks in persistent mode. If there is an existing snapshot, RemoveSnapshot must be invoked before CreateSnapshot is used again. Otherwise a MultipleSnapshotsNotSupported fault occurs.
• Entering values for a managed object might produce unexpected indirectRemove calls. When you do not specify an object property, the value for that property in the object is set to null. For example, this happens when a new managed object is created and optional values are left unspecified. Users might expect that when creating an object for the first time, there is nothing to remove, but the indirectRemove call is used to ensure that the unset optional values have a null value.