Table of Contents
Advertisement
Quick Links
vCloud SDK for .NET Developer's Guide
VMware vCloud SDK 1.0
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-000470-00
Advertisement
Table of Contents
Related Manuals for VMware VCLOUD SDK 1.0 - FOR NET DEVELOPERS GUIDE
Summary of Contents for VMware VCLOUD SDK 1.0 - FOR NET DEVELOPERS GUIDE
- Page 1 SDK for .NET Developer’s Guide VMware vCloud SDK 1.0 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.
- Page 2 VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.
-
Page 3: Table Of Contents
About This Book 5 About the vCloud SDK for .NET 7 vCloud Object Taxonomy 7 vCloud SDK for .NET Design 9 Setting Up for .NET Development 11 Prerequisites 11 Download and Install the vCloud SDK for .NET 12 Hello vCloud: A Structured Workflow Example 13 Running the HellovCloud Example 13 Logging In and Getting an Organization List 14 Getting References to the vDC and Catalog 14 Upload an OVF Package to Create a vApp Template 14 Add the vApp Template to a Catalog 16 Instantiate the vApp Template 16 Operate the vApp 17 Using the Examples 19 Building the Examples 19 Running the Examples 19 Index 21 VMware, Inc. - Page 4 SDK for .NET Developer’s Guide VMware, Inc.
-
Page 5: About This Book
.NET framework. To view the current version of this book as well as all VMware API and SDK documentation, go to http://www.vmware.com/support/pubs/sdk_pubs.html. Revision History This guide is revised with each release of the product or when necessary. A revised version can contain minor or major changes. Table 1 summarizes the significant changes in each version of this guide. Table 1. Revision History Revision Description 01NOV10 Version 1.0. Amendments and minor corrections to Beta content. 29SEP10 Version 1.0 (Beta) Intended Audience This guide is intended for software developers who are building vCloud API applications, including interactive clients of VMware Cloud Director. This guide assumes you are familiar with the C# programming language, the .NET framework, Representational State Transfer (REST) and RESTful programming conventions, the Open Virtualization Format (OVF) Specification, and VMware virtual machine technology. Familiarity with other technologies such as XML, HTTP, and the Windows or Linux operating systems is also assumed. VMware Technical Publications Glossary VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs. Document Feedback VMware welcomes your suggestions for improving our documentation. Send your feedback to docfeedback@vmware.com. VMware, Inc. - Page 6 SDK for .NET Developer’s Guide Technical Support and Education Resources The following sections describe the technical support resources available to you. To access the current versions of other VMware books, go to http://www.vmware.com/support/pubs. Online and Telephone Support To use online support to submit technical support requests, view your product and contract information, and register your products, go to http://communities.vmware.com/community/developer. Support Offerings To find out how VMware support offerings can help meet your business needs, go to http://www.vmware.com/support/services. VMware Professional Services VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides offerings to help you assess, plan, build, and manage your virtual environment. To access information about education classes, certification programs, and consulting services, go to http://www.vmware.com/services. VMware, Inc.
-
Page 7: About The Vcloud Sdk For .Net
PUT requests are used to create or modify an object, and HTTP DELETE requests are typically used to delete an object. The vCloud SDK for .NET is a C# language binding for the vCloud API. It provides C# class libraries and a set of example applications. The classes and functions in the library encapsulate the interfaces, objects, and operations that the vCloud API supports, while preserving its RESTful approach and compatibility with the HTTP protocol family. This vCloud SDK for .NET Developer’s Guide provides information about setting up the SDK in a development environment, and information about building and running the example applications included in the SDK. This chapter includes the following topics: “vCloud Object Taxonomy” on page 7 “vCloud SDK for .NET Design” on page 9 vCloud Object Taxonomy The vCloud SDK for .NET defines a set of objects common to cloud computing environments. Figure 1‐1 shows the principal object types. vCloud Organizations A vCloud contains one or more organizations. A vCloud organization is a unit of administration for a collection of users, groups, and computing resources. Users authenticate at the organization level, supplying credentials established by an organization administrator when the user was created or imported. vCloud Users and Groups An organization can contain an arbitrary number of users and groups. Users can be created by the organization administrator or imported from a directory service such as LDAP. Groups must be imported from the directory service. Permissions within an organization are controlled through the assignment of rights and roles to users and groups. vCloud Networks An organization can be provisioned with one or more networks. These organization networks can be configured to provide services such as DHCP, NAT, and firewalls. VMware, Inc. - Page 8 Catalogitem vApp vApp Catalogitem template Catalogitem Media Media Network users groups TasksList Network vCloud Virtual Datacenters A vCloud virtual datacenter (vDC) is an allocation mechanism for resources such as networks, storage, CPU, and memory. In a vDC, computing resources are fully virtualized, and can be allocated based on demand, service level requirements, or a combination of the two. There are two kinds of vDCs: Provider vDCs. These vDCs contain all the resources available from the vCloud service provider. Provider vDCs are created and managed by vCloud system administrators. Organization vDCs. These vDCs provide an environment where virtual systems can be stored, deployed, and operated. They also provide storage for virtual media, such as floppy disks and CD ROMs. An organization administrator specifies how resources from a provider vDC are distributed to the vDCs in an organization. vCloud Catalogs Catalogs contain references to virtual systems and media images. A catalog can be shared to make it visible to other members of an organization, and can be published to make it visible to other organizations. A vCloud system administrator specifies which organizations can publish catalogs, and an organization administrator controls access to catalogs by organization members. vCloud Tasks Long‐running operations initiated by members of an organization create tasks, which are kept on the organization’s tasks list. VMware, Inc.
-
Page 9: Vcloud Sdk For .Net Design
End‐user license agreement terms for each virtual machine. Deployment lease terms (typically inherited from the containing organization) that constrain the vApp’s consumption of vDC resources Access control information specifying which users and groups can perform operations such as deploy, power on, modify, and suspend on the vApp and the virtual machines it contains. vCloud SDK for .NET Design The vCloud SDK for .NET provides object‐specific methods for creating, updating, retrieving, and deleting objects defined by the vCloud API. It also provides methods for operating virtual systems. The SDK includes the following class libraries com.vmware.vcloud.api.rest.schema provides constructor, getter, and setter methods for all objects defined by the vCloud API. com.vmware.vcloud.sdk provides methods that create, update, retrieve, and delete vCloud API objects. com.vmware.vcloud.sdk.admin provides methods that create, update, retrieve, and delete vCloud administrative API objects. com.vmware.vcloud.sdk.admin.extensions provides methods that create, update, retrieve, and delete vCloud API vSphere extension objects. com.vmware.vcloud.sdk.utility provides utility methods that simplify the implementation of clients. Many of the classes implemented in these libraries are wrapper classes whose methods access vCloud API resources using an object reference. Each vCloud API object reference includes the URL (href attribute value), resource type, and name properties that define the object. Static methods get resources by passing object references, and act as constructors for SDK wrapper objects. The vCloud SDK for .NET does not provide object lifecycle management. Every wrapper object represents the resource at the time of the GET operation. If a client makes multiple GET requests for the same resource, the client receives multiple representations of the resource wrapped in the helper object. There is no automatic refresh of the client‐side representation. It is the client’s responsibility to make new requests to get the latest values. To avoid memory leaks, the client must dispose of objects that are not in use. VMware, Inc. - Page 10 SDK for .NET Developer’s Guide VMware, Inc.
-
Page 11: Setting Up For .Net Development
Setting Up for .NET Development This chapter describes how to prepare for using the vCloud SDK for .NET, how to download the SDK, and how to install and use it. This chapter includes the following topics: “Prerequisites” on page 11 “Download and Install the vCloud SDK for .NET” on page 12 Prerequisites The vCloud SDK for .NET requires the following software to be installed on the development host: Microsoft Visual Studio 2008 or later Microsoft .NET Framework 3.5 or later Additional DLL files, as documented in the README file in the download. This document and the SDK reference documentation assume that you are familiar with the C# programming language, Microsoft .NET framework and Visual Studio, and have access to an installation of VMware vCloud Director. In addition, consider the following items: Although the vCloud SDK for .NET reference documentation provides information about the vCloud API XML schemas, which define the objects and operations that the SDK supports, familiarity with the details of the underlying objects and operations, as described in the vCloud API Programming Guide, can help you understand the structure of vCloud API objects, and how the methods in this SDK operate on those objects. Before you can run the examples, you must use the vCloud Director Web console or the vCloud API to create an organization, catalog, and vDC that the examples can use. The organization must have a user account with rights to run the examples. The predefined CatalogAuthor role should provide all the necessary rights. For more information about roles and rights, see the VMware Cloud Director Administratorʹs Guide. Several of the example programs require you to have an OVF package available on the client host. This ... -
Page 12: Download And Install The Vcloud Sdk For .Net
SDK for .NET Developer’s Guide Download and Install the vCloud SDK for .NET You can download the vCloud SDK for .NET from the VMware Web site. The SDK is distributed as a compressed archive named Vcloud.NetSDK-build.zip, where build is the build number of the SDK. To download and install the vCloud SDK for .NET In a browser, go to http://www.vmware.com/go/vcloudsdkfordotnet. In the Resources area of the vCloud SDK for .NET Community page, click the Download button. On the Download page, log in with your VMware customer credentials. Accept the license agreement to continue. Choose a download option, then click the link to start the download. When the download completes, uncompress the download package into any convenient folder on your computer. Uncompressed, the archive requires about 18 MB of disk space. The package includes the following folders: Docs: vCloud SDK for .NET reference documentation in HTML format. Samples: Example code demonstrating common use cases associated with programmatically managing virtual infrastructure. Import the package into Visual Studio. See the README file in the download for information about additional DLL files that you must obtain. VMware, Inc. -
Page 13: Hello Vcloud: A Structured Workflow Example
Running the HellovCloud Example The HellovCloud example, included in the Samples folder, demonstrates the following operations supported by the vCloud SDK for .NET: Logging in to the vCloud Uploading an OVF package to create a vApp template Adding the vApp template to a catalog Instantiating the vApp template to create a vApp Operating the vApp The file HellovCloud.txt in the Samples folder includes example program input and output. Before you can run the HellovCloud example, you must build it. For information about building the examples, see “Building the Examples” on page 19. To run the HellovCloud example, use a command of the following form: vCloudApiVersionsURL versionId user@vcloud-organization password orgName vdcName .Net HellovCloud ovfFileLocation vmdkFileLocation vmdkFileName catalogName The following options are required: vCloudApiVersionsURL is the base API URL of the vCloud. versionId is the version of the API to use. Use the value 1.0 with vCloud Director 1.0. username is the name of a vCloud Director user, in the form user@vcloud‐organization, who has rights to upload OVF, create vApp templates, create vApps, and operate vApps. VMware, Inc. -
Page 14: Logging In And Getting An Organization List
Vdc FindVdc(string orgName, string vdcName) ReferenceType orgRef = client.GetOrgRefByName(orgName); Organization org = Organization.GetOrganizationByReference(client, orgRef); ReferenceType vdcRef = org.GetVdcRefByName(vdcName); return Vdc.GetVdcByReference(client, vdcRef); Upload an OVF Package to Create a vApp Template The HellovCloud command line requires you to supply the name of an OVF descriptor file and the vmdk file that it references. This information is used in the createUploadvAppTemplate method to upload the OVF descriptor and vmdk file, create a vApp template, and return a reference to the template that can be used by other methods in the program. The createUploadvAppTemplate method and the methods it calls from the vCloud SDK for .NET class libraries implement the following workflow to upload the OVF package and create a vApp template. VMware, Inc. - Page 15 // periodically check the vAppTemplate URL, looking for ovfDescriptorUploaded="true" while (!vappTemplate.Resource.ovfDescriptorUploaded) System.Threading.Thread.Sleep(5000); vappTemplate = VappTemplate.GetVappTemplateByReference(client, vappTemplate.Reference); // when the descriptor has been uploaded, upload the VMDK file FileStream vmdkFileInputStream = File.OpenRead(vmdkFileLocation); vappTemplate.UploadFile(vmdkFileName, vmdkFileInputStream, vmdkFileInputStream.Length); vappTemplate = VappTemplate.GetVappTemplateByReference(client, vappTemplate.Reference); while (vappTemplate.Resource.status != 8) VMware, Inc.
-
Page 16: Add The Vapp Template To A Catalog
(vdc.GetAvailableNetworkRefs() != null && vdc.GetAvailableNetworkRefs().Count > 0) vAppNetworkConfigurationType.networkName = vdc.GetAvailableNetworkRefs().FirstOrDefault().name; // fill in the NetworkConfigSection NetworkConfigSectionType networkConfigSectionType = new NetworkConfigSectionType(); Msg_Type networkInfo = new Msg_Type(); networkConfigSectionType.Info = networkInfo; List<VAppNetworkConfigurationType> vAppNetworkConfigs = new List<VAppNetworkConfigurationType>(); vAppNetworkConfigs.Add(vAppNetworkConfigurationType); networkConfigSectionType.NetworkConfig = vAppNetworkConfigs.ToArray(); VMware, Inc. -
Page 17: Operate The Vapp
= vAppTemplateReference; instVappTemplParamsType.InstantiationParams = instantiationParamsType; // make the request, and get an href to the vApp in return Vapp vapp = vdc.InstantiateVappTemplate(instVappTemplParamsType); return vapp; catch ... Operate the vApp The Vapp class includes methods that perform operations on the vApp. The majority of these operations return a Task object that tracks the progress of the operation. The HellovCloud example uses these methods to cycle the vApp through the following states: Deploy the vApp using the vapp.Deploy() method. Power on the vApp using the vapp.PowerOn() method. Suspend the vApp using the vapp.Suspend() method. Power off the vApp using the vapp.PowerOff() method. Undeploy the vApp using the vapp.Undeploy() method. Delete the vApp using the vapp.Delete() method. VMware, Inc. - Page 18 SDK for .NET Developer’s Guide VMware, Inc.
-
Page 19: Using The Examples
To build the examples in Visual Studio Double‐click the file samples.sln. Click Build > Build Solution. Running the Examples Examples listed in Table 4‐1 can be run by any user with rights to create and modify catalog items and vApps. Table 4-1. User API Examples Example Name Description CatalogInventory Lists name and href for all items in all catalogs in the organization. CatalogItemCRUD Create, retrieve, update, or delete a catalog item. DiskCRUD Create, retrieve, update, or delete a virtual hard disk in a Vm object. ListAllvApps List all vApps in a vDC by name and href. ThreadSample Examples of how to implement multi‐threaded client applications that execute multiple requests in parallel. VdcInventoryCRUD List name and href for all vApps, vApp templates, and media images in all vDCs in the organization. VMware, Inc. - Page 20 SDK for .NET Developer’s Guide Examples listed in Table 4‐2 require organization administrator privileges. Table 4-2. Administrative API Examples Example Name Description CatalogCRUD Create, retrieve, update, or delete a catalog. OrganizationCRUD Create, retrieve, update, or delete an organization. Requires system administrator privileges. OrgNetworkCRUD Create, retrieve, update, or delete an organization network. RoleCRUD Create, retrieve, update, or delete a role. UserCRUD Create, retrieve, update, or delete a local user. VdcCRUD Create, retrieve, update, or delete a vDC. Each of the example folders includes a .txt file that provides an example of example program input and output. VMware, Inc.
-
Page 21: Index
OVF, to upload 13 Tasks, about 8 technical support resources 6 vApp power state changes 17 to create from template 16 to delete 17 vApp template OVF upload workflow 14 to create 13, 14 to instantiate 16 vDC, about 8 VMware, Inc. - Page 22 SDK for .NET Developer’s Guide VMware, Inc.