# VMware vSphere Automation Client SDK for .NET Samples - 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). The following sections provide information about using the samples. 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:
Package | Description
--- | ---
vmware.samples.tagging | Feature samples for Tagging API
vmware.samples.vcenter | Feature samples for virtual machine configuration and operations
vmware.samples.common | Common abstractions and helpers for the samples; this namespace does NOT contain any sample
## 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. The vSphere Automation SDK .NET samples project uses a helper library to facilitate these capabilities: 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 To run a sample, navigate to `Samples\bin\Release` directory and then: 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 Example 1: Tag lifecycle sample successfully run.
        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.
Example 2: Tag lifecycle sample run with missing required argument '--sso-password'.
        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.
Copyright © 2015, 2016 VMware, Inc. All rights not expressly granted herein are reserved. | Last updated: 15th July 2016 | VMware vSphere Automation SDK .NET