VMware vSphere Automation Client SDK for .NET Samples - README

  Client SDK README

This document describes the samples that come bundled with the vSphere Automation SDK .NET. The samples depend on the SDK .NET libraries and the runtime library in order to work. Most of the samples demonstrate the usage of some of the vSphere Automation APIs. Additionally, some of them demonstrate the combined use of the vSphere Automation APIs and the vSphere Web Services APIs. They have been developed to work with Microsoft .NET Framework and Visual Studio (only needed if you want to modify the samples project).

• Samples Packaging
• Samples Program Structure
• Running the Samples
• Examples

Samples Packaging

The samples sub-directory contains the samples solution which in turn contains a samples project with all the source files. The samples are organized by their functionalities into the following namespaces:

Samples Program Structure

To work with the VMware-supported deployment configurations of Platform Services Controllers (Single Sign-On) and vCenter Servers, applications need to dynamically discover service URLs to make service requests. Before making service requests, applications need to authenticate with the Single Sign-On service.

Every sample performs the following basic tasks to connect to a service endpoint and initialize.

• Step 1: Connect to the lookup service endpoint on the Platform Services Controller Node.
• Step 2: Discover the Single Sign-On service URL from lookup service.
• Step 3: Connect to the Single Sign-On URL and retrieve a SAML token.
• Step 4: Discover the vAPI and VIM service URLs from lookup service.
• Step 5: Use the SAML token to login to vAPI and VIM service endpoints.
• Step 6: (Optionally) use the session ID you get from previous step for further authentication with each endpoint.
• Step 7: Discover other services through lookup service.
• Step 8: Perform certain tasks using vAPI and VIM services.

Each sample is an extension of this abstract class vmware\samples\common\SamplesBase.cs which contains common options such as Lookup Service URL, SSO username, and SSO password and common initialization logic. The common initialization logic in this class initializes vmware\samples\common\ManagementNode.cs which in turn initializes vmware\samples\common\PlatformServiceController.cs. ManagementNode and PlatformServiceController classes represent the management and infrastructure node instances that the samples connect to. PlatformServiceController provides connections to SSO and Lookup services. It also provides helper methods for these services. Similarly ManagementNode provides connections to vAPI, VIM, and VIM-PBM services. After the SamplesBase class initializes the ManagementNode, it connects to a particular management node by calling the Connect(string mgmtNodeName) method on the ManagementNode. Then it calls the abstract Run() method inherited by the samples, and finally disconnects from all services. Therefore, every sample is responsible for additional setup and teardown it requires.

The following is a code snippet from vmware\samples\common\SamplesBase.cs which shows how individual samples are called:

    /// <summary>
    /// Connects to service endpoints.
    /// </summary>
    public void Connect()
    {
        ServiceManager = new ManagementNode(this);
        ServiceManager.Connect(MgmtNodeName);
    }

    /// <summary>
    /// Runs the sample. Each sample will provider its own implementation
    /// for this method.
    /// </summary>
    public abstract void Run();

    /// <summary>
    /// Disconnects from service endpoints.
    /// </summary>
    public void Disconnect()
    {
        ServiceManager.Disconnect();
    }
                

The public methods Connect(), Run(), and Disconnect() are called by the vmware\samples\Application.cs class. This class parses user input from the command line and validates that all required arguments are supplied with the help of a library. Then it calls Connect(), Run(), and Disconnect() in that order.

• Command line argument parsing.
• Specify mandatory and optional arguments for a sample.
• Display information about sample usage.

Note that by default vSphere Automation SDK uses certificates signed by VMware Certificate Authority (VMCA). Because these certificates are not signed by an official root Certificate Authority (CA) that is trusted by your client, you must obtain the server root certificate from each server that you plan to target with your client application and install it locally. To enable certificate validation, follow these steps:

• Get the root certificate for each server. If a server is using a certificate issued by VMware Certificate Authority (VMCA), then the VMCA root certificate can be obtained from the Platform Service Controller (PSC) by the server administrator. The VMCA root certificate file is located at /var/lib/vmware/vmca/root.cer for a linux installation.
• Install each root certificate into the Windows Trusted Root Certification Authorities certificate store.
• Enable samples certificate validation by setting the value of ValidateServerCertificate to true in configuration file SDK_ROOT\client\samples\src\Samples\bin\Release\VsphereAutomationSamples.exe.config or source configuration file SDK_ROOT\client\samples\src\Samples\App.config.

Running the Samples

• If you know the name and at least the required options of the sample, you can directly run the sample by using this command:
  VsphereAutomationSamples.exe [sample name] --ls-url=[Lookup Service URL] --sso-username=[SSO username] --sso-password=[SSO password] [--additional-option=[additional option value]] ...
• If you don't know the name or the options of the sample you want to run, simply run this command to get the list of all available samples in the project:
  VsphereAutomationSamples.exe. Then you can invoke this command to get the usage for a specific sample: VsphereAutomationSamples.exe [sample name]

Examples

    C:\temp\sdk>VsphereAutomationSamples.exe TagLifecycle --ls-url https://192.0.2.0/lookupservice/sdk --sso-username administrator@vsphere.local --sso-password test
    Samples Information: 0 : [PlatformServiceController] : Using infrastructure node: 192.0.2.0
    Samples Verbose: 0 : [PlatformServiceController] : LS++ Connection (URL: https://192.0.2.0/lookupservice/sdk)
    Samples Verbose: 0 : [PlatformServiceController] : SSO Connection (URL: https://sc-rdops-vm02-dhcp-33-10.eng.vmware.com/sts/STSService/vsphere.local, AssertionId: _badafa57-4324-4978-b278-63336d2b05c0(BEARER))
    Samples Information: 0 : [ManagementNode] : Using management node: sc-rdops-vm02-dhcp-33-10.eng.vmware.com
    Samples Verbose: 0 : [ManagementNode] : vAPI Connection (URL: https://sc-rdops-vm02-dhcp-33-10.eng.vmware.com:443/api, Authn Scheme: com.vmware.vapi.std.security.session_id)
    Samples Verbose: 0 : [ManagementNode] : VIM Connection (URL: https://sc-rdops-vm02-dhcp-33-10.eng.vmware.com:443/sdk, SessionKey: 52985987-a4a4-e589-a448-e36f43ce771c)
    Samples Verbose: 0 : [ServiceEndpoint`1] : Instantiating vAPI Service - Tag
    Samples Verbose: 0 : [ServiceEndpoint`1] : Instantiating vAPI Service - Category
    Samples Information: 0 : [TagLifecycle] : Created category 'Cat-P1xTr'
    Samples Information: 0 : [TagLifecycle] : Created tag 'Tag-KwhVr'
    Samples Information: 0 : [TagLifecycle] : Updated category description to 'Tag category updated at 11/18/2014 12:51:53 PM'
    Samples Information: 0 : [TagLifecycle] : Updated tag description to 'Tag updated at 11/18/2014 12:51:54 PM'
    Samples Information: 0 : [TagLifecycle] : Deleted tag 'Tag-KwhVr'
    Samples Information: 0 : [TagLifecycle] : Deleted category 'Cat-P1xTr'
    Samples Information: 0 : [VimConnection] : Logged out successfully.
    Samples Information: 0 : [Application] : Finished running sample.
                

    C:\temp\sdk>VsphereAutomationSamples.exe TagLifecycle --ls-url https://192.0.2.0/lookupservice/sdk --sso-username administrator@vsphere.local

    Usage: VsphereAutomationSamples.exe TagLifecycle [options]

      --ls-url            Required. Lookup service URL.
      --mgmt-node-name    Management node's instance name. Ex: IP/FQDN of the node.
      --sso-username      Required. SSO username.
      --sso-password      Required. SSO password.
      --help              Display this help screen.