Vsphere Automation SDK 65 Net Programming Guide

VMware vSphere Automation SDK
for .NET Programming Guide

VMware vSphere Automation SDK for .NET 6.5
vCenter Server 6.5
VMware ESXi 6.5
This document supports the version of each product listed and

supports all subsequent versions until the document is
replaced by a new edition. To check for more recent editions of
this document, see http://www.vmware.com/support/pubs.
EN-002090-00
VMware vSphere Automation SDK for .NET Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2015, 2016 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
Contents
About vSphere Automation SDK for .NET Programming Guide 7
1 Introduction to the vSphere Automation SDKs 9

vSphere Automation SDKs Overview 9
Supported Programming Languages 11
2 Components of the vSphere Automation Virtualization Layer 13

Components and Services of a Virtual Environment 13
vSphere Deployment Configurations 14
3 Retrieving Service Endpoints 17

Filtering for Predefined Service Endpoints 18
Filter Parameters for Predefined Service Endpoints 18
Connect to the Lookup Service and Retrieve the Service Registration Object 19
.NET Example of Connecting to the Lookup Service and Retrieving a Service Registration
Object 20
Retrieve Service Endpoints on vCenter Server Instances 20
.NET Example of Retrieving a Service Endpoint on a vCenter Server Instance 21
Retrieve a vCenter Server ID by Using the Lookup Service 22
.NET Example of Retrieving a vCenter Server ID by Using the Lookup Service 22
Retrieve a vSphere Automation Endpoint on a vCenter Server Instance 23
.NET Example of Retrieving a vSphere Automation Endpoint on a vCenter Server Instance 23
4 Authentication Mechanisms 25
Retrieve a SAML Token 26
.NET Example of Retrieving a SAML Token 26
Create a vSphere Automation Session with a SAML Token 27
.NET Example of Creating a vSphere Automation API Session with a SAML Token 27
Create a vSphere Automation Session with User Credentials 28
Create a Web Services Session 29
.NET Example of Creating a Web Services Session 29
5 Accessing vSphere Automation Services 31

Access a vSphere Automation Service 31
6 Content Library Service 33

Content Library Overview 33
Content Library Types 34
Content Library Items 34
Content Library Storage 34
VMware, Inc. 3
Querying Content Libraries 35

Listing All Content Libraries 35
Listing Content Libraries of a Specific Type 36
List Content Libraries by Using Specific Search Criteria 36
Content Libraries 36
Create a Local Content Library 37
Publish an Existing Content Library 38
Publish a Library at the Time of Creation 39
Subscribe to a Content Library 39
Synchronize a Subscribed Content Library 41
Editing the Settings of a Content Library 42
Removing the Content of a Subscribed Library 42
Delete a Content Library 43
Library Items 43
Create an Empty Library Item 44
Querying Library Items 44
Edit the Settings of a Library Item 45
Upload a File from a Local System to a Library Item 46
Upload a File from a URL to a Library Item 48
Download Files to a Local System from a Library Item 49
Synchronizing a Library Item in a Subscribed Content Library 51
Removing the Content of a Library Item 51
Deleting a Library Item 51
7 Content Library Support for OVF Packages 53

Using the Content Library Service to Handle OVF Packages 53
Upload an OVF Package from a URL to a Library Item 53
Upload an OVF Package from a Local File System to a Library Item 54
Using the LibraryItem Service to Execute OVF-Specific Tasks 54
Deploy a Virtual Machine or Virtual Appliance from an OVF Package in a Content Library 54
Create an OVF Package in a Content Library from a Virtual Machine 55
8 Tagging Service 57
Creating Tags 57
Creating a Tag Category 58
Creating a Tag 58
Creating Tag Associations 59
Assign the Tag to a Content Library 59
Assign a Tag to a Cluster 60
Updating a Tag 60
.NET Example of Updating a Tag Description 60
9 Virtual Machine Configuration and Operations 63

Filtering Virtual Machines 63
Create a Virtual Machine 63
Configuring a Virtual Machine 64
Name and Placement 64
Boot Options 64
4 VMware, Inc.
Contents
Operating System 64
CPU and Memory 64
Networks 65
Performing Virtual Machine Power Operations 65
Java Example of Powering On a Virtual Machine 66
Index 67
VMware, Inc. 5
6 VMware, Inc.
About vSphere Automation SDK for .NET
Programming Guide
VMware vSphere Automation SDK for .NET Programming Guide describes how to use the
vSphere Automation SDK for .NET. VMware provides different APIs and SDKs for different applications
and goals. The vSphere Automation SDK for .NET supports the development of clients that use the
vSphere Automation SDK for infrastructure support tasks .
Intended Audience
This information is intended for anyone who will develop applications by using the
vSphere Automation SDK for .NET. Some programming background in C# and .NET is required.
VMware, Inc. 7
8 VMware, Inc.
Introduction to the
vSphere Automation SDKs 1
The vSphere Automation SDKs bundle client libraries for accessing new vSphere Automation features like
Content Library and existing features like Tagging. The vSphere Automation SDKs contain sample
applications and API reference documentation for the Content Library and Tagging services. The
vSphere Automation SDKs also provide sample code that retrieves the endpoints of vSphere Automation
and vSphere services and establishes a secure connection with the vSphere Automation endpoint.
vSphere Automation supports six languages for accessing the vSphere Automation API services and
provides six SDKs for developing client applications for managing components in your virtual environment.
This chapter includes the following topics:
n “vSphere Automation SDKs Overview,” on page 9
n “Supported Programming Languages,” on page 11
vSphere Automation SDKs Overview

The vSphere Automation API provides a unified programming interface to vSphere Automation services
that you can use through SDKs provided in six programming languages. The vSphere Automation API
provides a service-oriented architecture for accessing resources in the virtual environment by issuing
requests to the vSphere Automation Endpoint.
vSphere Automation API client applications communicate with services on the Platform Services Controller
and vCenter Server.
VMware, Inc. 9
Figure 1‑1. Communication Model of vSphere Automation API Client Applications
Platform Services Controller

Retrieve service
endpoints
Lookup Service
Establish
authenticated
session
vCenter Single Sign-On
Client vCenter Server

Application Communicate
with services
vSphere Automation
API Endpoint
Content Тagging
Library Service
vSphere API Services
vSphere Automation API client applications use the Lookup Service to retrieve the vCenter Single Sign-On
endpoint, the vSphere Automation Endpoint, and the endpoints of services that are exposed through the
vSphere API. To access vSphere Automation services such as Content Library and Tagging, client
applications issue requests to the vSphere Automation Endpoint. By using the vCenter Single Sign-On
service, client applications can either establish an authenticated vSphere Automation session, or
authenticate individual requests to the vSphere Automation Endpoint.
Client applications can access services that are exposed through the vSphere API by using the vSphere
Management SDK.
Depending on the vSphere deployment model, client applications can communicate with
vSphere Automation services on a single vCenter Server instance or multiple vCenter Server instances. For
more information about the vSphere deployment models, see Chapter 2, “Components of the vSphere
Automation Virtualization Layer,” on page 13
SDK Developer Setup

To start developing a vSphere Automation API client application, you must download the software and set
up a development environment. You can find instructions for setting up a development environment in the
README for each vSphere Automation SDK.
SDK Samples
The vSphere Automation SDKs provide sample applications that you can extend to implement client
applications that serve your needs. The code examples in the vSphere Automation SDKs documentation are
based on these sample applications.
10 VMware, Inc.
Chapter 1 Introduction to the vSphere Automation SDKs
Supported Programming Languages

The vSphere Automation SDKs are packed in six different programming languages that let you build client
applications on your preferred programming language.
n vSphere Automation SDK for Java
n vSphere Automation SDK for Python
n vSphere Automation SDK for .NET
n vSphere Automation SDK for Perl
n vSphere Automation SDK for Ruby
n vSphere Automation SDK for REST
VMware, Inc. 11
12 VMware, Inc.
Components of the
vSphere Automation Virtualization
Layer 2
At the core of vSphere Automation is vSphere, which provides the virtualization layer of the software-
defined data center. You can use vSphere deployment options for vCenter Server and ESXi hosts to build
virtual environments of different scales.
n “Components and Services of a Virtual Environment,” on page 13
n “vSphere Deployment Configurations,” on page 14
Components and Services of a Virtual Environment

Starting with vSphere 6.0, the deployment of the virtual environment consists of two major components that
provide different sets of services, the VMware Platform Services Controller and vCenter Server. You can
deploy vCenter Server with an embedded or external Platform Services Controller.
Services Installed with Platform Services Controller

The Platform Services Controller group of infrastructure services contains vCenter Single Sign-On, License
Service, Lookup Service, and VMware Certificate Authority. The services installed with the
Platform Services Controller are common to the entire virtual environment. A Platform Services Controller
can be connected to one or more vCenter Server instances. In a deployment that consists of more than one
Platform Services Controller, the data of each service is replicated across all Platform Services Controller
instances.
In vSphere Automation API client applications, you use the vCenter Single Sign-On and the Lookup Service
on the Platform Services Controller to provide a range of functionality.
Authentication and You use the vCenter Single Sign-On service to establish an authenticated
Session Management session with the vSphere Automation Endpoint. You send credentials to the
vCenter Single Sign-On service and receive a SAML token that you use to
obtain a session ID from the vSphere Automation Endpoint. Alternatively,
you can access the vSphere Automation APIs in a sessionless manner by
including the SAML token in every request that you issue to the
vSphere Automation Endpoint.
Service Discovery You use the Lookup Service to discover the endpoint URL for the vCenter
Single Sign-On service on the Platform Services Controller, the location of the
vCenter Server instances, and the vSphere Automation Endpoint.
VMware, Inc. 13
Services Installed with vCenter Server

vCenter Server is a central administration point for ESXi hosts. The vCenter Server group of services
® ®
contains vCenter Server, vSphere Web Client, Inventory Service, vSphere Auto Deploy™, vSphere ESXi™
®
Dump Collector, VMware vSphere Syslog Collector on Windows and VMware vSphere Syslog Service for
the vCenter Server Appliance.
vCenter Server also provides services that you can access through the vSphere Automation Endpoint.
Content Library Service You can use the Content Library Service to share VM templates, vApp
templates, and other files across the software-defined data center. You can
create, share, and subscribe to content libraries on the same vCenter Server
instance or on a remote instance. This promotes consistency, compliance,
efficiency, and automation in deploying workloads at scale. By using content
libraries, you can also create OVF packages from virtual machines and
virtual appliances in hosts, resource pools, and clusters. You can then use the
OVF packages to provision new virtual machines in hosts, resource pools,
and clusters.
Tagging Service This service supports the definition of tags that you can associate with
vSphere objects or vSphere Automation resources. The vSphere Automation
SDKs provide the capability to manage tags programmatically.
vSphere Deployment Configurations

vSphere Automation client applications communicate with services on the Platform Services Controller and
vCenter Server components of the virtual environment. vCenter Server can be deployed with an embedded
or external Platform Services Controller.
vCenter Server with an Embedded Platform Services Controller

vCenter Server and Platform Services Controller reside on the same virtual machine or physical server. This
deployment is most suitable for small environments such as development or test beds.
You can use the Platform Services Controller in two ways to establish secure, authenticated sessions for your
client application, by making requests to the Lookup Service and the vCenter Single Sign-On Service.
One way to use the Platform Services Controller is to request an authentication token that can be used to
authenticate requests across services. The client connects to the Lookup Service and retrieves the vCenter
Single Sign-On Service endpoint and the vSphere Automation API endpoint. The client then uses the
vCenter Single Sign-On endpoint to authenticate with user credentials and receive a token that securely
verifies the client's credentials. This allows the client to authenticate with a number of service endpoints
without sending user credentials over the network repeatedly.
Alternatively, if the client connects directly to the vSphere Automation API endpoint, there is no need for
the client to interact with the vCenter Single Sign-On Service. The client sends user credentials to the
vSphere Automation API endpoint, which creates a session identifier that persists across requests.
14 VMware, Inc.
Chapter 2 Components of the vSphere Automation Virtualization Layer
Figure 2‑1. vCenter Server with Embedded Platform Services Controller
VM or Physical Server
Single Sign-On
Service URL
Lookup vCloud Suite
Service Endpoint URL
vCenter Server
URL
Other Services
URLs
Single
Sign-ON SAML Token
Service
VM
VMware ESXi
vCenter Server
Content Library
Service
vAAPI
Endpoint Тagging
Service VM
Other Services
VMware ESXi
vCenter Server with an External Platform Services Controller

In the case of an external Platform Services Controller, the vCenter Server and the
Platform Services Controller are deployed on separate virtual machines or physical servers. The
Platform Services Controller can be shared across several vCenter Server instances. For larger deployments
or to provide better availability, more than one Platform Services Controller can be deployed. When
configured as replication partners within a single vCenter Single Sign-On domain,
Platform Services Controller instances replicate all user and system data within the cluster.
A client application functions in a similar way as in a Platform Services Controller with embedded
vCenter Server deployment. The only difference is that the client application can access services on multiple
vCenter Server instances, or services only on a particular vCenter Server instance.
VMware, Inc. 15
Figure 2‑2. vCenter Server with External Platform Services Controller
VM or Physical Server
Single Sign-On
Service URL
Lookup vCloud Suite
Service Endpoint URL
vCenter Server
URL
Other Services
URLs
Single
Sign-ON SAML Token
Service
VM or Physical Server VM or Physical Server
vCenter Server vCenter Server
Content Library Content Library

Service Service
vAAPI vAAPI
Endpoint Тagging Endpoint Тagging
Service Service
Other Services Other Services
VM VM VM VM
VMware ESXi VMware ESXi VMware ESXi VMware ESXi
16 VMware, Inc.
Retrieving Service Endpoints 3
To access services and resources in the virtual environment, vSphere Automation API client applications
must know the endpoints of vSphere Automation and vSphere services. Client applications retrieve service
endpoints from the Lookup Service that runs on the Platform Services Controller.
The Lookup Service provides service registration and discovery by using a Web services API. By using the
Lookup Service, you can retrieve endpoints of services on the Platform Services Controller and
vCenter Server. The following endpoints are available from the Lookup Service.
n The vCenter Single Sign-On endpoint on the Platform Services Controller. You use the vCenter Single
Sign-On service to get a SAML token and establish an authenticated session with a vSphere Automation
endpoint or a vCenter Server endpoint.
n The vSphere Automation Endpoint on vCenter Server. Through the vSphere Automation Endpoint, you
can make requests to vSphere Automation API services such as virtual machine management, Content
Library, and Tagging.
n The vCenter Server endpoint. In an environment with external Platform Services Controller instances,
you can use the vCenter Server endpoint to get the node ID of a particular vCenter Server instance. By
using the node ID , you can retrieve service endpoints on that vCenter Server instance.
n The vSphere API endpoint and endpoints of other vSphere services that run on vCenter Server.
Workflow for Retrieving Service Endpoints

The workflow that you use to retrieve service endpoints from the Lookup Service might vary depending on
the endpoints that you need and their number. Follow this general workflow for retrieving service
endpoints.
1 Connect to the Lookup Service on the Platform Services Controller and service registration object so
that you can query for registered services.
2 Create a service registration filter for the endpoints that you want to retrieve.
3 Use the filter to retrieve registration information for services from the Lookup Service.
4 Extract one or more endpoint URLs from the array of registration information that you receive from the
Lookup Service.
n “Filtering for Predefined Service Endpoints,” on page 18
n “Filter Parameters for Predefined Service Endpoints,” on page 18
n “Connect to the Lookup Service and Retrieve the Service Registration Object,” on page 19
n “Retrieve Service Endpoints on vCenter Server Instances,” on page 20
VMware, Inc. 17
n “Retrieve a vCenter Server ID by Using the Lookup Service,” on page 22
n “Retrieve a vSphere Automation Endpoint on a vCenter Server Instance,” on page 23
Filtering for Predefined Service Endpoints

The Lookup Service maintains a registration list of vSphere services. You can use the Lookup Service to
retrieve registration information for any service by setting a registration filter that you pass to the List()
function on the Lookup Service. The functions and objects that you can use with the Lookup Service are
defined in the lookup.wsdl file that is part of the SDK.
Lookup Service Registration Filters

You can query for service endpoints through a service registration object that you obtain from the Lookup
Service. You invoke the List() function on the Lookup Service to list the endpoints that you need by passing
LookupServiceRegistrationFilter. LookupServiceRegistrationFilter identifies the service and the
endpoint type that you can retrieve.
Optionally, you can include the node ID parameter in the filter to identify the vCenter Server instance where
the endpoint is hosted. When the node ID is omitted, the List() function returns the set of endpoint URLs
for all instances of the service that are hosted on different vCenter Server instances in the environment.
For example, a LookupServiceRegistrationFilter for queering the vSphere Automation service has these
service endpoint elements.
Table 3‑1. Service Registration Filter Parameters

Filter Types Value Description
LookupServiceRegistrationServiceType product= "com.vmware.cis" vSphere Automation namespace.
type="cs.vapi" Identifies the

vSphere Automation service.
LookupServiceRegistrationEndpointType type="com.vmware.vapi.endpo Specifies the endpoint path for

int" the service.
protocol= Identifies the protocol that will

"vapi.json.https.public" be used for communication with
the endpoint .
For information about the filter parameter of the available predefined service endpoints, see “Filter
Parameters for Predefined Service Endpoints,” on page 18.
Filter Parameters for Predefined Service Endpoints

Depending on the service endpoint that you want to retrieve, you provide different parameters to the
LookupServiceRegistrationFilter that you pass to the List() function on the Lookup Service. To search for
services on a particular vCenter Server instance, set the node ID parameter to the filter.
Table 3‑2. Input Data for URL Retrieval for the Lookup Service Registration Filter
Service Input Data Value
vCenter Single Sign-On product namespace com.vmware.cis

service type cs.identity
protocol wsTrust
endpoint type com.vmware.cis.cs.identity.sso
vSphere Automation Endpoint product namespace com.vmware.cis
service type cs.vapi
18 VMware, Inc.
Chapter 3 Retrieving Service Endpoints
Table 3‑2. Input Data for URL Retrieval for the Lookup Service Registration Filter (Continued)
Service Input Data Value
protocol vapi.json.https.public
endpoint type com.vmware.vapi.endpoint
vCenter Server product namespace com.vmware.cis
service type vcenterserver
protocol vmomi
endpoint type com.vmware.vim
vCenter Storage Monitoring product namespace com.vmware.vim.sms
Service
service type sms
protocol https
endpoint type com.vmware.vim.sms
vCenter Storage Policy-Based product namespace com.vmware.vim.sms
Management
service type sms
protocol https
endpoint type com.vmware.vim.pbm
vSphere ESX Agent Manager product namespace com.vmware.vim.sms
service type cs.eam
protocol vmomi
endpoint type com.vmware.cis.cs.eam.sdk
Connect to the Lookup Service and Retrieve the Service Registration

Object
You must connect to the Lookup Service to gain access to its operations. After you connect to the Lookup
Service, you must retrieve the service registration object to make registration queries.
Procedure
1 Connect to the Lookup Service.
a Configure a connection stub for the Lookup Service endpoint, which uses SOAP bindings, by using
the HTTPS protocol.
b Create a connection object to communicate with the Lookup Service.
2 Retrieve the Service Registration Object.

a Create a managed object reference to the Service Instance.
b Invoke the RetrieveServiceContent() method to retrieve the ServiceContent data object.
c Save the managed object reference to the service registration object.
With the service registration object, you can make registration queries.
VMware, Inc. 19
.NET Example of Connecting to the Lookup Service and Retrieving a Service

Registration Object
The example is based on the code from the LsConnection.cs sample file. The source file is located in the
following vSphere Automation SDK for .NET
directory: /client/samples/src/Samples/vmware/samples/common
using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using vmware.lookupservice;
// 1 - Create a custom binding for SOAP messages.

var customBinding = new CustomBinding();
var textMessageEncoding = new TextMessageEncodingBindingElement();
textMessageEncoding.MessageVersion = MessageVersion.Soap11;
var transport = new HttpsTransportBindingElement();
transport.MaxReceivedMessageSize = 2147483647;
customBinding.Elements.Add(textMessageEncoding);
customBinding.Elements.Add(transport);
// 2 - Create an object that encapsulates the Lookup Service URL.

var address = new EndpointAddress(lsUrl);
// 3 - Create a connection object to communicate with the Lookup Service.

lsPort = new LsPortTypeClient(customBinding, address);
// 4 - Manufacture a managed object reference.

var serviceInstanceRef = new ManagedObjectReference();
serviceInstanceRef.type = "LookupServiceInstance";
serviceInstanceRef.Value = "ServiceInstance";
// 5 - Retrieve the ServiceContent managed object.

serviceContent = lsPort.RetrieveServiceContent(serviceInstanceRef);
// 6 - Retrieve the service registration object.

serviceRegistration = serviceContent.serviceRegistration;
Retrieve Service Endpoints on vCenter Server Instances

You can create a function that obtains the endpoint URLs of a service on all vCenter Server instances in the
environment. You can modify that function to obtain the endpoint URL of a service on a particular
vCenter Server instance.
Prerequisites
n Establish a connection with the Lookup Service.
n Retrieve a service registration object.
Procedure
1 Create a registration filter object, which contains the following parts:
n A filter criterion for service information
20 VMware, Inc.
n A filter criterion for endpoint information
Option Description
Omit the node ID parameter Retrieves the endpoint URLs of the service on all vCenter Server instances.
Include the node ID parameter Retrieves the endpoint URL of the service on a particular vCenter Server
instance.
2 Retrieve the specified service information by using the List() function.
Depending on whether you included the node ID parameter, the List() function returns one of the
following results:
n A list of endpoint URLs for a service that is hosted on all vCenter Server instances in the environment.
n An endpoint URL of a service that runs on a particular vCenter Server instance.
What to do next
Call the function that you implemented to retrieve service endpoints. You can pass different filter
parameters depending on the service endpoints that you need. For more information, see “Filter Parameters
for Predefined Service Endpoints,” on page 18.
To retrieve a service endpoint on a particular vCenter Server instance, you must retrieve the node ID of that
instance and pass it to the function. For information about how to retrieve the ID of a vCenter Server
instance, see “Retrieve a vCenter Server ID by Using the Lookup Service,” on page 22.
.NET Example of Retrieving a Service Endpoint on a vCenter Server Instance

This example provides a common pattern for filtering Lookup Service registration data. This example is
based on the code in the LsConnection.cs sample file. The file is located in the following
vSphere Automation SDK for .NET directory: /client/samples/src/Samples/vmware/samples/common
using System;
using vmware.lookupservice;
public LookupServiceRegistrationInfo[] LookupSingleServiceUrl(string prod,

string sType,
string proto,
string eType,
string nodeId)
{
// 1 - Create a filter criterion for service info.
var filterServiceType = new LookupServiceRegistrationServiceType();
filterServiceType.product = prod;
filterServiceType.type = sType;
// 2 - Create a filter criterion for endpoint info.

var filterEndpointType = new LookupServiceRegistrationEndpointType();
filterEndpointType.protocol = proto;
filterEndpointType.type = eType;
// 3 - Create the registration filter object.

var filterCriteria = new LookupServiceRegistrationFilter();
filterCriteria.serviceType = filterServiceType;
filterCriteria.endpointType = filterEndpointType;
filterCriteria.nodeId = nodeId;
VMware, Inc. 21
// 4 - Retrieve specified service info with the List() method.

return lsPort.List(serviceRegistration, filterCriteria);
}
Retrieve a vCenter Server ID by Using the Lookup Service

You use the node ID of a vCenter Server instance to retrieve the endpoint URL of a service on that
vCenter Server instance. You specify the node ID in the service registration filter that you pass to the List()
function on the Lookup Service.
Managed services are registered with the instance name of the vCenter Server instance where they run. The
instance name maps to a unique vCenter Server ID. The instance name of a vCenter Server system is
specified during installation and might be an FQDN or an IP address.
Prerequisites
Procedure
1 List the vCenter Server instances.
2 Find the matching node name of the vCenter Server instance and save the ID.
Use the node ID of the vCenter Server instance to filter subsequent endpoint requests. You can use the node
ID in a function that retrieves the endpoint URL of a service on a vCenter Server instance. For information
about implementing such a function, see “Retrieve Service Endpoints on vCenter Server Instances,” on
page 20.
.NET Example of Retrieving a vCenter Server ID by Using the Lookup Service

vSphere Automation SDK for .NET directory: /client/samples/src/Samples/vmware/samples/common.
using System;
using System.Linq;
using vmware.vapi.util.security;
public String getMgmtNodeId(String nodeInstanceName)

{
// 1 - List the vCenter Server instances.
var services = LookupServiceUrls("com.vmware.cis",
"vcenterserver",
"vmomi",
"com.vmware.vim");
// 2 - Find the matching node name and save the ID.

foreach (var service in services)
{
foreach (var serviceAttribute in service.serviceAttributes
{
if (serviceAttribute.key.Equals("com.vmware.vim.vcenter.instanceName",
StringComparison.CurrentCultureIgnoreCase) &&
nodeInstanceName.Equals(serviceAttribute.value,
StringComparison.CurrentCultureIgnoreCase))
22 VMware, Inc.
{
return service.nodeId;
}
}
}
}
Retrieve a vSphere Automation Endpoint on a vCenter Server

Instance
Through the vSphere Automation Endpoint, you can access other vSphere Automation services that run on
vCenter Server, such as Content Library and Tagging. To use a vSphere Automation service, you must
retrieve the vSphere Automation Endpoint.
Prerequisites
n Determine the node ID of the vCenter Server instance where the vSphere Automation service runs.
n Implement a function that retrieves the endpoint URL of a service on a vCenter Server instance.
Procedure
1 Invoke the function for retrieving the endpoint URL of a service on a vCenter Server instance by
passing filter strings that are specific to the vSphere Automation endpoint.
2 Save the URL from the resulting single-element list.
.NET Example of Retrieving a vSphere Automation Endpoint on a

vCenter Server Instance
vSphere Automation SDK for .NET directory: /client/samples/src/Samples/vmware/samples/common.
targetNodeId = getMgmtNodeId(target_node_fqdn)
var serviceInfo = LookupSingleServiceUrl("com.vmware.cis",
"cs.vapi",
"vapi.json.https",
"com.vmware.vapi.endpoint",
targetNodeId);
var vapiUrl = serviceInfo[0].serviceEndpoints[0].url;
VMware, Inc. 23
24 VMware, Inc.
Authentication Mechanisms 4
To perform operations on services in the vSphere environment, you must create an authenticated connection
to the services that you want to use. With the vSphere Automation SDK for .NET you can authenticate and
access vSphere Automation services.
Client applications can choose from two supported authentication patterns for accessing services in the
virtual environment.
For better security, client applications can request a security token to authenticate connections with the
vSphere Automation services.
To invoke operations on services, client applications must create a security context. The security context
represents the client authentication. You can achieve authentication by using one of the following
mechanisms.
Password-Based To authenticate with user name and password, you connect to the
Authentication vSphere Automation Endpoint with vCenter Single Sign-On user credentials
and obtain a session identifier (ID). The user account credentials are
validated by the vSphere Automation Endpoint, and must be present in the
vCenter Single Sign-On identity store. The session ID is valid only for the
service endpoint that you want to access and that issues the session ID.
Token-Based Client applications can authenticate by using the vCenter Single Sign-On
Authentication component on thePlatform Services Controller. vCenter Single Sign-On
includes the Security Token Service (STS) that issues security tokens. The
token must comply with the Security Assertion Markup Language (SAML)
specification, which defines an XML-based encoding for communicating
authentication data.
vCenter Single Sign-On supports two types of security tokens: bearer token
and Holder-of-Key (HoK) token. To acquire a SAML token, client
applications must issue a token request to vCenter Single Sign-On.
Client applications can present a SAML token to the vSphere Automation

Endpoint in exchange for a session identifier with which they can perform a
series of authenticated operations.
To retrieve a session ID for the vSphere Web Services endpoint, you provide
the SAML token to the vSphere Web services endpoint. For more information
about creating an authenticated session to access the vSphere Web Services,
see the vSphere Web Services SDK Programming Guide documentation.
VMware, Inc. 25
n “Retrieve a SAML Token,” on page 26
n “Create a vSphere Automation Session with a SAML Token,” on page 27
n “Create a vSphere Automation Session with User Credentials,” on page 28
n “Create a Web Services Session,” on page 29
Retrieve a SAML Token

The vCenter Single Sign-On service provides authentication mechanisms for securing the operations that
your client application performs in the virtual environment. Client applications use SAML security tokens
for authentication.
Client applications use the vCenter Single Sign-On service to retrieve SAML tokens. For more information
about how to acquire a SAML security token, see the vCenter Single Sign-On Programming Guide
documentation.
The vSphere Automation SDK for .NET provides the SsoConnection utility class. The utility creates a
connection with the vCenter Single Sign-On service and acquires a SAML token. The security token is
required for securing the communication between the client application and the services running in your
virtual environment. The source file of the utility is in the vSphere Automation SDK for .NET directory:
client/samples/src/Samples/vmware/vcloud/suite/samples/common/SsoConnection.cs.
Prerequisites
Verify that you have the vCenter Single Sign-On URL. You can use the Lookup Service on the
Platform Services Controller to obtain the endpoint URL. For information about retrieving service
endpoints, see Chapter 3, “Retrieving Service Endpoints,” on page 17.
Procedure
1 Create a connection object to communicate with the vCenter Single Sign-On service.
Pass the vCenter Single Sign-On endpoint URL, which you can get from the Lookup Service.
2 Issue a security token request by sending valid user credentials to the vCenter Single Sign-On service
on the Platform Services Controller.
The vCenter Single Sign-On service returns a SAML token.
What to do next
You can present the SAML token to the vSphere Automation API Endpoint or other endpoints, such as the
vSphere Web Services Endpoint. The endpoint returns a session ID and establishes a persistent session with
that endpoint. Each endpoint that you connect to uses your SAML token to create its own session.
.NET Example of Retrieving a SAML Token

The example is based on the code in the PlatformServiceController.cs sample file. This file is located in the
following vSphere Automation SDK for .NET
directory: /client/samples/src/Samples/vmware/samples/common.
using System;
using System.Linq;
using vmware.vapi.util.security;
// Create a connection object to communicate with the vCenter Single Sign-On service.
var ssoUrl = FindSsoUrl();
26 VMware, Inc.
Chapter 4 Authentication Mechanisms
SsoConnection = new SsoConnection(ssoUrl);
// Request a SAML token.

SsoConnection.AcquireSamlToken(ssoUserName, ssoPassword, SamlTokenConfirmationType.BEARER);
Create a vSphere Automation Session with a SAML Token

To establish a vSphere Automation session, you create a connection to the vSphere Automation API
Endpoint and then you authenticate with a SAML token to create a session for the connection.
Prerequisites
n Retrieve the vSphere Automation Endpoint URL from the Lookup Service.
n Obtain a SAML token from the vCenter Single Sign-On service.
Procedure
1 Create a connection by specifying the vSphere Automation API Endpoint URL and the message
protocol to be used for the connection.
Note To transmit your requests securely, use https for the vSphere Automation API Endpoint URL.
2 Create the request options or stub configuration and set the security context to be used.
The security context object contains the SAML token retrieved from the vCenter Single Sign-On service.
Optionally, the security context might contain the private key of the client application.
3 Create an interface stub or a REST path that uses the stub configuration instance.
The interface stub corresponds to the interface containing the method to be invoked.
4 Invoke the session create method.
The service creates an authenticated session and returns a session identification cookie to the client.
5 Create a security context instance and add the session ID to it.
6 Update the stub configuration instance with the session security context.
What to do next
Use the updated stub configuration with the session ID to create a stub for the interface that you want to
use. Method calls on the new stub use the session ID to authenticate.
.NET Example of Creating a vSphere Automation API Session with a SAML

Token
This example is based on code in the ServiceEndpoint.cs sample file. This file is located in the following
vSphere Automation SDK for .NET directory: client/samples/src/Samples/vmware/samples/common/.
using System;
using System.Security.Cryptography;
using vmware.vapi.bindings;
using vmware.vapi.dsig;
using vmware.vapi.protocol;
using vmware.vapi.security;
// Create a connection to the vSphere

Automation Endpoint.
var protocolFactory = new ProtocolConnectionFactory();
var protocolConnection = protocolFactory.GetConnection(Protocol.Http, vapiUrl, new
VMware, Inc. 27
CspParameters());
myStubFactory = new StubFactory(protocolConnection.GetApiProvider());
// Create a temporary security context and

// apply it to the stub configuration instance.
var tempStubConfiguration = new StubConfiguration();
tempStubConfiguration.SetSecurityContext(new SamlTokenSecurityContext
(ssoConnection.SamlToken, ssoConnection.PrivateKey));
// 3 - Create session with SAML token context.

Session mySession = myStubFactory.CreateStub<Session>(tempStubConfiguration);
// 4 - Use the SAML token context to log in to the vSphere

Automation Endpoint.
sessionId = Login(mySession);
// 5 - Use the session ID to replace the SAML token for the vSphere
Automation API session.
myStubConfiguration = new StubConfiguration();
myStubConfiguration.SetSecurityContext(new SessionSecurityContext(sessionId));
mySession = myStubFactory.CreateStub<Session>(myStubConfiguration);
Create a vSphere Automation Session with User Credentials

With the vSphere Automation SDK for .NET, you can create authenticated sessions by using only user
credentials.
You connect to the vSphere Automation Endpoint by using a user name and password known to the
vCenter Single Sign-On service. The vSphere Automation uses your credentials to authenticate with the
vCenter Single Sign-On Service and obtain a SAML token.
Prerequisites
n Retrieve the vSphere Automation Endpoint URL from the Lookup Service.
n Verify that you have valid user credentials for the vCenter Single Sign-On identity store.
Procedure
1 Create a connection stub by specifying the vSphere Automation Endpoint URL and the message
protocol to be used for the connection.
2 Create a stub configuration instance and set the specific security context to be used.
The security context object uses the user name and password that are used for authenticating to the
vCenter Single Sign-On service.
3 Create a Session stub that uses the stub configuration instance.
4 Call the create operation on the Session stub to create an authenticated session to the
vSphere Automation Endpoint.
The operation returns a session identifier.
5 Create a security context instance and add the session ID to it.
6 Update the stub configuration instance with the session security context.
28 VMware, Inc.
Chapter 4 Authentication Mechanisms
What to do next
You can use the authenticated session to access vSphere Automation services. For more information about
creating stubs to the vSphere Automation services, see Chapter 5, “Accessing vSphere Automation
Services,” on page 31.
Create a Web Services Session

To develop a complex workflow, you might need to send requests to vSphere Web Services running in your
virtual environment. To achieve this, you access the vSphere Web Services API by using the Web Services
endpoint.
The vSphere Web Services API also supports session-based access. To establish an authenticated session, you
can send the SAML token retrieved from the vCenter Single Sign-On service to a vSphere Web Service. In
return you receive a session identifier that you can use to access the service. For more information about
accessing Web Services, see the vSphere Web Services SDK Programming Guide documentation.
Prerequisites
n Retrieve the vSphere Web Services endpoint URL from the Lookup Service.
n Obtain a SAML token from the vCenter Single Sign-On service.
Procedure
1 Connect to the vSphere Web Services endpoint.
2 Send the SAML token to a specific Web service to create an authenticated session.
3 Add the retrieved session ID to the service content object.
The Service Content object gives you access to several server-side managed objects that represent
vSphere services and components.
.NET Example of Creating a Web Services Session

This example is based on code in the VimConnection.cs sample file. This file is located in the following
vSphere Automation SDK for .NET directory: client/samples/src/Samples/vmware/samples/common.
using System;
using System.IdentityModel.Tokens;
using System.Net;
using System.ServiceModel.Description;
using vmware.vim25;
// Wrap a SAML token for the Web Services authentication.

var token = ssoConnection.SamlTokenXml;
var created = DateTime.Parse(ssoConnection.RequestSecurityTokenResponse.Lifetime.Created.Value;
var expires = DateTime.Parse(ssoConnection.RequestSecurityTokenResponse.Lifetime.Expires.Value;
var securityToken = new GenericXmlSecurityToken(token, null, created, expires, null, null, null);
// Create a communication port with the SAML token context.

var binding = GetCustomBinding(SecurityKeyType.BearerKey);
var endpoint = new EndpointAddress(vcenterUrl);
var factory = new ChannelFactory<VimPortType>(binding, endpoint);
factory.Endpoint.Behaviors.Add(new ClientViaBehavior(new Uri(vcenterUrl));
factory.Credentials.SupportInteractive = false;
var vimPort = factory.CreateChannelWithIssuedToken(securityToken);
VMware, Inc. 29
// Create a reference to the ServiceInstance managed object.

var serviceRef = new ManagedObjectReference();
serviceRef.type = “ServiceInstance”;
serviceRef.value = “ServiceInstance”;
// Retrieve a Service Content data object.

// ServiceContent provides access to the vSphere Web Services.
var serviceContent = vimPort.RetrieveServiceContent(serviceRef);
// Create a session to the Web Service by using the SAML token.

var mySession = vimPort.LoginByToken(serviceContent.sessionManager);
30 VMware, Inc.
Accessing vSphere Automation
Services 5
vSphere Automation SDK provides mechanisms for creating remote stubs to give clients access to
vSphere Automation services.
The sequence of tasks you must follow to create a remote stub starts with creating a ProtocolFactory. You
use the protocol factory object to create a ProtocolConnection. Connection objects provide the basis for
creating stub interfaces tovSphere Automation services.
When you establish a connection to the vSphere Automation Endpoint, you can create a StubFactory object
and a StubConfiguration object. With these objects, you can create the remote stub for the
vSphere Automation service that you want to access.
The complete connection sequence also includes SSL truststore support and a temporary StubConfiguration
that you use for SAML token authentication and session creation.
For greater security, use an external utility to create a certificate store:
keytool -import -noprompt -trustcacerts \

-alias <alias name> \
-file <certificate file> \
-keystore <truststore filename> \
-storepass <truststore password>
Access a vSphere Automation Service

To access a vSphere Automation service, you must have a valid session connection. The sequence for
accessing a vSphere Automation service includes creating a protocol connection object and using it to create
the service stub.
Prerequisites
Establish a connection to the vSphere Automation Endpoint URL. For more information about the
authentication mechanisms that you can use, see Chapter 4, “Authentication Mechanisms,” on page 25.
Procedure
1 Create a protocol factory object.
2 Create a protocol connection object to access an API provider.
The vSphere Automation API clients use ApiProvider instances to invoke operations on services
running in the virtual environment. To invoke an operation, you must specify the target service and
operation, input parameters, and execution context.
3 Create a StubFactory object by using the ApiProvider instance.
4 Create a StubConfiguration instance and set the security context to be used for the service stub.
VMware, Inc. 31
5 Create the stub for the vSphere Automation service interface by calling the create method of the
StubFactory instance. Pass the service class and the StubConfiguration instance as arguments.
32 VMware, Inc.
Content Library Service 6
The Content Library Service provides means for managing content libraries in the context of a single or
multiple vCenter Server instances deployed in your virtual environment. You can use the
vSphere Automation APIs to access the Content Library Service through the vSphere Automation Endpoint.
Administrators can use content libraries to share VM templates, vApp templates, and other types of files
across vCenter Server instances in the virtual environment. Sharing templates across your virtual
environment promotes consistency, compliance, efficiency, and automation in deploying workloads at scale.
n Content Library Overview on page 33

A content library instance represents a container for a set of library items. A content library item
instance represents the logical object stored in the content library, which might be one or more usable
files.
n Querying Content Libraries on page 35

You can create queries to find libraries that match your criteria. You can also retrieve a list of all
libraries or only the libraries of a specific type.
n Content Libraries on page 36

The Content Library API provides services that allow you to create and manage content libraries
programmatically. You can create a local library and publish it for the entire virtual environment. You
can also subscribe to use the contents of a local library and enable automatic synchronization to ensure
that you have the latest content.
n Library Items on page 43

A library item groups multiple files within one logical unit. You can perform various tasks with the
items in a content library.
Content Library Overview

A content library instance represents a container for a set of library items. A content library item instance
represents the logical object stored in the content library, which might be one or more usable files.
n Content Library Types on page 34

You can create two types of libraries, local and subscribed.
n Content Library Items on page 34

Library items are VM templates, vApp templates, or other VMware objects that can be contained in a
content library. VMs and vApps have several files, such as log files, disk files, memory files, and
snapshot files that are part of a single library item. You can create library items in a specific local
library or remove items from a local library. You can also upload files to an item in a local library so
that the libraries subscribed to it can download the files to their NFS or SMB server, or datastore.
VMware, Inc. 33
n Content Library Storage on page 34

When you create a local library, you can store its contents on a datastore managed by the
vCenter Server instance or on a remote file system.
Content Library Types

You can create two types of libraries, local and subscribed.
n You can create a local library as the source for content you want to save or share. Create the local library
on a single vCenter Server instance. You can add items to a local library or remove them. You can
publish a local library and as a result this content library service endpoint can be accessed by other
vCenter Server instances in your virtual environment. When you publish a library, you can configure
the authentication method, which a subscribed library must use to authenticate to it.
n You can create a subscribed library and populate its content by synchronizing to a local library. A
subscribed library contains copies of the local library files or just the metadata of the library items. The
local library can be located on the same vCenter Server instance as the subscribed library, or the
subscribed library can reference a local library on a different vCenter Server instance. You cannot add
library items to a subscribed library. You can only add items to the source library. After synchronization,
both libraries will contain the same items.
Content Library Items

Library items are VM templates, vApp templates, or other VMware objects that can be contained in a
content library. VMs and vApps have several files, such as log files, disk files, memory files, and snapshot
files that are part of a single library item. You can create library items in a specific local library or remove
items from a local library. You can also upload files to an item in a local library so that the libraries
subscribed to it can download the files to their NFS or SMB server, or datastore.
For information about the tasks that you can perform by using the content library service, see “Content
Libraries,” on page 36.
Content Library Storage

When you create a local library, you can store its contents on a datastore managed by the vCenter Server
instance or on a remote file system.
Depending on the type of storage that you have, you can use Virtual Machine File System (VMFS) or
Network File System (NFS) for storing content on a datastore.
For storing content on a remote file system, you can enter the path to the NFS storage that is mounted on the
Linux file system of the vCenter Server Appliance. For example, you can use the following URI formats:
nfs://<server>/<path>?version=4 and nfs://<server>/<path>. If you have a vCenter Server instance that
runs on a Windows machine, you can specify the Server Massage Block (SMB) URI to the Windows shared
folders that store the library content. For example, you can use the following URI format: smb://<unc-
server>/<path>.
.NET Example of Storing Library Content on a Datastore

This example shows how to define where the library content is stored.
...
using vmware.content;
using vmware.content.library;
// Create a StorageBacking instance of datastore type.

var libraryBacking = new StorageBacking();
libraryBacking.SetType(vmware.content.library.StorageBacking.Type.DATASTORE);
34 VMware, Inc.
Chapter 6 Content Library Service
// Provide the datastore ID.

libraryBacking.SetDatastoreId("datastore-123");
// Create a LibraryModel that represents a local library backed on a datastore.

var libraryModel = new LibraryModel();
libraryModel.SetName("AcmeLibrary");
libraryModel.SetStorageBackings(new List<StorageBacking>() { libraryBacking });
Querying Content Libraries

You can create queries to find libraries that match your criteria. You can also retrieve a list of all libraries or
only the libraries of a specific type.
n Listing All Content Libraries on page 35

You can retrieve a list of all content library IDs in your virtual environment, regardless of their type,
by using the Library service.
n Listing Content Libraries of a Specific Type on page 36

You can use the vSphere Automation API to retrieve content libraries of a specific type. For example,
you can list only the local libraries in your virtual environment.
n List Content Libraries by Using Specific Search Criteria on page 36

You can filter the list of content libraries and retrieve only the libraries that match your specific criteria.
For example, you might want to publish all local libraries with a specific name.
Listing All Content Libraries

You can retrieve a list of all content library IDs in your virtual environment, regardless of their type, by
using the Library service.
You can use the list function to retrieve all local and subscribed libraries in your system.
.NET Example of Retrieving a List of All Content Libraries

This example shows how you can retrieve a list of all local and subscribed content libraries in your virtual
environment.
...
// Create a vSphere
Automation session (not shown).
// Access the Library Service.
var libraryService = ServiceManager.VapiConnection.GetService<Library>();
// List the visible content libraries.
Console.WriteLine("List of all library identifiers: ");

foreach (var libId in libraryService.List())
{
Console.WriteLine(libId);
}
VMware, Inc. 35
Listing Content Libraries of a Specific Type

You can use the vSphere Automation API to retrieve content libraries of a specific type. For example, you
can list only the local libraries in your virtual environment.
If you want to retrieve only a list of the local libraries, you must retrieve the LocalLibrary service and use
the list function on the LocalLibrary service. To list only subscribed libraries, you must retrieve the
SubscribedLibrary service and call the list function on the SubscribedLibrary service.
List Content Libraries by Using Specific Search Criteria

You can filter the list of content libraries and retrieve only the libraries that match your specific criteria. For
example, you might want to publish all local libraries with a specific name.
Prerequisites
Verify that you have access to the Library service.
Procedure
1 Create a FindSpec instance and specify your search criteria.
2 Call the find function on the Library service.

All content libraries that match your search criteria are listed.
.NET Example of Retrieving a List of All Local Libraries with a Specific Name
This example retrieves a list of all local libraries with the name AcmeLibrary that exist in your virtual
environment.
...
// Create a FindSpec instance to set your search criteria.
var findSpec = new vmware.content.LibraryTypes.FindSpec();
// Filter the visible content libraries by using a library name.
findSpec.SetName("AcmeLibrary");
findSpec.SetType(vmware.content.LibraryModel.LibraryType.LOCAL)
List<String> libIds = libraryService.Find(findSpec);
Content Libraries
The Content Library API provides services that allow you to create and manage content libraries
programmatically. You can create a local library and publish it for the entire virtual environment. You can
also subscribe to use the contents of a local library and enable automatic synchronization to ensure that you
have the latest content.
n Create a Local Content Library on page 37

You can create a local content library programmatically by using the vSphere Automation API. The
API allows you to populate the content library with VM and vApp templates. You can use these
templates to deploy virtual machines or vApps in your virtual environment.
36 VMware, Inc.
n Publish an Existing Content Library on page 38

To make the library content available for other vCenter Server instances across the
vSphere Automation environment, you must publish the library. Depending on your workflow, select
a method for publishing the local library. You can publish a local library that already exists in your
vSphere Automation environment.
n Publish a Library at the Time of Creation on page 39

You can publish a local library at the time of creation to enable other libraries to subscribe and use the
library content.
n Subscribe to a Content Library on page 39

You can subscribe to public content libraries. The source objects for a public content library can be: a
library created on a vCenter Server 6.0 instance, a catalog created on a vCloud Director 5.5 instance, or
a third-party library. When you subscribe to a library, you must specify the backing storage for the
library content. You must also provide the correct user name and password if the library requires basic
authentication.
n Synchronize a Subscribed Content Library on page 41

When you subscribe to a published library, you can configure the settings for downloading and
updating the library content.
n Editing the Settings of a Content Library on page 42

You can update the settings of content library types in your virtual environment by using the
vSphere Automation API.
n Removing the Content of a Subscribed Library on page 42

You can free storage space in your virtual environment by removing the subscribed library content
that you no longer need.
n Delete a Content Library on page 43

When you no longer need a content library, you can invoke the delete method on either the
LocalLibrary or the SubscribedLibrary service depending on the library type.
Create a Local Content Library

You can create a local content library programmatically by using the vSphere Automation API. The API
allows you to populate the content library with VM and vApp templates. You can use these templates to
deploy virtual machines or vApps in your virtual environment.
Procedure
1 Create a StorageBacking instance and define the storage location.
2 Create a LibraryModel instance and set the properties of the new local library.
3 Access the LocalLibrary object which is part of the vSphere Automation API service interfaces.
4 Call the create function on the LocalLibrary object and pass the LibraryModel as a parameter.
.NET Example of Creating a Local Content Library

This example creates a local library with name AcmeLibrary , which is stored on the local file system where
vCenter Server runs.
...
// Create a StorageBacking instance to back the library content on the local file system.
VMware, Inc. 37

libraryBacking.SetType(vmware.content.library.StorageBacking.Type.OTHER);
libraryBacking.SetStorageUri(new Uri("file:///tmp"));
// Create a LibraryModel that represents a local library.

libraryModel.SetType(vmware.content.LibraryModel.LibraryType.LOCAL);
libraryModel.SetName("AcmeLibrary");
// Access the LocalLibrary service by using the vSphere

Automation endpoint.
LocalLibrary localLibraryService = ServiceManager.VapiConnection.GetService<LocalLibrary>();
// Call the Create method of the LocalLibrary service

// passing the LibraryModel instance as an argument.
var libraryId = localLibraryService.Create(Guid.NewGuid().ToString(), libraryModel);
Publish an Existing Content Library

To make the library content available for other vCenter Server instances across the vSphere Automation
environment, you must publish the library. Depending on your workflow, select a method for publishing the
local library. You can publish a local library that already exists in your vSphere Automation environment.
Procedure
1 Retrieve a reference to the LocalLibrary service.
2 Retrieve an existing local library by using the library ID.
3 Create a PublishInfo instance to define how the library is published.
4 Specify the authentication method to be used by a subscribed library to authenticate to the local library.
You can enable either basic authentication or no authentication. Basic authentication requires a user
name and password.
5 (Optional) If you publish the library with basic authentication, you must specify a user name and
password for the PublishInfo instance, which must be used for authentication.
Important Use the predefined user name vcsp or leave the user name undefined. You must set only a
password to protect the library.
6 Specify that the library is published.
7 Use the retrieved local library to configure it with the PublishInfo instance.
8 Update the properties of the LibraryModel object returned for the local library.
.NET Example of Publishing an Existing Local Library

This example shows how you can publish a local library, which already exists in your virtual environment.
...
// Access the LocalLibrary service.

var localLibraryService = ServiceManager.VapiConnection.GetService<LocalLibrary>();
// Retrieve an existing local library.
38 VMware, Inc.
var libraryModel = localLibraryService.Get(libraryId);

var publishInfo = new PublishInfo();
// Configure how the local library is published by using BASIC authentication.

publishInfo.SetUserName("vcsp");
publishInfo.SetPassword("password".ToCharArray());
publishInfo.SetAuthenticationMethod(PublishInfo.AuthenticationMethod.BASIC);
// Set the local library to published and update the library instance.
publishInfo.SetPublished(true);
libraryModel.SetPublishInfo(publishInfo);
localLibraryService.Update(libraryModel.GetId(), libraryModel);
Publish a Library at the Time of Creation

You can publish a local library at the time of creation to enable other libraries to subscribe and use the
library content.
Procedure
1 Retrieve the LocalLibrary service.
2 Create a PublishInfo instance to define how the library is published.

3 Specify the authentication method to be used by a subscribed library to authenticate to the local library.
You can enable either basic authentication or no authentication on the library. Basic authentication
requires a user name and password.
4 (Optional) If you publish the library with basic authentication, you must specify a user name and
password for the PublishInfo instance, which must be used for authentication.
Important Use the predefined user name vcsp or leave the user name undefined. You must set only a
password to protect the library.
5 Create a LibraryModel instance and configure the instance.
6 Set the library type to local and use the configured PublishInfo instance to set the library to published.
7 Define where the content of the local library is stored by using the StorageBacking class.
8 Create a published local library.
Subscribe to a Content Library

You can subscribe to public content libraries. The source objects for a public content library can be: a library
created on a vCenter Server 6.0 instance, a catalog created on a vCloud Director 5.5 instance, or a third-party
library. When you subscribe to a library, you must specify the backing storage for the library content. You
must also provide the correct user name and password if the library requires basic authentication.
Note If you subscribe to libraries created with basic authentication on a vCenter Serverinstance, make sure
that you pass vcsp as an argument for the user name.
Procedure
1 Create a StorageBacking instance to define the location where the content of the subscribed library is
stored.
VMware, Inc. 39
2 Create a SubscriptionInfo instance to define the subscription behavior of the library.
a Provide the mechanism to be used by the subscribed library to authenticate to the published
library.
You can choose between no authentication and basic authentication depending on the settings of
the published library you subscribe to. If the library is published with basic authentication, you
must set basic authentication in the SubscriptionInfo instance. Set the user name and the
password of the SubscriptionInfo instance to match the credentials of the published library.
b Provide the URL to the endpoint where the metadata of the published library is stored.
c Define the synchronization mechanism of the subscribed library.
You can choose between two synchronization modes: automatic and on demand. If you enable
automatic synchronization for a subscribed library, both the content and the metadata are
synchronized with the published library. To save storage space, you can synchronize the subscribed
library on demand and update only the metadata for the published library content.
d Set the thumbprint that is used for validating the certificate of the published library.
3 Create a LibraryModel instance and set the library type to subscribed

(LibraryModel.LibraryType.SUBSCRIBED).
4 Access the SubscribedLibrary service and create the subscribed library instance.
.NET Example of Subscribing to a Published Library

This example demonstrates how to subscribe to a published library.
...
...
// Create a StorageBacking instance to store

// the contents of the subscribed library on the local file system.
libraryBacking.SetType(StorageBacking.Type.OTHER);
libraryBacking.SetStorageUri(new Uri("/mnt/nfs/cls-root"));
// Create a new SubscriptionInfo object to define the subscription

// behavior of the library.
var subscriptionInfo = new SubscriptionInfo();
subscriptionInfo.SetAuthenticationMethod(SubscriptionInfo.AuthenticationMethod.BASIC);
subscriptionInfo.SetUserName("libraryUser");
subscriptionInfo.SetPassword("password".ToCharArray());
subscriptionInfo.SetSubscriptionUrl(new
Uri("https://www.acmecompary.com/library_inventory/lib.json"));
// Specify that the content of the subscribed library will be downloaded immediately
subscriptionInfo.SetAutomaticSyncEnabled(true);
// Set an SHA-1 hash of the SSL certificate of the remote endpoint.

subscriptionInfo.SetSslThumbprint("9B:00:3F:C4:4E:B1:F3:F9:0D:70:47:48:E7:0B:D1:A7:0E:DE:60:A5");
// Create a new LibraryModel object for the subscribed library.

libraryModel.SetType(vmware.content.LibraryModel.LibraryType.SUBSCRIBED);
40 VMware, Inc.
libraryModel.SetName("SubscrLibrary");
// Attach the storage backing and the subscription info to the library model.
libraryModel.SetSubscriptionInfo(subscriptionInfo);
// Create the new subscribed library.

SubscribedLibrary subscribedLibService =
ServiceManager.VapiConnection.GetService<SubscribedLibrary>();
var clientToken = Guid.NewGuid().ToString();
var subscribedLibId = subscribedLibService.Create(clientToken, libraryModel);
Synchronize a Subscribed Content Library

When you subscribe to a published library, you can configure the settings for downloading and updating the
library content.
n You can enable automatic synchronization of the subscribed library and download a copy of the content
of the local library immediately.
n You can save storage space and download only the metadata for the items that are part of the local
library.
To ensure that your subscribed library contains the most recent published library content, you can force a
synchronization task.
Procedure
1 Access the SubscribedLibrary vSphere Automation service.
2 Retrieve the subscribed library ID from the SubscribedLibrary service.
3 Force the synchronization of the subscribed library.
The synchronization operation depends on the update settings of the subscribed library. If the subscribed
library is configured to update only on demand, only the metadata of the library items will be synchronized.
VMware, Inc. 41
Editing the Settings of a Content Library

You can update the settings of content library types in your virtual environment by using the
vSphere Automation API.
Table 6‑1. Options for Updating a Content Library

Content Library Types Option
Local content library You can change the settings of a local library before calling
the update function on the LocalLibrary object:
n Before a library is published, you can edit the following
settings:
n The name of a local library that is retrieved by
using the LocalLibrary object
n The human-readable description of a local library
retrieved by using the LocalLibrary object
n After a library is published, you must first retrieve the
PublishInfo instance of the published library you
want. You can use the instance to configure the
following settings.
n Unpublish the local library.
n Change the authentication method of the library.
n Change the password that must be used for
authentication.
Subscribed content library You can edit the settings of a subscribed library if you
retrieve the SubscriptionInfo instance associated with it.
To apply the changes, you must update the library by using
the SubscribedLibrary object.
You can configure the following settings:
n The authentication method required by the local
library
n The user name and password of the subscribed library
for authentication to the local library
n The method for synchronizing the metadata and the
content of the subscribed library
n The thumbprint used for validating the SSL certificate
of the local library
Removing the Content of a Subscribed Library

You can free storage space in your virtual environment by removing the subscribed library content that you
no longer need.
You can create a subscribed library with the option to download the library content on demand. As a result,
only the metadata for the library items is stored in the associated with the subscribed library storage. When
you want to deploy a virtual machine from a VM temple in the subscribed library, you must synchronize the
subscribed library to download the entire published library content. When you no longer need the VM
template, you can call the evict function on the SubscribedLibrary service. You must provide the
subscribed library ID to this function. As a result, the subscribed library content that is cached on the
backing storage is deleted.
If the subscribed library is not configured to synchronize on demand, an exception is thrown. In this case the
subscribed library always attempts to have the most recent published library content.
42 VMware, Inc.
Delete a Content Library

When you no longer need a content library, you can invoke the delete method on either the LocalLibrary or
the SubscribedLibrary service depending on the library type.
Procedure
1 Access the SubscribedLibrary or the LocalLibrary service by using the vSphere Automation Endpoint.
2 Retrieve the library ID you want to delete.
3 Call the delete function on the library service and pass the library ID as argument.
All library items cashed on the storage backing are removed asynchronously. If this operation fails, you
must manually remove the content of the library.
Library Items
A library item groups multiple files within one logical unit. You can perform various tasks with the items in
a content library.
You can upload files to a library item in a local library and update existing items. You can download the
content of a library item from a subscribed library and use the item, for example, to deploy a virtual
machine. You can remove the content of a library item from a subscribed library to free storage space and
keep only the metadata of the library item. When you no longer need local library items, you can delete
them and they are removed from the subscribed library when a synchronization task is completed.
You can create a library item from a specific item type, for example .ovf. The Content Library service must
support the library item type to handle the item correctly. If no support is provided for a specified type, the
Content Library service handles the library item in the default way, without adding metadata to the library
item or guiding the upload process.
n Create an Empty Library Item on page 44

You can create as many library items as needed and associate them with a local content library.
n Querying Library Items on page 44

You can perform numerous query operations on library items.
n Edit the Settings of a Library Item on page 45

You can edit the name, description, and type of a library item.
n Upload a File from a Local System to a Library Item on page 46

You can upload different types of files from a local system to a library item that you want to use in the
n Upload a File from a URL to a Library Item on page 48

vSphere Automationenvironment.
n Download Files to a Local System from a Library Item on page 49

You might want to download files to a local system from a library item and then make changes to the
files before you use them.
n Synchronizing a Library Item in a Subscribed Content Library on page 51

The items in a subscribed library have features that are distinct from the items in a local library.
Synchronizing the content and the metadata of an item in a subscribed library depends on the
synchronization mechanism of the subscribed library.
VMware, Inc. 43
n Removing the Content of a Library Item on page 51

You can remove the content from a library item to free space on your storage.
n Deleting a Library Item on page 51

You can remove a library item from a local library when you no longer need it.
Create an Empty Library Item

You can create as many library items as needed and associate them with a local content library.
Procedure
1 Access the Item service by using the vSphere Automation endpoint.
2 Instantiate the ItemModel class.
3 Define the settings of the new library item.
4 Associate the library item with an existing local library.
5 Invoke the create function on the Item object to pass the library item specification and the unique client
token.
What to do next
Upload content to the new library item. See “Upload a File from a Local System to a Library Item,” on
page 46 and “Upload a File from a URL to a Library Item,” on page 48.
.NET Example of Creating a Library Item

This example shows how to create a library item that stores an ISO image file.
...
...
// Create an instance of the ItemModel class and specify the item settings.
var libItemSpec = new ItemModel();
libItemSpec.SetName("ESXi ISO image");
libItemSpec.SetDescription("ISO image with the latest security patches for ESXi 5.5 as of
2/3/2015");
libItemSpec.SetType("iso");
// Associate the item with an existing content library.

libItemSpec.SetLibraryId("<content_library_ID>");
// Create the new Item instance, using the specified model.

Item libItemService = ServiceManager.VapiConnection.GetService<Item>();
var itemID = Guid.NewGuid().ToString();
var newItem = libItemService.Create(itemID, libItemSpec);
Querying Library Items

You can perform numerous query operations on library items.
You can retrieve a list of all items in a library, retrieve a library item that has a specific type or name, and
find a library item that is not cached on the disk. You can then update the library item content from the
subscribed library.
44 VMware, Inc.
List Library Items

You can use the list method of the Item object to retrieve a list of all items in a particular library.
Prerequisites
Verify that you have access to the Item service.
Procedure
1 Retrieve the ID of the content library whose items you want to list.
2 List the items of the specific library.
3 Retrieve a list of the files that belong to a library item.
You can see an example query operation in the code example for “Edit the Settings of a Library Item,” on
page 45. The beginning of the example lists the items of a published library and prints a list with the names
and size of each file in the listed items.
List Library Items That Match Specific Criteria

You can filter the items contained in a library and retrieve only the items matching specific criteria. For
example, you might want to remove or update only specific items in a library.
Prerequisites
Procedure
1 Create an instance in the FindSpec class.
2 Specify the filter properties by using the FindSpec instance.
3 List the items matching the specified filter.
A list of items matching the filter criteria is created as a result.
Edit the Settings of a Library Item

You can edit the name, description, and type of a library item.
Prerequisites
Procedure
1 Retrieve the item that you want to update.
2 Create an ItemModel instance.
3 Change the human-readable name and description of the library item.
4 Update the library item with the configured item model.
VMware, Inc. 45
.NET Example of Changing the Settings for a Library Item

This example shows how to find an item using the item name and then shows how to change the name and
description of the retrieved item.
...
...
var libItemService = ServiceManager.VapiConnection.GetService<Item>();

var itemFilesService = ServiceManager.VapiConnection.GetService<
vmware.content.library.item.File>();
// List the items in a published library

foreach (var itemId in libItemService.List(libraryId))
{
// List the files uploaded to each library item and print their names and size
foreach (var singleFile in itemFilesService.List(itemId))
{
Console.WriteLine("Library item with name " + singleFile.GetName() +
" has size " + singleFile.GetSize());
}
// Change the name and description of the library item with the specified name
var singleItem = libItemService.Get(itemId);
if (singleItem.GetName().Equals("simpleVmTemplate"))
{
var libItemUpdated = new ItemModel();
libItemUpdated.SetName("newItemName");
libItemUpdated.SetDescription("Description of the newItemName");
libItemService.Update(singleItem.GetId(), libItemUpdated);
}
}
Upload a File from a Local System to a Library Item

Prerequisites
n Create an empty library item. See “Create an Empty Library Item,” on page 44.
n Verify that you have access to the UpdateSession and File services.
Procedure
1 Create an UpdateSessionModel instance to track the changes that you make to the library item.
2 Create an update session by using the UpdateSession service.
3 Create an AddSpec instance to describe the upload method and other properties of the file to be
uploaded.
4 Create the request for changing the item by using the File service.
46 VMware, Inc.
5 Upload the file that is on the local system.
6 Complete and delete the update session to apply the changes to the library item.
.NET Example of Uploading Files to a Library Item from the Local System
This example shows how to upload an ISO image file from the local system to a library item.
...
using vmware.content.library.item;
using vmware.content.library.item.updatesession;
...
// Create a new library item as described in “.NET Example of Creating a Library Item,” on page 44
...
// Create an UpdateSessionModel instance to track the changes you make to the item.
var updateSessionModel = new UpdateSessionModel();
updateSessionModel.SetLibraryItemId(newItem);
// Create a new update session.

var uploadService = ServiceManager.VapiConnection.GetService<UpdateSession>();
String sessionId = uploadService.Create(Guid.NewGuid().ToString(), updateSessionModel);
try
{
// Instantiate the vmware.vcloud.suite.samples.common.HttpHelper class.
var httpClient = new HttpClient(true);
// Create a new AddSpec instance to describe the properties of the file to be uploaded.
var fileSpec = new vmware.content.library.item.updatesession.FileTypes.AddSpec();
fileSpec.SetName("ESXi patch as of 10/2/2015");
fileSpec.SetSourceType(vmware.content.library.item.updatesession.FileTypes.SourceType.PUSH);
var uploadFileService =
ServiceManager.VapiConnection.GetService<vmware.content.library.item.updatesession.File>();
var fileInfo = uploadFileService.Add(sessionId, fileSpec);
var uploadUri = fileInfo.GetUploadEndpoint().GetUri();
var file1 = System.IO.File.Create("/updates/esxi/esxi_patch.iso");
// Use the HTTP PUT request to upload the file to the library item.
httpClient.Upload(file1, uploadUri.ToString());
// Mark the upload session as completed.

uploadService.Complete(sessionId);
}
finally
{
uploadService.Delete(sessionId);
}
VMware, Inc. 47
Upload a File from a URL to a Library Item

vSphere Automationenvironment.
Prerequisites
n Create an empty library item. See “Create an Empty Library Item,” on page 44.
n Verify that you have access to the UpdateSession and File services.
Procedure
1 Create an UpdateSessionModel instance to track the changes that you make to the library item.
2 Create an update session by using the UpdateSession service.
3 Create a file specification to describe the upload method and other properties of the file to be uploaded.
4 Specify the location of the file to be uploaded by creating a TransferEndpoint instance.
5 Add the file source endpoint to the file specification.
6 Create a request for changing the item by using the configured file specification.
7 Complete the update session to apply the changes to the library item.
.NET Example of Uploading a File from a URL to a Library Item

This example shows how to upload a file from a URL to a library item.
....
using vmware.content.library.item.updatesession;
...
// Create a new library item. See “Create an Empty Library Item,” on page 44.
...
// Create an UpdateSessionModel instance to track the changes you make to the item.
var updateSessionModel = new UpdateSessionModel();
updateSessionModel.SetLibraryItemId(newItem);
// Create a new update session.

var uploadService = ServiceManager.VapiConnection.GetService<UpdateSession>();
var sessionId = uploadService.Create(Guid.NewGuid().ToString(), updateSessionModel);
// Create a new AddSpec instance to describe the properties of the file to be uploaded.
var fileSpec = new vmware.content.library.item.updatesession.FileTypes.AddSpec();
fileSpec.SetName("ESXi patch as of 10/2/2015");
fileSpec.SetSourceType(vmware.content.library.item.updatesession.FileTypes.SourceType.PULL);
// Specify the location from which the file is uploaded to the library item.
var endpoint = new TransferEndpoint();
endpoint.SetUri(new Uri("http://www.acme.com/patches_ESXi55/ESXi_patch.iso"));
fileSpec.SetSourceEndpoint(endpoint);
var uploadFileService =
ServiceManager.VapiConnection.GetService<vmware.content.library.item.updatesession.File>();
48 VMware, Inc.
uploadFileService.Add(sessionId, fileSpec);
// Mark the session as completed.

uploadService.Complete(sessionId);
Download Files to a Local System from a Library Item

You might want to download files to a local system from a library item and then make changes to the files
before you use them.
Procedure
1 Create a download session model to specify the item, which contains the file that you want to
download.
2 Access the File service and retrieve the file that you want to export to your system within the new
download session.
3 Prepare the files that you want to download and wait until the files are in the prepared state.
4 Retrieve the download endpoint URI of the files.
5 Download the files with an HTTP GET request.

6 Delete the download session after all files are downloaded.
.NET Example of Downloading Files from a Library Item to Your Local System
This example shows how you can download individual files from a library item to your local file system.
...
using System;
using System.IO;
using vmware.content.library.item.downloadsession;
// Access the DownloadSession service.

var downloadSessionService = ServiceManager.VapiConnection.GetService<DownloadSession>();
// Create a new download session model.

var downloadSessionModel = new DownloadSessionModel();
downloadSessionModel.SetLibraryItemId(libItem.GetId());
var downloadSessionId =
downloadSessionService.Create(Guid.NewGuid().ToString(),downloadSessionModel);
var httpClient = new HttpClient(true);
// Access the File service and retrieve the files you want to export.
var downloadFileService =
ServiceManager.VapiConnection.GetService<vmware.content.library.item.downloadsession.File>();
for (var downloadFileInfo in downloadFileService.List(downloadSessionId))
{
// Make sure all files are in prepared state before you precede with the downloading
operation
downloadFileService.Prepare(downloadSessionId, downloadFileInfo.GetName(),
vmware.content.library.item.downloadsession.FileTypes.EndpointType.HTTPS);
VMware, Inc. 49
long timeOut = 360;

long endTime = DateTime.Now.Millisecond + timeOut * 1000;
Thread.sleep(5000);
var expectedStatus =vmware.content.library.item.downloadsession.File.PrepareStatus.PREPARED;
downloadFileInfo = downloadFileService.Get(downloadSessionId,downloadFileInfo.GetName());
var currentStatus = downloadFileInfo.GetStatus();
if (currentStatus == expectedStatus)
{
// When the files are prepared, you can retrieve the download information for each file.
downloadFileInfo = downloadFileService.Get(downloadSessionId,
downloadFileInfo.GetName());
var downloadUrl = downloadFileInfo.GetDownloadEndpoint().GetUri().ToString();
// Execute an HTTP GET request and pass the URLs to the endpoints of the download files.
using(var inputStream = httpClient.DownloadFile(downloadUrl))
{
var tmpDirInfo = Directory.CreateDirectory("tmp");
var fullLocalPath = Path.Combine(tmpDirInfo.FullName, downloadFileInfo.GetName());
using(var localFile = File.Create(fullLocalPath))
{
// Copy the files to the directory on your machine

inputStream.CopyTo(localFile);
}
}
}
else
{
while (endTime > DateTime.Now.Millisecond)
{
downloadFileInfo = downloadFileService.Get(downloadSessionId,
downloadFileInfo.GetName());
currentStatus = downloadFileInfo.GetStatus();
if (currentStatus == expectedStatus)
{
return;
}
else if (currentStatus ==
vmware.content.library.item.downloadsession.File.PrepareStatus.ERROR)
{
Console.WriteLine("DownloadSession Info : " +
downloadSessionService.Get(downloadSessionId));
throw new Exception("Error while waiting for download file status to be
PREPARED...");
}
}
}
}
50 VMware, Inc.
Synchronizing a Library Item in a Subscribed Content Library

The items in a subscribed library have features that are distinct from the items in a local library.
Synchronizing the content and the metadata of an item in a subscribed library depends on the
synchronization mechanism of the subscribed library.
Table 6‑2. Options for Synchronizing a Library Item

Synchronization Type of the Subscribed
Library Description
Synchronized on demand If the subscribed library is synchronized on demand, you can use the
sync method on the SubscribedItem service and pass as arguments
the library item ID and true. When you perform the task, both the
item metadata and the content are synchronized. To synchronize only
the metadata of the item, pass the library ID and false as arguments
to the method.
Not synchronized on demand If the subscribed library is not synchronized on demand, you can use
the sync method on the SubscribedItem service and pass as
argument the item ID. In this case, the content of the item is always
synchronized and the Boolean value is ignored when the call is
executed.
Synchronized automatically If the subscribed library is synchronized automatically, you can also
use the sync method to force the synchronization of an item. Method
execution depends on whether the subscribed library is synchronized
on demand.
Removing the Content of a Library Item

You can remove the content from a library item to free space on your storage.
If you create a subscribed library with the option to synchronize library content on demand, only the
metadata for the library items is stored. When you want to use the items in the library, you must force
synchronization on the items to download their content. When you no longer need the files in an item, you
can remove the cached content of the library item and free storage space. To achieve this task use the evict
function of the SubscribedItem object.
Deleting a Library Item

You can remove a library item from a local library when you no longer need it.
To remove a library item from a library, you can call the delete method on the Item object and pass the
library item ID as an argument. The item content is asynchronously removed from the storage.
You cannot remove items from a subscribed library. If you remove an item from a local library, the item is
removed from the subscribed library when you perform a synchronization task on the subscribed library
item.
VMware, Inc. 51
52 VMware, Inc.
Content Library Support for OVF
Packages 7
Open Virtualization Format (OVF) is an industry standard that describes metadata about a virtual machine
image in an XML format. An OVF package includes an XML descriptor file and optionally disk images,
resource files (such as ISO files), manifest files, and certificate files.
With the vSphere Automation API, you can use the virtual machine (VM) and vApp templates from an OVF
package in a content library to deploy VMs and virtual appliances on hosts, resource pools, and clusters.
You can also use the API to create OVF packages in content libraries from virtual appliances and VMs on
hosts, resource pools, and clusters.
When you create library items to store OVF packages, you must set the item type to ovf. You can use the
objects and methods provided by the Content Library API to manage OVF packages. To comply with the
specific standards of the OVF packages, the vSphere Automation API provides the LibraryItem class.
n “Using the Content Library Service to Handle OVF Packages,” on page 53
n “Using the LibraryItem Service to Execute OVF-Specific Tasks,” on page 54
Using the Content Library Service to Handle OVF Packages

You can upload an OVF package to a library item by using the UpdateSession interface. The location of the
OVF package determines whether you can pull the content from a URL or push the content directly to a
content library.
For information about uploading content to library items, see “Upload a File from a Local System to a
Library Item,” on page 46 and “Upload a File from a URL to a Library Item,” on page 48.
To download the files that are included in an OVF package to your local file system, use the
DownloadSession interface. For more information, see “Download Files to a Local System from a Library
Item,” on page 49.
Upload an OVF Package from a URL to a Library Item

You can upload an OVF package from a Web server to a library item.
Procedure
1 Create an empty library item.
2 Create an update session object.
3 Create an AddSpec object to describe the properties and the upload location of the descriptor file of the
OVF package.
VMware, Inc. 53
4 Link the AddSpec object to the update session.
All files that are included in the OVF package are automatically uploaded.
5 Complete the asynchronous transfer.
Upload an OVF Package from a Local File System to a Library Item

You can upload an OVF package from a local file system. This procedure describes how to use the AddSpec
object after you have created a library item and initiated an update session.
Procedure
1 Create a library item.
2 Create an update session.
3 Create an AddSpec object to describe the properties and the upload location of the descriptor file of the
OVF package.
4 Link the AddSpec object to the update session.
5 Create an AddSpec object for each VMDK file included in the OVF package.
6 Add all AddSpec objects to the update session.

Steps 5 and 6 must be repeated for each VMDK file included in the OVF package.
7 Initiate the upload operation.
8 Complete the update session.
9 Delete the session.
Using the LibraryItem Service to Execute OVF-Specific Tasks

You can deploy virtual machines and vApps on hosts, clusters, and resource pools in your environment. You
use the VM templates and vApp templates from an OVF package that is stored as a content library item.
With the vSphere Automation API, you can use the LibraryItem service to deploy virtual machines and
virtual applications from library items that contain OVF packages. You can also use the LibraryItem
vSphere Automation service to create library items from existing virtual machines and virtual appliances.
Deploy a Virtual Machine or Virtual Appliance from an OVF Package in a

Content Library
You can use the LibraryItem service to deploy a virtual machine or virtual appliance on a host, cluster, or
resource pool from a library item.
Procedure
1 Create a DeploymentTarget instance to specify the deployment location of the virtual machine or virtual
appliance.
2 Instantiate the ResourcePoolDeploymentSpec class to define all necessary parameters for the deployment
operation.
For example, you can assign a name for the deployed virtual machine or virtual appliance, and accept
the End User License Agreements (EULAs) to complete the deployment successfully.
3 (Optional) Retrieve information from the descriptor file of the OVF package and use the information
during the OVF package deployment.
4 Invoke the deploy method on the LibraryItem service.
54 VMware, Inc.
Chapter 7 Content Library Support for OVF Packages
5 Verify the outcome of the deployment operation.
Create an OVF Package in a Content Library from a Virtual Machine

You can create library items from existing virtual machines or virtual appliances. Use those library items
later to deploy virtual machines and virtual appliances on hosts and clusters in the vSphere Automation
environment.
Procedure
1 Create a DeployableIdentity instance to specify the source virtual machine or virtual appliance to be
captured in an OVF package.
2 Create a CreateTarget instance to identify the content library where the OVF package is stored.
3 Create a CreateSpec instance to specify the properties of the OVF package.
4 Initiate a synchronous create operation by invoking the create function of the LibraryItem service.
5 Verify the results of the create operation.
VMware, Inc. 55
56 VMware, Inc.
Tagging Service 8
The vSphere Automation Tagging Service supports the definition of tags that you can associate with
vSphere objects or vSphere Automation resources. vSphere has a tagging feature but no public API to
manage tags. With the vSphere Automation SDK, you can manage tags programmatically.
For example, to tag your VMs by guest operating system type, you might create a category called
operating system, and specify that it applies to VMs only. You might also specify that only a single tag can
be applied to a VM at any time. The tags in this category might be Windows, Linux, and Mac OS.
n Creating Tags on page 57

When you create a tag, you create a tag category and create a tag under the category. After you create
the tag, you can associate the tag with an object.
n Creating Tag Associations on page 59

After you create a tag category and create a tag within the category, you can associate the tag with a
vSphere managed object or a vSphere Automation resource. An association is a simple link that
contains no data of its own. You can enumerate objects that are attached to a tag or tags that are
attached to an object.
n Updating a Tag on page 60

To update a tag, you must create an update spec for the tag. In the update spec, you set values for the
fields to be changed, and omit values for the other fields. When you do an update operation using the
update spec, only the fields that contain values are changed.
Creating Tags
When you create a tag, you create a tag category and create a tag under the category. After you create the
tag, you can associate the tag with an object.
Tags and categories have global scope. The Platform Services Controller stores tags and categories makes
them available to any vCenter Server system that is registered with the Platform Services Controller.
n Creating a Tag Category on page 58

You create tags in the context of a tag category. You must create a category before you can add tags
within that category.
n Creating a Tag on page 58

After you create a tag category, you can create tags within that category
VMware, Inc. 57
Creating a Tag Category

You create tags in the context of a tag category. You must create a category before you can add tags within
that category.
A tag category has the following properties:
n name
n description
n cardinality, or how many tags it can contain
n the types of elements to which the tags can be assigned
You can associate tags with both vSphere API managed objects and VMware vSphere Automation API
resources.
.Net Example of Creating a Tag Category

This example is based on code in the TagLifecycle.cs sample file. This file is located in the following
vSphere Automation SDK for .NET directory: client/samples/src/Samples/vmware/samples/tagging.
The category Create() function returns an identifier that you use when you create a tag for that category.
The empty set for the associable types indicates that any object type can be associated with a tag in this
category.
using vmware.cis.tagging;
using System.Collections.Generic;
var categoryStub = myStubFactory.CreateStub<Category>(myStubConfiguration);
// Set up a tag category create spec.

var createSpec = new CategoryTypes.CreateSpec();
createSpec.SetName(“favorites”);
createSpec.SetDescription(“My favorite virtual machines.”);
createSpec.SetCardinality(CategoryModel.Cardinality.MULTIPLE);
HashSet<String> associableTypes = new HashSet<String>();
createSpec.SetAssociableTypes(associableTypes);
// Create the tag category.

String newCategoryId = categoryStub.Create(createSpec);
Creating a Tag
After you create a tag category, you can create tags within that category
A tag has the following properties:
n name
n description
n category ID
58 VMware, Inc.
Chapter 8 Tagging Service
.NET Example of Creating a Tag

This example creates a tag specification and then uses it to create the tag. The tag specification references the
category identifier that was returned from the category create operation. Use the returned tag identifier for
subsequent operations on the tag.
vSphere Automation SDK for .NET directory:
client/samples/src/Samples/vmware/vcloud/suite/samples/cis/tagging/
var tagStub = myStubFactory.CreateStub<Tag>(myStubConfiguration);
// Set up a tag create spec.

var createSpec = new TagTypes.CreateSpec();
createSpec.SetName(“red”);
createSpec.SetDescription(“My favorite color”);
createSpec.SetCategoryId(newCategoryId);
String tagId = tagStub.Create(spec);
Creating Tag Associations

After you create a tag category and create a tag within the category, you can associate the tag with a vSphere
managed object or a vSphere Automation resource. An association is a simple link that contains no data of
its own. You can enumerate objects that are attached to a tag or tags that are attached to an object.
Tag associations are local to a vCenter Server instance. When you request a list of tag associations from a
vCenter Server system, it enumerates only the associations that it has stored.
When you associate a tag with an object, the object's type must match one of the associable types specified
for the category to which the tag belongs.
n Assign the Tag to a Content Library on page 59

After you create a tag, you can assign the tag to a vSphere Automation resource.
n Assign a Tag to a Cluster on page 60

After you create a tag, you can assign the tag to a vSphere managed object. Tags make the inventory
objects in your virtual environment more sortable and searchable.
Assign the Tag to a Content Library

After you create a tag, you can assign the tag to a vSphere Automation resource.
Procedure
1 Construct a dynamic object identifier for the library.
The dynamic identifier includes the type and ID of the object.
2 Attach the tag to the content library.
VMware, Inc. 59
.Net Example of Assigning a Tag to a Content Library

This example assigns a tag to a content library.
using vmware.vapi.std;
// 1 - Create a dynamic type ID for the content library.

DynamicID libraryDynamicId = new DynamicID(Library.RESOURCE_TYPE,
myLibrary.GetId());
// 2- Attach the tag to the ClusterComputeResource managed object.

var tagAssociationStub = myStubFactory.CreateStub<TagAssociation>(myStubConfiguration);
tagAssociationStub.Attach(myLibrary.GetId(),
libraryDynamicId);
Assign a Tag to a Cluster

After you create a tag, you can assign the tag to a vSphere managed object. Tags make the inventory objects
in your virtual environment more sortable and searchable.
This procedure describes the steps for applying tag a to a cluster object in your inventory.
Prerequisites
Obtain the managed object identifier for the specified cluster.
To get the managed object identifier of the ClusterComputeResource, you must access vCenter Server by
using the vSphere Web Services API. For more information about how to access Web Services, see “Create a
Web Services Session,” on page 29.
Procedure
1 Construct a dynamic object identifier for the cluster.
The dynamic identifier includes the type and ID of the managed object reference.
2 Attach the tag to the cluster.
Updating a Tag
To update a tag, you must create an update spec for the tag. In the update spec, you set values for the fields
to be changed, and omit values for the other fields. When you do an update operation using the update spec,
only the fields that contain values are changed.
For example, you might use a timestamp in a tag description to identify a resource's last reconfiguration.
After reconfiguring the resource, you update the tag description to contain the current time.
.NET Example of Updating a Tag Description

vSphere Automation SDK for .NET directory: client/samples/src/Samples/vmware/samples/tagging.
using System;
// Format current time.

String newDescription = String.format(“Server tag updated at ({0}).”, DateTime.Now);
// Create update spec ta change Description field.
60 VMware, Inc.
Chapter 8 Tagging Service
TagTypes.UpdateSpec updateSpec = new TagTypes.UpdateSpec();

updateSpec.SetDescription(newDescription);
// Apply update spec to tag.

var tagStub = myStubFactory.CreateStub<Tag>(myStubConfiguration);
tagStub.Update(myTagId, updateSpec);
VMware, Inc. 61
62 VMware, Inc.
Virtual Machine Configuration and
Operations 9
A virtual machine is a software computer that, like a physical computer, runs an operating system and
applications. The virtual machine consists of a set of specification and configuration files and is backed by
the physical resources of a host. Each virtual machine encapsulates a complete computing environment and
runs independently of the underlying hardware.
Starting with vSphere 6.5, you can configure virtual machine settings and perform power operations
through the vSphere Automation SDK for .NET.
n “Filtering Virtual Machines,” on page 63
n “Create a Virtual Machine,” on page 63
n “Configuring a Virtual Machine,” on page 64
n “Performing Virtual Machine Power Operations,” on page 65
Filtering Virtual Machines

You can retrieve a list of virtual machines that match a specific filter or a group of up to one thousand virtual
machines available in a specific vCenter Server instance.
You can retrieve a list of up to one thousand virtual machine IDs for a single vCenter Server instance by
filtering them based on a specific requirement, such as a host, cluster, datacenter, or resource pool on which
the VMs are running.
Call the list methods of the VM service to retrieve only a list of the virtual machines that match your specific
criteria. The method takes as parameter the VMTypes.FilterSpec instance that you can use to describe the
virtual machine filter.
Create a Virtual Machine

You can create a virtual machine by using the VM.create method. The method takes as parameter a
CreateSpec instance that allows you to specify the attributes of the virtual machine.
To create a virtual machine you must specify the virtual machine attributes by using the CreateSpec class.
For example, you can specify a name, boot options, networking, and memory for the virtual machine. See
“Configuring a Virtual Machine,” on page 64.
All attributes are optional except the virtual machine placement information that you must provide by using
the PlacementSpec class. Use the virtual machine placement specification to set the datastore, cluster, folder,
host, or resource pool of the created virtual machine and make sure that all these vSphere objects are located
in the same data center in a vCenter Server instance.
For more information refer to the API Reference documentation inside the SDK.
VMware, Inc. 63
Configuring a Virtual Machine

You can configure a virtual machine during creation. You can also reconfigure an existing virtual machine
by adding or changing the type of the storage controllers, configure the virtual disks, boot options, CPU and
memory information, and networks.
Name and Placement

You specify the display name and the location of the virtual machine by using the CreateSpec and
PlacementSpec classes.
When you create your virtual machine, use the setName method of the CreateSpec class to pass as argument
the display name of the virtual machine.
You must create also a PlacementSpec instance that describes the location of the virtual machine in regards to
the resources of a given vCenter Server instance. Use the setPlacement(PlacementSpec placement) method
of the CreateSpec class to set the placement information for the virtual machine. You can set one or all of the
following vSphere resources: datastore, cluster, folder, host, and resource pool.
Boot Options
You can configure the boot options of a virtual machine by using the setBoot(CreateSpec boot) method of
the CreateSpec class.
The method takes as argument the BootTypes.CreateSpec class. You can select one of the following settings
when booting the virtual machine:
n Delay - Indicates a delay in milliseconds before starting the firmware boot process when the virtual
machine is powered on.
n Retry - Indicates whether the virtual machine automatically retries to boot after a failure.
n Retry delay - Indicates a delay in milliseconds before retrying the boot process after a failure.
n Enter setup mode - If set to true, indicates that the firmware boot process automatically enters BIOS
setup mode the next time the virtual machine boots. The virtual machine resets this flag to false once it
enters setup mode.
n EFI legacy boot - If set to true, indicates that the EFI legacy boot mode is used.
Operating System
The guest operating system that you specify affects the supported devices and available number of virtual
CPUs.
You specify the guest operating system by using the setGuestOS(GuestOS guestOS) method of the
VMTypes.CreateSpec class. The GuestOS class defines the valid guest OS types that you can use to configure a
virtual machine.
CPU and Memory

The CreateSpec class allows you to specify the CPU and memory configuration of a virtual machine.
To change the CPU and memory configuration settings, use the CpuTypes.UpdateSpec and
MemoryTypes.UpdateSpec classes.
64 VMware, Inc.
Chapter 9 Virtual Machine Configuration and Operations
CPU Configuration
You can set the number of CPU cores in the virtual machine by using the setCount method of the
CpuTypes.UpdateSpec class. The supported range of CPU cores depends on the guest operating system and
virtual hardware version of the virtual machine. If you set CpuTypes.Info.getHotAddEnabled() and
CpuTypes.Info.getHotRemoveEnabled() to true, you allow virtual processors to be added or removed from
the virtual machine at runtime.
Memory Configuration
You can set the memory size of a virtual machine by using the setSizeMiB method of the
MemoryTypes.UpdateSpec class. The supported range of memory sizes depends on the configured guest
operating system and virtual hardware version of the virtual machine. If you set
MemoryTypes.UpdateSpec.setHotAddEnabled() to true while the virtual machine is not powered on, you
enable adding memory while the virtual machine is running.
Networks
You configure network settings so that a virtual machine can communicate with the host and with other
virtual machines. When you configure a virtual machine, you can add network adapters (NICs) and specify
the adapter type.
You can add virtual Ethernet adapters to a virtual machine by using the VMTypes.CreateSpec.setNics
method. Pass as argument a List of EthernetTypes.CreateSpec objects that provide the configuration
information of the created virtual Ethernet adapters. You can set the MAC address type to
EthernetTypes.MacAddressType.MANUAL, EthernetTypes.MacAddressType.GENERATED, or
EthernetTypes.MacAddressType.ASSIGNED. Select MANUAL to specify the MAC address explicitly.
You can specify also the physical resources that back a virtual Ethernet adapter by using the
EthernetTypes.BackingSpec.setType method. The method takes as argument one of the following types:
EthernetTypes.BackingType.STANDARD_PORTGROUP, HOST_DEVICE, DISTRIBUTED_PORTGROUP, or OPAQUE_NETWORK.
Performing Virtual Machine Power Operations

You can start, stop, reboot, and suspend virtual machines by using the methods of the Power class.
A virtual machine can have one of the following power states:
n PowerTypes.State.POWERED_ON - Indicates that the virtual machine is running. If a guest operating

system is not currently installed, you can perform the guest OS installation in the same way as for a
physical machine.
n PowerTypes.State.POWERED_OFF - Indicates that the virtual machine is not running. You can still update
the software on the physical disk of the virtual machine, which is impossible for physical machines.
n PowerTypes.State.SUSPENDED - Indicates that the virtual machine is paused and can be resumed. This
state is the same as when a physical machine is in standby or hibernate state.
To perform a power operation on a virtual machine, you can use one of the methods of the Power class.
Before you call one of the methods to change the power state of a virtual machine, you must first check the
current state of the virtual machine by using the Power.get method. Pass as argument the virtual machine
identifier.
Following is a list if the power operations:
n Power.start - Powers on a powered off or suspended virtual machine. The method takes as argument
the virtual machine identifier.
n Power.stop - Powers off a powered on or suspended virtual machine. The method takes as argument
the virtual machine identifier.
VMware, Inc. 65
n Power.suspend - Pauses all virtual machine activity for a powered on virtual machine. The method takes
as argument the virtual machine identifier.
n Power.reset - Shuts down and restarts the guest operating system without powering off the virtual
machine. Although this method functions as a stop method that is followed by a start method, the two
operations are atomic with respect to other clients, meaning that other power operations cannot be
performed until the reset method completes.
Java Example of Powering On a Virtual Machine

This example is based on the code in the EthernetConfiguration.java sample that is located in the following
vSphere Automation SDK for Java
directory, /client/samples/java/vmware/samples/vcenter/vm/hardware/ethernet.
import com.vmware.vcenter.vm.Power;
import vmware.samples.common.SamplesAbstractBase;
import vmware.samples.vcenter.helpers.VmHelper;
...
private String vmName;
private String vmId;
private Power powerService;
...
this.powerService = vapiAuthHelper.getStubFactory().createStub(
Power.class, this.sessionStubConfig);
this.vmId = VmHelper.getVM(vapiAuthHelper.getStubFactory(),
sessionStubConfig,
vmName);
this.powerService.start(this.vmId);
...
66 VMware, Inc.
Index
Symbols content library storage 34

.Net example 60 list, query 35
.NET example local content library 34
connecting to the Lookup Service 20 subscribed library 34
retrieving service endpoints on a vCenter content library items, downloading 49
Server instance 21 content library overview 33
retrieving service registration object 20 content library storage, .NET example 34
retrieving vSphere Automation Endpoint 23 CPU and memory 64
Retrieving a vCenter Server ID by using the create tag, .Net example 59
Lookup Service 22 create tag category, .Net example 58
retrieving a vSphere Automation Endpoint on a creating tags 57
vCenter Server Instance 23 creating a local content library, creating local
retrieving vCenter Server ID 22 content libraries 37
creating a virtual machine 63
A creating connection objects, accessing
about 7 services 31
accessing vSphere Automation services 31 creating libraries, .NET example 37
assign tag to content library 60 creating vSphere Automation sessions, user
authentication, retrieving SAML token 26 credentials 28
authentication mechanisms 25 creating vSphere Automation sessions, SAML
token 27
B creating vSphere Automation session SAML
token, .NET example 27
boot options 64
creating Web Services session, .NET
example 29
C
configuring virtual machines 64 D
connecting to the Lookup Service 19 deleting content libraries 43
Content Library 9 deleting library items 51
content libraries deploying VM from OVF 54
.NET list specific name 36
creating an OVF package from a VM 55 E
creating library items 55 editing content library settings 42
deploying VA from OVF 54 editing setting of a library item 45
deploying virtual appliance from OVF 54 embedded Platform Services Controller 13, 14
editing settings 42 evicting library items 51
listing all 35 external Platform Services Controller 13, 14
listing all .NET example 35
listing specific types 36 F
OVF support 53 filtering for service endpoints 18
search criteria 36 filtering library items 45
subscribing 39 filtering virtual machines 63
subscribing to 41
content libraries, publishing 39 J
content library Java example 66
content library items 34
VMware, Inc. 67
L S
library items SAML token, retrieving 26
creating 44 SAML token session 27
creating .NET 44 security context objects 27
deleting 51 service endpoints 17, 18
downloading .NET 49 service registration 19
editing 45 service endpoint filters 18
editing .NET 46 service registration object 19
filtering 45 SSO endpoint 18
removing 51 subscribe to library, .NET example 40
synchronizing 51 subscribing to a content library 39
uploading files 48 supported programming languages
uploading .NET 47, 48 .NET 11
library items list 45 Java 11
library items, listing 44 Perl 11
library items, searching for 44 Python 11
library items, uploading content 46 Ruby 11
listing library items 45 synchronizing library items 51
local system, downloading files 49
local system, uploading a file 46 T
looking up for services 17 tag associations, assign tag to content library 59
Lookup Service, service endpoints 20 tagging service 57
Tagging Service 9
N tags
name and placement 64 associations 59
create tag 58
O create tag category 58
operating system 64 update description 60
OVF package, uploading from a URL 53 tags, assigning, assigning tags 60
OVF support, content libraries 53
U
update tag, .Net example 60
P
uploading a file from a local system 46
Platform Services Controller 13, 14
uploading an OVF from a local file system 54
power on virtual machine 65
uploading files to library items 48
powering on a virtual machine 66
uploading OVF from a URL 53
predefined service endpoints 18
programming languages 11
V
protocol connection objects 31
vCenter Server 13
protocol factory objects 31
vCenter Service endpoint 18
publishing a library at the time of creation 39
vCenter Single Sign-On Endpoint 18
publishing content libraries, .NET example 38
virtual environment 13
virtual machine networks 65
R
virtual machine configuration and operations 63
removing content from subscribed library 42
virtualization layer 13
REST 11
vSphere 13
retrieving multiple service endpoints 20
vSphere components 13
retrieving node ID 22
vSphere deployment 14
retrieving SAML token, .NET example 26
vSphere services 13
retrieving service endpoints 17, 20
vSphere Automation endpoint 18, 23
retrieving the vSphere Automation 23
vSphere Automation Endpoint 13
retrieving vCenter Server ID 22
vSphere Automation SDK 9
68 VMware, Inc.
Index
vSphere Automation SDKs

client application 9
development environment 9
sample applications 9
vSphere deployment configurations 14
vSphere Web Services, creating sessions 29
VMware, Inc. 69
70 VMware, Inc.

Vsphere Automation SDK 65 Net Programming Guide

Uploaded by

Copyright:

Available Formats

Vsphere Automation SDK 65 Net Programming Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Vsphere Automation SDK 65 Net Programming Guide

Uploaded by

Copyright:

Available Formats

VMware vSphere Automation SDK

for .NET Programming Guide

This document supports the version of each product listed and

About vSphere Automation SDK for .NET Programming Guide 7

1 Introduction to the vSphere Automation SDKs 9

2 Components of the vSphere Automation Virtualization Layer 13

3 Retrieving Service Endpoints 17

5 Accessing vSphere Automation Services 31

6 Content Library Service 33

Querying Content Libraries 35

7 Content Library Support for OVF Packages 53

9 Virtual Machine Configuration and Operations 63

This chapter includes the following topics:

n “vSphere Automation SDKs Overview,” on page 9

n “Supported Programming Languages,” on page 11

vSphere Automation SDKs Overview

Figure 1‑1. Communication Model of vSphere Automation API Client Applications

Platform Services Controller

Client vCenter Server

vSphere API Services

SDK Developer Setup

Supported Programming Languages

n vSphere Automation SDK for Java

n vSphere Automation SDK for Python

n vSphere Automation SDK for .NET

n vSphere Automation SDK for Perl

n vSphere Automation SDK for Ruby

n vSphere Automation SDK for REST

This chapter includes the following topics:

n “Components and Services of a Virtual Environment,” on page 13

n “vSphere Deployment Configurations,” on page 14

Components and Services of a Virtual Environment

Services Installed with Platform Services Controller

Services Installed with vCenter Server

vSphere Deployment Configurations

vCenter Server with an Embedded Platform Services Controller

Figure 2‑1. vCenter Server with Embedded Platform Services Controller

Platform Services Controller

vCenter Server with an External Platform Services Controller

Figure 2‑2. vCenter Server with External Platform Services Controller

Platform Services Controller

VM or Physical Server VM or Physical Server

vCenter Server vCenter Server

Content Library Content Library

VMware ESXi VMware ESXi VMware ESXi VMware ESXi

Workflow for Retrieving Service Endpoints

This chapter includes the following topics:

n “Filtering for Predefined Service Endpoints,” on page 18

n “Filter Parameters for Predefined Service Endpoints,” on page 18

n “Retrieve Service Endpoints on vCenter Server Instances,” on page 20

n “Retrieve a vCenter Server ID by Using the Lookup Service,” on page 22

n “Retrieve a vSphere Automation Endpoint on a vCenter Server Instance,” on page 23

Filtering for Predefined Service Endpoints

Lookup Service Registration Filters

Table 3‑1. Service Registration Filter Parameters

LookupServiceRegistrationServiceType product= "com.vmware.cis" vSphere Automation namespace.

type="cs.vapi" Identifies the

LookupServiceRegistrationEndpointType type="com.vmware.vapi.endpo Specifies the endpoint path for

protocol= Identifies the protocol that will