VMware vCloud Suite SDK for .NET 6.0 Release Notes

Released 12 MAR 2015

 

This document contains the following sections:

Overview

This SDK provides programmatic access to new features introduced in vSphere 6.0 and existing features that did not have a public API prior to the vSphere 6.0 release. Access to existing features is exposed through the vSphere Web Services API. The vCloud Suite SDK for .NET also contains samples that demonstrate how the libraries work with other vSphere APIs.

The version 6.0 SDK enables programmatic access to the following services:

  • Service discovery using Lookup Service
  • Authentication (Single Sign-On)
  • Session management
  • Tagging
  • Content Library

Note:  Single Sign-On authentication is available through the VMware vCenter Single Sign-On API. Service discovery is available through the Lookup Service API.

Distribution Kit

When you extract the contents of the vCloud Suite SDK for .NET distribution kit, the files are placed in the VMware-vCloud-Suite-SDK-.Net directory:

    VMware-vCloud-Suite-SDK-.NET/
        client/
        docs/
        open_source_license.txt
        SDK-EULA.txt
        vCloud-Suite-SDK-.NET-README.html

You can download the vCloud Suite SDK for .NET distribution kit from the VMware Developer Center.

Known Issues

The following issues were discovered during testing.

  • Internal Server Error if Tagging Description Field is Empty

    The Tag Category Description field is optional in the vSphere Web Services API, but it is mandatory in the vCloud Suite SDK. Therefore, if the description field is empty, the vCloud Suite SDK can return an internal server error that states, "the ‘description’ field of the Category model is empty".

    Workaround:

    When creating tags, do not leave the description field empty. If you do not have any description, you may add a whitespace character (i.e. space).

  • Unauthenticated exception following long-running operation

    After an API client completes a long-running operation, such as an upload to the content library, the next operation might fail with an "Unauthenticated exception" message. This happens if the long running operation did not complete within the lifetime of the authentication session.

    Workarounds:

  • Keep the session alive by issuing short operations on another thread until the long running operation completes.
  • Increase the session length using the VMware vSphere Web Client. Select Administration > System Configuration > Services > vAPI Endpoint > Manage > General, and increase the value for the Maximum session idle time.

  • Certificate Validation

    The samples in the vCloud Suite SDK for .NET do not enable certificate validation for service endpoints by default. This is suitable for development environments, but for production environments you should modify the samples to perform certificate validation.

    To enable certificate validation in a .NET client, you must first import the server certificate into the Windows Trusted Root Certification Authorities certificate store, then add a validation callback to validate certificate properties.

    1. Use a Web browser connected to the service endpoint to download the certificate chain from the server. The result is a ZIP file containing all root certificates in the VMware Endpoint Certificate Store (VECS).
    2. Extract the contents of the ZIP file and import the certificates into the certificate store on the client machine. For more information about importing certificates, see http://windows.microsoft.com/en-us/windows/import-export-certificates-private-keys.
    3. Add the following validation callback method to your client code: 

      using System;
using System.Net;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;
// certificate validation callback.
private static bool Validate(object sender, X509Certificate certificate,
                             X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
  var result = true;
  if (sslPolicyErrors == SslPolicyErrors.None) {return result;}
  if ((sslPolicyErrors & SslPolicyErrors.RemoteCertificateNameMismatch) != 0)
  { 
    Console.WriteLine("SSL policy error {0}. " +
                      "The client may be using an incorrect server host name.",
                      SslPolicyErrors.RemoteCertificateNameMismatch);
    result = false;
  }
  if ((sslPolicyErrors & SslPolicyErrors.RemoteCertificateChainErrors) != 0)
  {
    var chainStatusList = new List<string>();
    if (chain != null && chain.ChainStatus != null)
    {
      foreach (var status in chain.ChainStatus)
      {
        if (certificate.Subject == certificate.Issuer)
        { // Self-signed cert with untrusted root is valid.
          continue;
        }
        chainStatusList.Add(status.Status.ToString());
      }
    }
    if (chainStatusList.Count > 0)
    {
      Console.WriteLine("SSL policy error {0}. Fix the following errors: {1}",
                        SslPolicyErrors.RemoteCertificateChainErrors,
                        string.Join(", ", chainStatusList));
      result = false;
    }
    if ((sslPolicyErrors & SslPolicyErrors.RemoteCertificateNotAvailable) != 0)
    [
      Console.WriteLine("SSL policy error {0}. " +
                        "The server certificate is not available for validation.",
                        SslPolicyErrors.RemoteCertificateNotAvailable);
      result = false;
    }
    return result;
  }
}

    4. Add the callback method to the ServicePointManager before creating a connection to the service: 

      ServicePointManager.ServerCertificateValidationCallback += Validate;
var protocolFactory= new ProtocolConnectionFactory();
...