VMware VCLOUD SDK 1.0 - FOR NET DEVELOPERS GUIDE User manual

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

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2VMware, Inc.
vCloud SDK for .NET Developer’s 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:
[e-mail]
Copyright © 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. 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.

VMware, Inc. 3
Contents
AboutThisBook 5
1AboutthevCloudSDKfor.NET 7
vCloudObjectTaxonomy 7
vCloudSDKfor.NETDesign 9
2SettingUpfor .NETDevelopment 11
Prerequisites 11
DownloadandInstallthevCloudSDKfor.NET 12
3Hello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
4UsingtheExamples 19
BuildingtheExamples 19
RunningtheExamples 19
Index 21

vCloud SDK for .NET Developer’s Guide
4VMware, Inc.

VMware, Inc. 5
Thisbook,thevCloudSDKfor.NETDeveloper’sGuide,providesinformationaboutusingtheVMware vCloud®
SDKfor .NET.
VMwareprovidesseveralAPIsandSDKsfordifferentapplicationsandgoals.Thisbookprovidesinformation
aboutusingthevCloudSDKfor.NETfordeveloperswhoarecreatingVMwarevCloudDirectorclient
applicationsinC#usingthe .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.
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
[email protected].
About This Book
Table 1. Revision History
Revision Description
01NOV10 Version1.0.AmendmentsandminorcorrectionstoBetacontent.
29SEP10 Version1.0(Beta)

vCloud SDK for .NET Developer’s Guide
6VMware, Inc.
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. 7
1
TheVMwarevCloudAPIprovidessupportfordeveloperswhoarebuildinginteractiveclientsofVMware
vCloudDirectorusingaRESTfulapplicationdevelopmentstyle.vCloudAPIclientsandserverscommunicate
overHTTP,exchangingrepresentationsofvCloudobjects.TheserepresentationstaketheformofXML
elements.HTTPGETrequestsareusedtoretrievethecurrentrepresentationofanobject,HTTPPOSTand
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.
About the vCloud SDK for .NET 1

vCloud SDK for .NET Developer’s Guide
8VMware, Inc.
Figure 1-1. vCloud Object Taxonomy
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.
Catalog 2
Catalogitem
em
em
em
Catalog 1
Catalog 3
vDC2 Catalogitem
Catalogitem
Catalogitem
Catalogitem
users
Media
vApp
template
Media
vApp
TasksList
Organization
vDC1
Media
vApp
template
Media
vApp
Network
Network
Catalogitem
em
em
em
groups

VMware, Inc. 9
Chapter 1 About the vCloud SDK for .NET
Virtual Systems and Media Images in a vCloud
VirtualsystemsandmediaimagesarestoredinavDCandcanbeincludedinacatalog.Mediaimagesare
storedintheirnativerepresentation(ISOorfloppy).Virtualsystemsarestoredastemplates,usinganopen
standardformat(OVF1.0).Thesetemplatescanberetrievedfromcatalogsandtransformedintovirtual
systems,calledvApps,throughaprocesscalledinstantiation,whichbindsatemplate’sabstractresource
requirementstoresourcesavailableinavDC.AvAppcontainsoneormoreindividualvirtualmachines(Vm
elements),alongwithparametersthatdefineoperationaldetailssuchas:
Howthecontainedvirtualmachinesareconnectedtoeachotherandtoexternalnetworks.
Theorderinwhichindividualvirtualmachinesarepoweredonoroff.
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.
NOTE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.

vCloud SDK for .NET Developer’s Guide
10 VMware, Inc.