Developers Setup Guide

VMware vSphere Web Services SDK 5.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-000670-01

Developers Setup 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: [email protected]

Copyright 20072011 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. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

VMware, Inc.

Contents

AboutThisBook

1 AboutthevSphereWebServicesSDK 7
KnowledgeRequiredforUsingthevSphereWebServicesSDK 7 ProgrammingLanguagesSupportedbythevSphereWebServicesSDK TypesofApplicationsThatYouCanBuildUsingThisSDK 8 vSphereWebServicesSDKPackageContents 9 SDKVersionsandVMwarevSphereProductCompatibility 10 8

2 SettingUpforJavaDevelopment 11
Requirements 11 SetupInstructionsforJavaDevelopment 11 SettingUpforDevelopmentUsingJAXWS 12 SettingUpforDevelopmentUsingApacheAxis 12 SettingEnvironmentVariablesforAxisDevelopment 13 BatchFilesandShellScriptsforBuildingandRunningSamples 15 ImportingServerCertificatesintotheJavaKeystore 15 GeneratingStubsandCompilingClasses 16 PrecompiledJAXWSSamples 17 PrecompiledAxisSamples 17 UsingtheIncludedBuildScripts 17 RunningtheSimpleClientSampleApplicationtoValidateSetup 18 RunningaSampleApplicationUsingtheProvidedScripts 18 TroubleshootingSetupIssues 20

3 SettingUpforMicrosoftC#Development 21
Requirements 21 EnvironmentVariableSettings 21 SetupInstructionsforC#Development 22 BuildingtheC#Samples 22 BuildingforaChosenVersionofVisualStudio 22 IteratingtheBuildforBothVimandVim25Namespaces 23 RunningtheMicrosoft.NET(C#)VersionofSimpleClient 24 TroubleshootingSetupIssues 25

Appendix:vSphereServerCertificates

27

SecureClientServerCommunications 27 SimplifiedSecuritySetupforDevelopmentEnvironment 27 ObtainingServerCertificates 28 ObtainingCertificatesbyUsingthevSphereClient 28 ObtainingCertificatesbyConnectingDirectlytoServerSystems 29 ModifyingServerConfigurationstoSupportHTTP 29

Index 33

VMware, Inc.

Developers Setup Guide

VMware, Inc.

About This Book

Thisbook,theDevelopersSetupGuide,providesinformationaboutsettingupyourdevelopmentenvironment tousetheVMwarevSphereWebServicesSDK5.0. VMwareprovidesseveraldifferentAPIsandSDKsforvariousapplicationsandgoals.Thisbookprovides informationaboutusingthevSphereWebServicesSDKfordeveloperswhoareinterestedincreatingclient applicationsformanagingVMwarevSpherecomponentsavailableonVMwareESXiandVMwarevCenter Serversystems. ToviewthecurrentversionofthisbookaswellasallVMwareAPIandSDKdocumentation,goto http://www.vmware.com/support/pubs/sdk_pubs.html.

Revision History
Thisguideisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisguide. Table 1. Revision History
Revision 17Nov2011 24Aug2011 13Jul2010 07May2009 Description CorrectedsetupinstructionsforC#stubs. UpdatedforvSphere5.0(includedinformationonusingJAXWSbindings). MinorupdatesforvSphere4.1(newWSDLfileconfiguration,examplesyntax). RevisedreleaseoftheDevelopersSetupGuideforvSphereWebServicesSDK4.0.Servercertificatesetup informationislocatedinthereferencesection.ChangeddirectorynameforWSDLFILEenvironment variable. InitialreleaseofDevelopersSetupGuideforVMwareInfrastructureSDK2.5.

29Nov2007

Intended Audience
ThisbookisintendedforanyonewhowantstodevelopapplicationsusingtheVMwarevSphereWebServices SDK.vSphereWebServicesSDKdeveloperstypicallyincludesoftwaredeveloperscreatingclientapplications usingJavaorC#(intheMicrosoft.NETenvironment)targetingVMwarevSphere.

VMware Technical Publications Glossary

VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.

Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto [email protected].

VMware, Inc.

Developers Setup Guide

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.

Online and Telephone Support

Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and registeryourproducts,gotohttp://www.vmware.com/support.

Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto http://www.vmware.com/support/services.

VMware Professional Services

VMwareEducationServicescoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerials designedtobeusedasonthejobreferencetools.Coursesareavailableonsite,intheclassroom,andlive online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.

VMware, Inc.

About the vSphere Web Services SDK

TheVMwarevSphereWebServicesSDKincludesallthecomponentsnecessarytoworkwiththe VMwarevSphereAPI,includingWSDLfiles,samplecode,andvariouslibraries.The vSphereWebServicesSDKfacilitatesdevelopmentofclientapplicationsthattargettheVMwarevSphereAPI. WiththevSphereWebServicesSDK,developerscancreateclientapplicationstomanage,monitor,and maintainVMwarevSpherecomponents,asdeployedonESX,ESXi,andVMwarevCenterServersystems. ThisDevelopersSetupGuideprovidesinformationaboutsettingupthedevelopmentenvironmentforusing JavaandMicrosoft.NET(usingtheC#programminglanguage)tocreatenewapplications,andinformation aboutrunningthesampleapplicationsincludedwiththevSphereWebServicesSDK. Thischapterincludesthesetopics: KnowledgeRequiredforUsingthevSphereWebServicesSDKonpage 7 ProgrammingLanguagesSupportedbythevSphereWebServicesSDKonpage 8 TypesofApplicationsThatYouCanBuildUsingThisSDKonpage 8 vSphereWebServicesSDKPackageContentsonpage 9 SDKVersionsandVMwarevSphereProductCompatibilityonpage 10

Knowledge Required for Using the vSphere Web Services SDK

DevelopingapplicationswiththevSphereWebServicesSDKrequiresexpertisewithJava,C#,oranother programminglanguage.YoumustalsounderstandthefollowingWebservicesprogrammingconcepts: Webservicestechnologyprovidesoperations(alsoknownasmethodsinthecontextofclient applications).UsingthevSphereWebServicesSDKandtheprogramminglanguageofyourchoice,you cancreateclientapplicationsthatinvoketheseoperationstoperformthefullrangeofserverside managementandmonitoringtasks. TheWebservicesAPIisdefinedinWSDL(WebServicesDescriptionLanguage)files.TheWSDLfilesare usedbyclientsideWebservicesutilitiestocreateproxycode(stubs)thatclientapplicationsuseto interactwiththeserver. Clientapplicationsinvokeoperationsbycallingproxyinterfacemethods.Theclientproxyencodesan operationinvocationintoaSOAPmessageandsendsittotheserver.SOAP(SimpleObjectAccess Protocol)isaprogramminglanguageneutralXMLformat.SOAPmessagetranslationistransparentto thedeveloper. CommunicationsbetweenclientandserveroccuroverHTTPorHTTPS(secureHTTP,whichusesSSLto encryptclientservercommunications).ThedefaultisHTTPS,butyoucanconfiguretheVMwarevSphere WebservertosupportHTTP.(SeeModifyingServerConfigurationstoSupportHTTPonpage 29.) YoushouldalsoknowaboutbasicESX,ESXi,andvCenterServeroperations.SeetheVMwarevSphere Documentationpageathttp://www.vmware.com/support/pubs/vi_pubs.html.

VMware, Inc.

Developers Setup Guide

Programming Languages Supported by the vSphere Web Services SDK

BecausethevSphereAPIisbasedonWebservices,youcanuseanyprogrammingorscriptinglanguagethat providesutilitiesforgeneratingclientsidestubs(proxycode)fromWebservicesWSDLfiles.However, VMwarerecommendsusingJavaorC#,languagesforwhichSOAPtoolkitsarereadilyavailable.Also,the vSphereWebServicesSDKpackageincludessampleclientapplicationsdevelopedinbothJavaandC#. SeevSphereWebServicesSDKPackageContentsonpage 9foradditionalpackagingdetailsandforsome caveatsabouttheJavasamplesandforspecificversionrequirementsfortheJDK,theJavaAPIforXMLWeb Serviceslibraries,andtheApacheAxis1.4libraries. Table 1-1. Language and Tools Matrix for Client Application Development
Language/Tool Context Developmentenvironmentorframework Webservicesclientapplication developmenttoolset(SOAPtoolkit) Java J2SE6.0(aka,J2SE1.6J2SE1.6b22or subsequentversionrecommended) JAXWS2.1(JavaAPIforXMLWeb Services)orApacheAxis1.4 C# MicrosoftVisualStudio MicrosoftVisualC# Microsoft.NETFramework

Developers,scripters,andadministratorsusingMicrosoftPowerShellorPerlcanusethevSphereAPIthrough varioustoolkitsprovidedbyVMware.Youcanlearnmoreat http://communities.vmware.com/community/developer.

Types of Applications That You Can Build Using This SDK

ThetypesofapplicationsthatyoucandevelopusingthevSphereWebServicesSDKincludesystem administration,provisioning,andmonitoringapplicationsforVMwarevSpheresystems. TheVMwarevSphereClientapplicationandVMwarevSphereWebAccessaretwoexamplesofclient applicationsthatweredevelopedusingvSphereAPI.ThevSphereClientisatraditionalWindowsclient application.WebAccessisabrowserpluginthatisavailablethroughtheWebserverportonESX,ESXi,and vCenterServersystems. WiththevSphereWebServicesSDK,youcancreateyourownclientapplicationsthatautomatemany administration,provisioning,ormonitoringtasksassociatedwithvirtualinfrastructuremanagementand operations.HerearesomeexamplesoftheoperationaltasksthatyoucanautomateusingthevSphereAPI: Create,configure,powercycle,orsuspendvirtualmachinesexplicitlyorbyusingprofilesortemplates tofacilitatefasterprovisioning. Create,configure,andmanagevirtualdevices,suchasvirtualCDDVDdrives,virtualnetworkinterface cards,virtualswitches,andothercomponents. Connect,powercycle,anddisconnectESXandESXihostsystems. Capturethestateofavirtualmachinetoasnapshotandrestorethestateofavirtualmachinefroma snapshot,suchasinabackupapplication. Gatherstatisticsabouthostsystemandvirtualmachineperformance. Manageeventsgeneratedbytheserver,suchasthoseemittedbyalarmssetforspecificthresholds. Movevirtualmachinesbetweenhostsautomatically. Manageloadbalancingandfailoverthroughthedistributedresourcescheduler(VMwareDRS)andhigh availability(VMwareHA)subsystems.VMwareDRSandVMwareHArequirevCenterServer. Thislistisnotcomprehensive.Also,someoftheoperationspertaintotheserviceasawhole,notspecifichosts orvirtualmachines.Forexample,loadbalancingcanbeaservicewideoperationratherthanperhostor pervirtualmachineoperation.

VMware, Inc.

Chapter 1 About the vSphere Web Services SDK

vSphere Web Services SDK Package Contents

ThevSphereWebServicesSDKisazipfilethatincludes: WSDLfilesthatdefinetheAPIavailableonaVMwarevSphereserver(ESX,ESXi,andvCenterServer) Webservice. Precompiledclientsidelibraries(vim.jar,vim25.jar)availablefortestpurposesthatweregenerated fromtheWSDL.ThevSphereAPIispackagedinthevim25.jarfileandisavailableinthe SDK\vsphere-ws\wsdl\vim25subdirectory. Samplecodedemonstratingcommonusecasesassociatedwithmanagingvirtualinfrastructure.The samplecodeincludescompiledandreadytorunJavaclassfilesandbothJavaandC#sourcecodefiles. (ForC#developers,theMicrosoftVisualStudioprojectfiles(.sln)havebeenincluded.) NOTETheprecompiledJavasamples(samples.jar)havebeencompiledusingJDK1.6b22fromstubs generatedbytheJavaAPIforXMLWebServices(JAXWS)librariesinJ2SE6.0,andworkonlywiththese specificversionsofJavaandJAXWS.TouseadifferentversionofJava,oradifferentclientsideweb serviceslibrary,youmustrebuildthesamples(usingthebuildscript). ThevSphereWebServicesSDKalsocontainsprecompiledJavasamplesthathavebeencompiledusing JDK1.6usingstubsgeneratedbytheApacheAxis1.4libraries.Thesesamplesworkonlywiththese specificversionsofJavaandAxis.Toavoidaperformanceissue,useJDK 1.5.0_08orlater.SeeKnowledge Basearticle2983901,PerformanceIssue(forVISDK2.0)withJDKVersionsPriortoJDK1.5.0_08,for details. Batchfilesandshellscripts(build.bat,build.sh)thatautomatethebuildprocessforJavaandC#client applications,respectively. Batchfilesandshellscripts(run.bat,run.sh)thatfacilitaterunningtheJavasamplesfromtheWindows commandprompt. APIreferencedocumentation(vSphereAPIReference)thatprovideslanguageneutraldescriptive information(objecttypedefinitions,properties,andmethodsignatures,forexample)abouttheVMware vSphereAPIandtheobjectmodel. Accesstotechnicalpublications,including: vSphereWebServicesSDKDevelopersSetupGuide(thisbook),whichhelpsyousetupyour developmentenvironmentandrunsampleapplicationsusingeitherJavaorC# vSphereWebServicesSDKProgrammingGuide,whichprovidesconceptualandprescriptive informationabouthowtodevelopclientapplicationsusingthevSphereWebServicesSDK. Completeinformationaboutsettinguptheenvironment,andaboutgenerating,compiling,andrunning applicationsisincludedinChapter 2,SettingUpforJavaDevelopment,onpage 11,andinChapter 3, SettingUpforMicrosoftC#Development,onpage 21.

VMware, Inc.

Developers Setup Guide

SDK Versions and VMware vSphere Product Compatibility

VMwarehasreleasedseveralSDKproductstosupportvariousversionsoftheVMwarevSphereproduct family.TheVMwarevSphereWebServicesSDK5.0canbeusedwithallversionsofVMwarevSphereservers anditspredecessor,VMwareinfrastructure,includingESXi5.0,ESX/ESXi4.1,ESX/ESXi4.0, vCenterServer5.0,vCenterServer4.1/4.0,ESXServer3.5/3i/3.0.x,VirtualCenterServer2.5/2.0.x.Allversions aresupportedbyusingtheappropriateWSDLfiles,asfollows: SDK\vsphere-ws\wsdl\vim25containsWSDLfilesforusewithESXi5.0,ESX/ESXi4.1,ESX/ESXi4.0, vCenterServer4.1/4.0,ESX3.5,andVirtualCenter2.5systems.AsofvSphere4.1,thevSphereAPIWSDL definitionsaredividedintoseveralfiles.Thisarchitectureisforfutureimplementationsthatmayimport portionsofthevSphereAPI.BackwardscompatibilityisachievedbecausebothWSDLconfigurations (vim25andvimdirectories)useatoplevelfilewiththesamename(vimService.wsdl). SDK\vsphere-ws\wsdl\vimcontainsWSDLfilesforusewithESXServer3.0.1andVirtualCenter2.0. TheVMwarevSphereAPIisaWebservicethatrunsonVMwarevSphereservers,includingESX,ESXi,and vCenterServer.TheAPIexposedisthesameinallproducts.However,thevCenterServerprovidesthe followingcapabilitieswhicharenotavailablethroughanESXorESXiwebservice: Collectinghistoricalperformancedata Optimizingresources(includingmanagingdistributedresources) EnablingmigrationfromonehostsystemtoanotherbyusingVMwareVMotion Providingdistributedresourcemanagement,includingrecovery,acrossallhostsystemsunderitscontrol. IfyouattempttoinvokeanoperationonanESXorESXisystemthatissupportedonlyonthevCenterServer, theserverreturnsanotimplementedoranotsupportederrormessage.Forexample,the ExtensionManagerAPIisavailableonlyonVirtualCenterServer2.5andsubsequentreleasesofvCenter Server.AttemptingtoregisteranextensiontoanESXsystemreturnsanotsupportedfault.

10

VMware, Inc.

Setting Up for Java Development

Thischapterincludesthesetopics: Requirementsonpage 11 SetupInstructionsforJavaDevelopmentonpage 11 RunningtheSimpleClientSampleApplicationtoValidateSetuponpage 18 TroubleshootingSetupIssuesonpage 20

Requirements
DevelopingJavaWebservicesclientapplicationsusingtheVMwarevSphereWebServicesSDKrequiresthe JavaSDKandaJavaWebservicesdevelopmenttoolset.VMwarerecommendsusingJava2,StandardEdition, version6.0(J2SE1.6.x),specificallyJDK1.6b22orlater. TheJavaWebservicesdevelopmenttoolsetmustbeaSOAP(SimpleObjectAccessProtocol)implementation thatcanbedeployedtoaTomcatserver.VMwarerecommendsthatyouuseoneofthefollowingclientside webserviceslibraries: JavaAPIforXMLWebServices(JAXWS)version2.1.TheJAXWS2.1librariesareincludedwiththe JDK1.6. ApacheAxis1.4.AxisisanopensourceprojectoftheApacheWebservicesproject.YoucanobtainAxis fromtheApacheWebservicesprojectsiteathttp://ws.apache.org/axis/. NOTETheApacheAxis1.4librarieshaveaknownissuethatpreventsthemfromworkingwithJ2SE6.0 (JDK1.6).IfyouusetheAxis1.4libraries,youmustuseJ2SE5.0(JDK1.5_0_08).Supportforthe ApacheAxis1.4bindingsisdeprecatedinvSphere5.0. Youcanuseotherclientsidetoolsandlibraries,suchasIBMWebSphereandseveralopensource implementations,withthevSphereWebServicesSDK.However,onlytheJAXWSandAxisclientlibraries weretestedwiththisDevelopersSetupGuide. Thesamplesarchive(samples.jar)includesallvSphereWebServicesSDKsamples.Thesamplesinclude clientsideproxycode(stubclasses)generatedusingboththeJAXWSandApacheAxis1.4libraries.Samples usingJAXWSweregeneratedusingJDK1.6b22.SamplesgeneratedusingApacheAxis1.4weregenerated usingJDK1.5_0_08.

Setup Instructions for Java Development

Specificsetupinstructionsdependonwhetheryourdevelopmentworkstationalreadymeetssomeorallofthe requirements,whichclientsideWebservicelibraryyouplantouse,andwhetheryouplantousetheprovided samples.SpecificsetupinstructionsalsodependonwhetheryourtargetserverusestheHTTPSprotocolor HTTP.ThefollowinginstructionsassumethatthetargetserverusesHTTPS,whichisthedefaultserver configuration.

VMware, Inc.

11

Developers Setup Guide

Setting Up for Development Using JAX-WS

ThesamplesgeneratedusingJAXWSlibrariesandcompiledusingJavaJDK1.6b22includevim25.jarand samples.jar.Youcanusetheselibrarieswithoutgeneratingnewstubsandrecompilingifyouareusingthe sameversionoftheJDK. To set up a development workstation to use Java and JAX-WS 1 CreateadirectoryfortheJDK(assumingthattheJDKisnotinstalled)andforthevSphereWebServices SDKpackage.Donotusespacesinthedirectorynames,toavoidissueswithsomeoftheincludedSDK batchandscriptfiles. InstalltheJava2Platform,StandardEdition(J2SE)6.0.VMwarerecommendsusingJDK1.6b22orlater. YoucanobtaintheJ2SEfromhttp://java.sun.com/javase/downloads/. ObtaintheVMwarevSphereWebServicesSDKpackagefromtheVMwareWebsite http://www.vmware.com/download/sdk/. Unpackthecomponentsintosubdirectoriescreatedinstep1above,usingtheprovidedinstallerif appropriate.TheJ2SEusesaninstallationwizard.TheSDKzipfileunpacksintothedirectoryyouspecify. UnpackwithUsefoldernamesselected,tomaintaintheorganizationalstructure. OnUNIXdevelopmentsystems,usetheunzipcommandwiththeamodifier,toensureproper lineendingsintheshellscripts.Forexample:
unzip -a VMware-vSphere-SDK-4.1.0-251329.zip

2 3 4

ImportservercertificatesandusetheJavakeytoolutilitytocreateavmware.keystore.SeeImporting ServerCertificatesintotheJavaKeystoreonpage 15fordetails.Optionally,youcanignore servercertificateverificationforanyofthesampleJavaapplicationsbypassingthe--ignorecert argumentatruntime. CreatetheJAVAHOMEenvironmentvariable.TheJAVAHOMEenvironmentvariablemustbesettothe rootpathoftheJavaRuntimeEnvironment(JRE),suchasC:\jre1.6_0\jre. Addtheprecompiledsamplefiles(vim25.jarandsamples.jar)toyoursystemCLASSPATH environmentvariable.Asanalternative,youcanusetherun.batscript.Tousetherun.batscript,the JAVAHOMEenvironmentvariablemustbedefined. IfyouarenotusingJDK1.6b22,youmustusethebuild.bat(orbuild.sh,onLinux)togeneratestubsand compilethesamplefiles(vim25.jarandsamples.jar).Thebuildscriptsperformallnecessarytasksfor you,includingsettingtheCLASSPATHandPATHenvironmentvariables.SeeGeneratingStubsand CompilingClassesonpage 16fordetails.

6 7

RuntheJavaversionofSimpleClienttotestyoursetup.SeeRunningtheSimpleClientSample ApplicationtoValidateSetuponpage 18fordetails.

Setting Up for Development Using Apache Axis

ThesamplesgeneratedusingApacheAxis1.4librariesandcompiledusingJavaJDK1.5_0_08include vim.jar,vim25.jar,apputils.jar,andsamples.jar.Youcanusetheselibrarieswithoutgeneratingnew stubsandrecompilingifyouareusingthesesameversionsoftheJDKandAxis.

12

VMware, Inc.

Chapter 2 Setting Up for Java Development

To set up a development workstation to use Java and Apache Axis 1 Createdirectoriesforeachofthecomponentsthatyouwanttoinstall(assumingthatneitherJDKnorAxis clientisinstalled). Donotusespacesinthedirectorynames,toavoidissueswithsomeoftheincludedSDKbatchandscript files.Table 21listssomerecommendednamingconventions. Table 2-1. Recommended Directory Structures
Windows SDK Apache Axis Java 2, Standard Edition (J2SE) c:\devprojects\visdk21 c:\apache\axis c:\java\jdk1.5.0_nn c:\java\jre1.5.0_nn Linux ~\apps\visdk ~\apps\apache\axis ~\apps\java\jdk1.5.0_nn ~\apps\java\jre1.5.0_nn

InstalltheJava2Platform,StandardEdition(J2SE)5.0.VMwarerecommendsusingJDK1.5_0_08dueto improvedperformance(forJavasockets).YoucanobtaintheJ2SEfrom http://java.sun.com/javase/downloads/previous.jsp. ObtaintheApacheAxis1.4clientsideWebserviceslibrariesfromtheApacheWebservicesWebsiteat http://ws.apache.org/axis/java/releases.html. ObtaintheVMwarevSphereWebServicesSDKpackagefromVMwareWebsite http://www.vmware.com/download/sdk/. Unpackthevariouscomponentsintosubdirectoriescreatedinstep1above,usingtheprovidedinstaller ifappropriate.TheJ2SEusesaninstallationwizard.TheAxiszipfileandtheSDKunpackintothe directoryyouspecify. UnpackwithUsefoldernamesselected,tomaintaintheorganizationalstructure. OnUNIXdevelopmentsystems,usetheunzipcommandwiththeamodifier,toensureproper lineendingsintheshellscripts.Forexample:
unzip -a VMware-vSphere-WS-SDK-4.1.0-251329.zip

3 4 5

6 7 8

ImportservercertificatesandusetheJavakeytoolutilitytocreateavmware.keystore.SeeImporting ServerCertificatesintotheJavaKeystoreonpage 15fordetails. (Optional)ToignoreservercertificateverificationforanyofthesampleJavaapplications,youcanpass the--ignorecert argumentatruntimeinsteadofimportingservercertificates. ConfigureenvironmentsettingsasdetailedinSettingEnvironmentVariablesforAxisDevelopmenton page 13.TorunanyoftheJavasampleapplicationsusingtheprovidedrunscript(run.bat,run.sh),you mustsetonlyAXISHOME,JAVAHOME,VMKEYSTORE,andWBEMHOME. Usethebuild.bat(orbuild.sh,onLinux)togeneratestubsandcompileintovim.jar,vim25.jar, apputils.jar,andsamples.jar.Thebuildscriptsperformallnecessarytasksforyou,includingsetting theCLASSPATHandPATH.SeeGeneratingStubsandCompilingClassesonpage 16fordetails. NOTEIfyouareusingAxis1.4andJDK1.5,youdonotneedtousethebuildscript.Instead,addvim.jar, vim25.jar,apputils.jar,andsamples.jartoyoursystemCLASSPATH.Alternatively,setthe AXISHOME,JAVAHOME,VMKEYSTORE,andWBEMHOMEandusetherun.bat(orrun.sh).

10

RuntheJavaversionofSimpleClienttotestyoursetup.SeeRunningtheSimpleClientSample ApplicationtoValidateSetuponpage 18fordetails.

Setting Environment Variables for Axis Development

Theenvironmentvariabledefinitionssetdependonwhetheryouwanttousetheprovidedscripts (build.bat,build.sh;run.bat,run.sh).Tousetheprovidedscripts,youmustsetfourenvironment variables:AXISHOME,JAVAHOME,VMKEYSTORE,andWBEMHOME.SeeTable 22fordetails.
VMware, Inc. 13

Developers Setup Guide

Ifyoudonotwanttousethescripts,youmustsetCLASSPATHandPATHenvironmentvariablessothatthey includetheAxislibrariesandtheJ2SElibraries.Ifthesevariablesdonotalreadyexistonyourdevelopment workstation,youmustcreatethem.Table 22listsenvironmentvariablenames,directories,andfilenamesthat youmustspecificallyset.TheSDKHOMEenvironmentvariableisforconvenience. To set environment variables required by the build and run scripts 1 CreateenvironmentvariablesforAXISHOME,JAVAHOME,SDKHOME,VMKEYSTORE,and WBEMHOME,asdefinedinTable 22. ForMicrosoftWindowsdevelopmentworkstations,youmustsetSystem(ratherthanUser) environmentvariables. ForLinuxdevelopmentworkstations,youmustexportthevariablesinyouruserprofile. 2 3 TotheSystemCLASSPATH,addthecompletepathtoallAxisclientsidelibraryJARsandadditional librariesprovidedwiththeSDKspecifiedinTable 22. TotheSystemPATHenvironmentvariable,addthepathtotheAxisandJavaruntimebinaries,as specifiedinTable 22.

Table 2-2. Environment Variable Names and Required JAR and Other Files
Variable Name AXISHOME CLASSPATH Setting must Include... CompletepathtotheApacheAxisinstallationtopleveldirectory.Forexample: C:\apache\axis1.4 CompletepathstospecificJARfilesandotherlibrariesrequiredbyJavaandAxistools.Addthese specificJARfilestotheCLASSPATH(assumesthatyouhavesetupAXISHOME,JAVAHOME, andSDKHOME). %AXISHOME%\lib\axis.jar %AXISHOME%\lib\axis-ant.jar %AXISHOME%\lib\commons-discovery-0.2.jar %AXISHOME%\lib\commons-logging-1.0.4.jar %AXISHOME%\lib\jaxrpc.jar %AXISHOME%\lib\log4j-1.2.8.jar %AXISHOME%\lib\saaj.jar %AXISHOME%\lib\wsdl4j-1.5.1.jar %JAVAHOME%\lib\tools.jar %SDKHOME%\samples\Axis\java\vim.jar %SDKHOME%\samples\Axis\java\vim25.jar %SDKHOME%\samples\Axis\java\apputils.jar %SDKHOME%\samples\Axis\java\samples.jar %SDKHOME%\samples\Axis\java\lib\activation.jar %SDKHOME%\samples\Axis\java\lib\mailapi.jar %SDKHOME%\samples\Axis\java\lib\wbem.jar JAVAHOME PATH PathtotheJavaruntime(JRE)directory.Forexample: C:\jre1.5_0_08\jre AddthepathtotheJavaandtheAxisbinaryclienttoolstothesystempath.Assumingyousetup theAXISHOMEandJAVAHOMEvariables,youmustadd: %AXISHOME%\bin %JAVAHOME%\bin SDKHOME PaththetopleveldirectoryoftheunpackedSDKdownload.Forexample: C:\devprojects\visdk21\SDK\vsphere-ws\

14

VMware, Inc.

Chapter 2 Setting Up for Java Development

Table 2-2. Environment Variable Names and Required JAR and Other Files
Variable Name VMKEYSTORE Setting must Include... PathtoJavakeystore.TheVMKEYSTOREenvironmentvariableisusedbytherun.batand run.shbatchfiles.Samplepaths: VMKEYSTORE=C:\VMware-Certs\vmware.keystore[Windows] VMKEYSTORE=/root/vmware-certs/vmware.keystore[Linux] IfyouusetheignorecertargumenttorunanyJavasamples(usingtherun.bat orrun.sh script),youmuststillsettheVMKEYSTOREenvironmentvariable.Settoanylocation(youdo notneedtoimportthecertificateorcreatetheactualkeystore,though,ifyouusetheignorecert argument). WBEMHOME PathtotheAxisjavadirectory.Therun.shscriptusesthisvariabletoreferencetheWBEM(Web BasedEnterpriseManagement)Javaarchive(wbem.jar). WBEMHOME=%SDKHOME%\java\Axis\

Batch Files and Shell Scripts for Building and Running Samples
ThevSphereWebServicesSDKincludesseveralbatchfilesforWindowsandshellscriptsforLinuxthat facilitatebuildingandrunningthesampleapplications. NOTEIfyouareusingtheJAXWS2.1librarieswithJDK1.6b22(ortheAxis1.4librarieswithJDK1.5_0_08), youdonotneedtorebuildthesamples. Someofthebatchfilesareusedbyotherbatchfiles.Forexample,build.batcallsthelcp.batand clean.batscripts.Ifyoumodifythebatchfilesforanyreason,beawareofthedependenciesamongthem. Table 2-3. Batch Files and Shell Scripts for Java [..\Axis\java\ Subdirectory]
Filename build.bat build.sh Description Checksforenvironmentvariables(AXISHOME, JAVAHOME,VMKEYSTORE,andWBEMHOME)and setslocalclasspath(bycallinglcp.bat)usingthe variablesasdefined.Thebuild.batfilethencleansup existingJavafiles(bycallingclean.bat). Usage note Usethisscripttogenerateclientstubs andrebuildallsampleapplications. Successfulexecutionofbuild.bat createsthevim.jar,vim25.jar, apputils.jar,andsamples.jarfiles. Usethewflagtorecompilewithout regeneratingstubs. lcp.bat lcp.sh run.bat run.sh Setsthelocalclasspathontheworkstation.Calledby build.batandbyrun.bat. Batchfilethatenablesrunninganyofthesample applications.SetstheJavatrustStorepropertytothelocal truststoreandinvokestheJavaruntimewiththenameof theapplicationpassedasaparameter. Removesanyexistingartifactspriortobuildingthe samples,deletingJavaclassfilesinthesamplespackages andsamples.jarfile.Calledbybuildscript. Optional.Usetosetlocalclasspath. UsethisscripttorunanyJavasample applications.

clean.bat

Optional.Deletesallgeneratedsource codefiles.

Importing Server-Certificates into the Java Keystore

Thisstepisrequiredonlyifbothofthefollowingconditionsapplytoyourenvironment. Thetargetserversusethedefaultprotocol,HTTPS. Youdonotplantousethe--ignorecertcommandlineargument. Alternatively,touseHTTP(ratherthanHTTPS)andavoidtheuseofcertificatesentirely,followtheprocedure detailedinModifyingServerConfigurationstoSupportHTTPonpage 29.However,usingHTTPisnot recommendedforproductionenvironments. TheseinstructionsrequirethattheJAVAHOMEenvironmentvariableissetandthatitisaddedtothePATH environmentvariable.Theseinstructionsalsorequirethatthecertificateforeachtargetserverislocatedinthe C:\VMware-Certssubdirectory.SeeObtainingServerCertificatesonpage 28.

VMware, Inc.

15

Developers Setup Guide

To import certificates into a local Java keystore 1 2 OpentheWindowscommandpromptorLinuxshellcommand. CreatethedirectoryfortheJavacertificatestore. Createthedirectoryonly.Theactualkeystorefile,vmware.keystore,iscreatedduringtheprocessof importingthecertificates,insubsequentsteps. Table 2-4. Keystore Path
Operating System Windows Linux Path C:\VMware-Certs\vmware.keystore ~/vmware-certs/vmware.keystore

Navigatetothedirectory.Forexample,onWindowsusethefollowingdirectory:
cd vmware-certs\vmware

UsetheJavakeytoolutilitytoimportacertificate.Thesyntaxisasfollows:
keytool -import -file certificate-filename -alias server-name -keystore vmware.keystore

Forexample:
C:\VMware-Certs>keytool -import -file rui.crt -alias sdkpubs01 -keystore vmware.keystore

Apromptrequestingapasswordforthekeystoreappears:
Enter keystore password:

Createapasswordforthekeystorebyenteringitattheprompt.Thekeystoreutilitydisplaysthecertificate informationattheconsole.Forexample:
Owner: OID.1.2.840.113549.1.9.2="1183400896,564d7761726520496e632e", CN=sdkpubslab-01.vmware.com, [email protected], OU=VMware ESX Server Certificate, O="VMware, Inc.", L=Palo Alto, ST=California, C=US Issuer: OID.1.2.840.113549.1.9.2="1183400896,564d7761726520496e632e", CN=sdkpubslab-01.vmware.com, [email protected], OU=VMware ESX Server Certificate, O="VMware, Inc.", L=Palo Alto, ST=California, C=US Serial number: 0 Valid from: Mon Jul 02 11:28:17 PDT 2007 until: Mon Aug 31 11:28:17 PDT 2026 Certificate fingerprints: MD5: . . .61:35:C0:C4 SHA1: 4C:...78:B2

Attheendofthecertificateinformation,apromptdisplaysarequestforconfirmationthatthecertificate istrusted:
Trust this certificate? [no]:

TypeyesandpressEntertorespondtothepromptandimportthecertificateintothevmware.keystore keystore.Theconsoledisplaysthismessage:
Certificate was added to keystore

Repeatthisprocessforeachtargetserver.

Generating Stubs and Compiling Classes

ThevSphereWebServicesSDKincludesJavaarchivefilesforthesampleprograms.Therearetwosetsof sample.jarfiles:onesetcreatedusingJDK1.6andtheJAXWSwebserviceslibraries,andonesetcreated usingJDK1.5_0_08andtheApacheAxis1.4libraries.

16

VMware, Inc.

Chapter 2 Setting Up for Java Development

Precompiled JAX-WS Samples

TheJAXWSsamplesincludethevim25.jarandsamples.jarfilesthatwerecreatedusingtheJAXWSlibraries includedwithJDK1.6.Thesefilesarelocatedinthefollowingdirectory:
%SDKHOME%\java\JAX-WS\lib

IfyourdevelopmentenvironmentisusingtheJAXWSlibrariesandJDK1.6b22,youcanusethese precompiledlibraries.TryrunningtheSimpleClientbyfollowingtheinstructionsinRunningthe SimpleClientSampleApplicationtoValidateSetuponpage 18.

Precompiled Axis Samples

TheAxissamplesincludethevim.jar,vim25.jar,samples.jar,andapputils.jarfilesthatwerecreated usingAxis1.4andJDK1.5_0_08.Thesefilesarelocatedinthefollowingdirectory:
%SDKHOME%\java\Axis\

IfyourdevelopmentenvironmentincludesthesesameAxisandJavaversions,youcanusetheseprecompiled libraries.TryrunningtheSimpleClientbyfollowingtheinstructionsinRunningtheSimpleClientSample ApplicationtoValidateSetuponpage 18.

Using the Included Build Scripts

IfyourdevelopmentenvironmentusesdifferentversionsoftheJDKorclientsidelibrariesthantheonesused fortheprecompiledsamplefiles,youmustregeneratetheclientsideproxycode(stubs)andrecompilethem tocreateJavaarchivefiles.Thebuild.bat(orbuild.sh)scriptincludedwiththeSDKperformsallnecessary tasksforyou. Youmustregeneratethestubsunderthefollowingconditions: YouareusingtheJAXWSlibrariesandyouareusingaJavaversionotherthanJDK1.6b22.Tousethe includedbuildscripts,theJAVAHOMEenvironmentvariablemustbeset. YouareusingtheAxislibrariesandyouareusingJavaversionotherthanJDK1.5_0_08,oranAxisversion otherthanAxis1.4.Tousetheincludedbuildscripts,youmustsettheAXISHOME,JAVAHOME,and WBEMHOMEenvironmentvariables(seeSettingEnvironmentVariablesforAxisDevelopmenton page 13). To generate stubs and compile using the build.bat or build.sh script 1 2 Openacommandprompt. Navigatetothesubdirectorycontainingthebuild.batandbuild.shfiles.ForJAXWS,thisdirectoryis:
%SDKHOME%\java\JAX-WS\

ForAxis,thisdirectoryis:
%SDKHOME%\java\Axis\

VMware, Inc.

17

Developers Setup Guide

Runthebuild.bat(orbuild.sh)scriptbyenteringitsnameatthecommandprompt.
build

Theconsoledisplaysoutput,startingwithGeneratingstubsfromwsdl.Inafewminutes,theprocess completes.ThewordDoneappearsatthecommandprompt,asshowninExample 21.Thegenerating stubsfromwsdlmessageappearstwice,becausethisbuildfilegeneratesclientstubsusingbothsetsof WSDLdeclarations(foundin\vimand\vim25subdirectories). Example 2-1. Successful Stub Generation and Compilation Using build.bat Script
Generating stubs from wsdl Compiling stubs. ... Done. C:\devprojects\visdk21\SDK\vsphere-ws\java\Axis>

Whentheprocesscompletessuccessfully,theappropriatesample.jarfilesshowthecurrentdateandtime. TocompilewithoutregeneratingthestubsfromtheWSDL,usethewflagwiththebuildscript,asfollows:
build -w

Youcanrunanyofthesampleapplicationsbyfollowingtheinstructionsinthenextsection,Runningthe SimpleClientSampleApplicationtoValidateSetup.

Running the SimpleClient Sample Application to Validate Setup

Youcanquicklytestyoursetupandconnectivitybyrunningoneofthesampleapplications,suchas SimpleClient.SimpleClientisaJavaclassthatconnectstotheserverandobtainsalistingofthetoplevel inventoryentities,theirpropertiesandreferences.Youcanrunanyofthesamplesusingtherun.bat(orrun.sh) script. IfyouareusingstubsgeneratedbyJAXWS,thesescriptsrequiretheJAVAHOMEenvironmentvariabletobe set.IfyouareusingstubsgeneratedbyAxis1.4,thescriptsrequireyoutosettheAXISHOME,JAVAHOME, VMKEYSTORE,andWBEMHOMEenvironmentvariables(seeTable 22).

Running a Sample Application Using the Provided Scripts

Youcanusetherun.batorrun.shscripttorunanyoftheJavasamples.Whenyourunthescript,specifythe Javaclassforthesampleapplicationalongwiththeurl,username,andpasswordswitchesonthe commandline.IncludethecompletepackagenameintheJavaclassspecification.Thefollowingstatement showsthegeneralformatforusingtherun.batscripttoruntheSimpleClientsampleapplicationfromthe appropriateJavasamplessubdirectoryforJAXWS(%SDKHOME%\java\JAXWS\com\vmware\samples\ general\SimpleClient)orAxis (%SDKHOME%\java\Axis\com\vmware\samples\general\ SimpleClient):
run.bat com.vmware.samples.general.SimpleAgent --url https://yourFQDNservername/sdk --username username --password password [--ignorecert ignorecert]

Example 22showssampleoutputfromtheSimpleClientsampleprogram.

18

VMware, Inc.

Chapter 2 Setting Up for Java Development

Example 2-2. Sample Output of a Successful Run of SimpleClient (Precompiled Java Sample)
Object Type : Folder Reference Value : ha-folder-vm Property Name : name Property Value : vm Object Type : HostSystem Reference Value : ha-host Property Name : name Property Value : sdkpubslab-02.eng.vmware.com Object Type : ResourcePool Reference Value : ha-root-pool Property Name : name Property Value : Resources Object Type : Folder Reference Value : ha-folder-host Property Name : name Property Value : host Object Type : ComputeResource Reference Value : ha-compute-res Property Name : name Property Value : sdkpubslab-02.eng.vmware.com Object Type : VirtualMachine Reference Value : 16 Property Name : name Property Value : Windows_2K3_VM ... Object Type : Datacenter Reference Value : ha-datacenter Property Name : name Property Value : ha-datacenter Object Type : Folder Reference Value : ha-folder-root Property Name : name Property Value : ha-folder-root

To run the precompiled SimpleClient from the command prompt 1 2 OpenaWindowscommandpromptorshellpromptonLinux. NavigatetotheJavasamplessubdirectory.ForJAXWSsamples,thissubdirectoryis:
cd %SDKHOME%\java\JAXWS\samples

ForAxissamples,thissubdirectoryis:
cd %SDKHOME%\java\Axis\samples

InvoketheJavaruntime,providingthefullpackagenameoftheSimpleClient,serverURN,credentials, andJavakeyStorelocation(orthe--ignorecertargument).Thecompletesyntaxisasfollows:
java -Djavax.net.ssl.trustStore=keystore-path-or-%KEYSTORE%-environment-variable package-hierarchy-classname --url server-url --username username --password password [--ignorecert ignorecert]

Forexample:
java -Djavax.net.ssl.trustStore=%VMKEYSTORE% com.vmware.samples.general.SimpleClient --url https://example.com/sdk --username pubs --password *** --ignorecert ignorecert

NOTEIferrormessagesareraisedduetosystemheaporothermemoryissues,youcangivetheJavaVM morememory,asfollows:
java -Djavax.net.ssl.trustStore=%VMKEYSTORE% -Xms512M -Xmx1024M com.vmware.samples.general.SimpleClient https://sdkpubslab-02.eng.vmware.com/sdk --username username --password password --ignorecert ignorecert

VMware, Inc.

19

Developers Setup Guide

Troubleshooting Setup Issues

IfyouareunabletosuccessfullyruntheSimpleClient,checkyourenvironmentsettingsandallothersetup tasks.Table 25listssomecommonerrormessagesandprovidesstepsthatyoucantaketoresolvethem. Table 2-5. Java Runtime Error Messages
Symptom Exception in thread "main" java.lang.NoClassDefFoundError: com/vmware/vim/ManagedObjectReference at com.vmware.samples.general.SimpleClient.create ServiceRef(SimpleClient.java:32) at com.vmware.samples.general.SimpleClient.main(S impleClient.java:214) Caught Exception : Name : org.apache.axis.AxisFault Message : (301)Moved Permanently Trace : AxisFault faultCode: {http://xml.apache.org/axis/}HTTP faultSubcode: faultString: (301)Moved Permanently faultActor: faultNode: faultDetail: {}:return code: 301 Possible Solution VerifythattheCLASSPATHincludesallAxislibraries, directlyorthroughuseoftheAXISHOME environmentvariable. VerifythattheAXISHOMEvariablehasbeenset correctly.

Afterverifyingthattheservercertificatehasbeen importedintothelocalkeystore,runthecommand usingHTTPSandprovidethecredentials(user account,password)fortheserver.

{http://xml.apache.org/axis/}HttpErrorCode:301 (301)Moved Permanently at org.apache.axis.transport.http.HTTPSender.read FromSocket(HTTPSender.java:744)

20

VMware, Inc.

Setting Up for Microsoft C# Development

Thischapterincludesthesetopics: Requirementsonpage 21 SetupInstructionsforC#Developmentonpage 22 RunningtheMicrosoft.NET(C#)VersionofSimpleClientonpage 24 TroubleshootingSetupIssuesonpage 25

Requirements
ThevSphereWebServicesSDKincludesC#(.cs)sourcefilesandMicrosoftVisualStudioprojectfiles (solutions,or.sln)forMicrosoftVisualStudio.WebservicesclientapplicationdevelopmentforC#requires: DevelopmentenvironmentforC#,suchasMicrosoftVisualC#orMicrosoftVisualStudio. Microsoft.NETFramework,whichisincludedwithMicrosoftVisualStudio. Microsoft.NETFrameworkSoftwareDevelopmentKit.Youmustuseaversionofthe.NETSDKthat includesthecommandlineC#compiler(csc.exe).

Environment Variable Settings

ThevSphereWebServicesSDK5.0includestwoversionsoftheWSDLfiles: WSDLfilesthatsupportvim25forusewithESXi5.0,ESX/ESXi4.1,ESX/ESXi4.0,vCenterServer4.1and 4.0,ESX3.5,andVirtualCenter2.5.Seethecontentsofthedirectorysdk\wsdl\vim25. WSDLfilesthatsupportvimforusewithESXServer3.0.1andVirtualCenter2.0.Seethecontentsofthe directorysdk\wsdl\vim. ThebatchfilesusedtobuildsamplesrequireaccesstotheWSDLfiles.Ifyouintendtouseanyoftheprovided batchfiles,youmustcreatetheenvironmentvariableWSDLFILEandsetittotheWSDLdirectory (%SDKHOME%\wsdl). ThevSphereWebServicesSDKdownloadcontainsbatchfilesforsettingupthesamplesforMicrosoftVisual Studio.Thedownloadalsoincludesthesolutionfiles(.sln)files). IfyourMicrosoftsoftwaresetupvariesfromthedefaultpaths,youmustcreateaVSINSTALLDIR environmentvariableasdefinedinTable 31.

VMware, Inc.

21

Developers Setup Guide

Table 3-1. Environment Variable Names Required for Build Scripts

Variable Name VSINSTALLDIR Description LocationofMicrosoft...\Common7and ...\SDKsubdirectories. Usage Note Requiredonlyifyourdevelopmentsetupvariesfrom Microsoftdefaultinstallationpaths. Usequotationmarksaroundsubdirectorypathnamesthat includespaces.Forexample: C:\devstuff\Microsoft Visual Studio 8\Common7 C:\devstuff\Microsoft Visual Studio 8\SDK WSDLFILE LocationoftheWSDLfiles. Setto%SDKHOME%\wsdlforusewithbuildscripts.

To set environment variables required by the build script 1 2 CreatetheenvironmentvariableWSDLFILE,asdefinedinTable 31.SetSystemratherthanUser environmentvariables. IfyourMicrosoftdevelopmentand.NETsoftwarehasnotbeeninstalledusingdefaultpaths,createand settheVSINSTALLDIRenvironmentvariableasdefinedinTable 31.

Setup Instructions for C# Development

Specificsetupinstructionsdependonwhetheryourdevelopmentworkstationalreadymeetssomeorallofthe requirementsandwhetheryouplantousetheprovidedsamples. To set up a development workstation to use C# 1 InstalltheMicrosoftVisualprogrammingenvironment,suchasMicrosoftVisualC#orMicrosoftVisual Studio. VMwarerecommendsusingMicrosoftVisualStudio2005orlater,whichincludestherequired.NET Framework(2.0orlater)andimprovedversionsofWebservicesclienttools.Formoreinformation,goto http://msdn.microsoft.com. 2 3 4 ObtaintheMicrosoft.NETFramework(ifyoudonotalreadyhaveit)fromMicrosoft,at http://msdn.microsoft.com. ObtaintheVMwarevSphereWebServicesSDKpackagefromVMwareWebsiteat http://www.vmware.com/download/sdk/. Unpackthevariouscomponentsintoappropriatesubdirectories.UseMicrosoftdefaultsforMicrosoft VisualStudio,Microsoft.NETFramework,andMicrosoft.NETFrameworkSDK.

Toensurethatallpathstoalltools(wsdl.exe,csc.exe)aresetcorrectly,executethecommandscriptfrom theMicrosoft.NETSDKcommandprompt,whichisavailablefromthe.NETSDKmenu.

Building the C# Samples

InthevSphereWebServicesSDK,VMwaresuppliessampleclientsforVisualStudio2005,2008,and2010.The SDKincludesasolution(.sln)fileforeachversionofVisualStudio,suchasSamples2008.sln.Eachsolution filereferstoDLLswhosefilenamesalsoincludetheversionofVisualStudio.Forexample,Samples2008.sln referstoVimService2008.dllandVimService2008.XmlSerializers.dll.

Building for a Chosen Version of Visual Studio

ThisprocedureshowshowtobuildtheDLLsforyourchoiceofVisualStudioversion.Thefilenamesyoubuild willcontaintheactualversion,whereastheprocedureshowsfilenamesthatcontaintheplaceholderstring 20xx.SubstituteyourVisualStudioversionwhereveryousee20xxinafilename. Forexample,ifyouplantoruntheDLLsintheVisualStudio2010environment,usetheswitch /out:VimService2010.dllinstep4and/p VimService2010.dllinstep5.Thesefilenamesarereferenced intheSamples2010.slnsolutionfile.

22

VMware, Inc.

Chapter 3 Setting Up for Microsoft C# Development

Iterating the Build for Both Vim and Vim25 Namespaces

Inaddition,youmustdothesequenceofstep3throughstep8twice,substitutingtheactualvaluesVimand Vim25onsuccessivepasseswhereveryouseetheplaceholderstringVimyyinafilename.Thisisneeded becausethesolutionfilesreferenceboththeoldandthenewAPInamespaces. Forexample,ifyouplantoruntheDLLsintheVisualStudio2010environment,usetheswitch/n:VimApiin step3and/out:VimService2010.dllinstep4thefirsttimethrough.Continuetostep8,makingthesame substitutionsintheothersteps.Returntostep3andrepeatuntilstep8,usingtheswitch/n:Vim25Apiinstep 3,/out:Vim25Service2010.dllinstep4,andsoon. To build the C# samples 1 OpentheMicrosoft.NETFrameworkSDKcommandprompt(fromtheWindowsStartmenu,select Programs>Microsoft.NETFrameworkSDK>SDKCommandPrompt.Thecommandprompt launches. NavigatetotheDotNetsamplessubdirectory.
cd %SDKHOME%\samples\DotNet

GeneratetheVimService.csfilefromtheWSDL,usingwsdl.exe:
wsdl.exe /n:VimyyApi vim.wsdl vimService.wsdl

ThiscommandgeneratesVimService.cs(thedefaultoutputfile)inthecurrentdirectory,usingtheVim ortheVim25namespace. 4 CompileVimService.csintoalibrary.

csc /t:library /out:VimyyService20xx.dll VimService.cs

Thiscommandgeneratesaserializerassembly(aDLL). 5 UsethesgentooltopregenerateandcompiletheXMLserializers.
sgen /p VimyyService20xx.dll

ThiscommandoutputstheVimyyService20xx.XmlSerializers.dllfileinthecurrentdirectory.This DLLfilecontainspregeneratedXMLserializercode. ThebehaviorofthesgentoolvariesdependingonwhatyouhaveinyourMachine.configfile.For example,bydefaultsgenissupposedtooutputoptimizednondebugcode,butthatisnotalwaysthe case.Togetsomevisibilityintothetool,usethe/kflag,whichcausessgentokeepallitstemporary generatedfiles,includingthesourcefilesandcommandlineoptionfiles. 6 UsingthefindandreplacecapabilityinVisualStudiooryourfavoriteeditor,findthefollowingstring intheVimService.csfilethatyougeneratedinstep3.

[System.Xml.Serialization.XmlIncludeAttribute

Replaceitwith:
// [System.Xml.Serialization.XmlIncludeAttribute

Thiswillprevent.NETfromprocessingtheXml.Serialization.XmlIncludeAttributeattributesthat arethemaincauseoftheslowinstantiationoftheVimServiceclass.RefertotheMSDNdocumentation pageformoredetailsonthisattribute: http://msdn2.microsoft.com/enus/library/system.xml.serialization.xmlincludeattribute.aspx Ifyouareusingsomeother.NETlanguage,modifythereplacedstringtocommentitoutaccordingtothe syntaxofthatlanguage. 7 AnnotatetheVimServiceclassintheVimService.csfilethatyougeneratedinstep3,addingthe XmlSerializerAssemblyAttributetopointtothelocationoftheXMLserializerassembly.Addthis annotation:

[System.Xml.Serialization.XmlSerializerAssemblyAttribute(AssemblyName = "VimyyService20xx.XmlSerializers")]

VMware, Inc.

23

Developers Setup Guide

Youshouldendupwithsomethinglikethis:
// ... Some code here ... [System.Xml.Serialization.XmlSerializerAssemblyAttribute(AssemblyName = "VimyyService20xx.XmlSerializers")] public partial class VimService : System.Web.Services.Protocols.SoapHttpClientProtocol { // ... More code here.

TheAssemblynameshouldbethenameoftheSerializerDLLgeneratedbythesgentoolinstep5. 8 RegeneratetheVimyyService20xx.dlllibrarywiththefollowingcommand:
csc /t:library /out:VimyyService20xx.dll VimService.cs

EnsureyourapplicationreferencesthenewVimyyService20xx.dlllibrary.

Running the Microsoft .NET (C#) Version of SimpleClient

TheseinstructionsassumethatyouhavefollowedallsetupinstructionsdetailedinSetupInstructionsforC# Developmentonpage 22. To run the SimpleClient application 1 Navigatetothesubdirectorywherethecompiledobjectcodeislocated.Fromthetopleveldirectoryof theSDKdownload,thedirectoryisasfollows:
%SDKHOME%\samples\DotNet\cs\SimpleClient\bin\Debug

24

VMware, Inc.

Chapter 3 Setting Up for Microsoft C# Development

Runtheapplication,passingtothecommandlineurl,username,andpasswordswitchesalongwith thevaluesforeach.Ascoded,theSimpleClientapplication(SimpleClient.cs)requiresthatcredentials (useraccountandpassword)bepassedtotheexecutable,eveniftheserverisconfiguredtosupportHTTP. Youcanchangethesourcecodeyourselfandrecompile. Ifyoudonotprovideallthreeargumentsserveraddress,accountname,andpasswordtheexecutable generatesanerrormessageandcomestoahalt.Youmustpassallthreeargumentsusingthecommand lineswitchesasshownhere:

simpleclient --url https://sdkpubslab-01.eng.vmware.com/sdk --username useraccount -password password

Theapplicationconnectstotheserver.ABadServerCertificatemessagedisplays:

ClickYestodismissthismessageandproceedtotheserver.Aftertheclientconnectstotheserver,the outputfromserverdisplaysintheconsole(commandprompt),asshowninExample 31: Example 3-1. Sample Output of a Successful Run of SimpleClient
Object Type : Datacenter Reference Value : ha-datacenter Property Name : name Property Value : ha-datacenter Object Type : Folder Reference Value : ha-folder-root Property Name : name Property Value : ha-folder-root

Troubleshooting Setup Issues

IfyouareunabletosuccessfullyruntheSimpleClient,checkyourenvironmentsettingsandallothersetup tasks.Table 32listssomecommonerrormessagesandprovidesstepsthatyoucantaketoresolve. Table 3-2. Microsoft C# Runtime Error Messages
Symptom SimpleClient.exe https://<management-server>/sdk <user> <pass> Caught Exception : Name : WebException Message : Unable to connect to the remote server Trace : at System.Net.HttpWebRequest.GetRequestStream() at System.Web.Services.Protocols.SoapHttpClientProtocol.I nvoke(String methodName, Object[] parameters) at VimApi.VimService.RetrieveServiceContent(ManagedObject Reference _this) ... Exception disconnecting. Caught Exception : Name : NullReferenceException Message : Object reference not set to an instance of an object. Trace: ... Possible Solution CannotconnecttothewebservicefromMicrosoft.NET clientsamplethroughproxyserver.Tryadifferentserver onthesamesubnetastheclient.

VMware, Inc.

25

Developers Setup Guide

26

VMware, Inc.

Appendix: vSphere Server Certificates

Thisappendixincludesthesetopics: SecureClientServerCommunicationsonpage 27 SimplifiedSecuritySetupforDevelopmentEnvironmentonpage 27 ObtainingServerCertificatesonpage 28 ModifyingServerConfigurationstoSupportHTTPonpage 29

Secure Client-Server Communications

TheVMwarevSphereAPIisavailableasasecureWebservice.SecureWebservicemeansthat,bydefault,ESX, ESXi,andvCenterServerareconfiguredforHTTPSandsupportSSLtoencryptcommunications. ToconnecttotheserverusingHTTPS,clientapplicationsmustverifytheidentifyoftheserverbyusingthe serverscertificateduringaninitialhandshake.Theclientmustobtaintheservercertificateinadvance,sothat itisavailableduringthehandshake.SeeObtainingServerCertificatesonpage 28formoreinformation. ToconnecttotheserverusingHTTPrequiresthatyoufirstmodifythetargetserversdefaultconfigurationso thatitsupportsregularHTTPcommunications.IfyouconfiguretheserverforHTTP,youdonotneedto importtheservercertificatesontheclientdevelopmentworkstation.SeeModifyingServerConfigurationsto SupportHTTPonpage 29formoreinformation.ModifyingtheserverconfigurationtosupportHTTPaccess tothevSphereAPIisrecommendedfortestordevelopmentenvironmentsonly,notforproduction deployments.VMwarerecommendsusingthedefaultprotocol,HTTPS,forproductiondeployments.

Simplified Security Setup for Development Environment

JavadeveloperscanusetheSunFakeTrustSocketFactoryclasstoignoretheservercertificateverification processduringtheSSLhandshake.TheJavasamplesincludedwiththeSDKusethistechniquebyaccepting anoptionalcommandlineargument,--ignorecert.TheSunFakeTrustSocketFactoryclassisavailablein theAxisorg.apache.axis.components.net clientpackage. Ifyouplantousethe--ignorecertoptionorusethisautomaticservercertificateverificationtechniquein yourowncode,youdonotneedtoimportcertificates.SeeSetupInstructionsforJavaDevelopmenton page 11formoreinformation. Usethe--ignorecertoptiononlyfordevelopmentandtestingpurposes.Donotuseoutsideafirewall.Be awarethatbynotverifyingtheservercertificateduringtheSSLhandshake,theclientapplicationissubjectto maninthemiddleattacks.

VMware, Inc.

27

Developers Setup Guide

Obtaining Server Certificates

VMwareproductsusestandardX.509version3(X.509v3)certificatestoencryptsessioninformationsentover SSL(securesocketslayer)connectionsbetweenserverandclientsystems.Whenaclientapplicationinitiates anSSLsessionwiththeserver,theserversendsitscertificatetotheclientapplication,whichcheckstheX.509 certificateagainstalistofknownCertificateAuthorities(CAs)toverifytheauthenticityofthecertificate.The clientthenusestheserverspublickey(containedintheX.509certificate)togeneratearandomsymmetrickey, whichitusestoencryptallsubsequentcommunications. TheservercertificatesarecreatedautomaticallyduringtheprocessofinstallingVMwareproducts,including ESX,ESXi,andvCenterServersystems.ForESXandESXisystems,thecertificatenamematchestheDNSname oftheserver.ForvCenterServersystems,thecertificatenameisVMware.Becausethesecertificatesarenot signedbyanofficialrootCA,youmustobtaintheservercertificatefromeachserverthatyouplantotarget withyourclientapplicationandstoreitlocally. Forexample,ifyouarecreatingaclientapplicationtorunagainstthevCenterServerandanESXsystem directly(instandalonemode),youmustobtainboththevCenterServercertificateandtheESXcertificate.On theotherhand,ifyourapplicationisaimedsolelyatthevCenterServerthatmightmanageanynumberofESX systems,youmustobtainthecertificateonlyfromthevCenterServer. Youcanobtainthecertificatesinoneoftwogeneralways: DevelopersworkingontheMicrosoftWindowsplatformcanusethecertificatehandlingcapabilitiesof thevSphereClientfromthedevelopmentworkstationtoconnecttoeachESX,ESXi,orvCenterServerand acceptthecertificateintothelocalcacheandexportthecertificate.SeeObtainingCertificatesbyUsing thevSphereClientonpage 28. Developerswithaccessprivilegesonthetargetserversystemscanuseasecureshellclientutility(SCP, WinSCP,orSSH)toconnectdirectlytotheESX,ESXi,orvCenterServerandcopythecertificatesdirectly fromtheservertothedevelopmentplatform.SeeObtainingCertificatesbyConnectingDirectlytoServer Systemsonpage 29fordetails.

Obtaining Certificates by Using the vSphere Client

ThisapproachrequiresyoutoinstallthevSphereClientonyourdevelopmentmachine.ThevSphereClient leveragesthenativeMicrosoftcredentialhandlingmechanismstoallowyoutoacceptthecertificateand exportitasalocalfile. To obtain server certificates using vSphere Client 1 CreateadirectorynamedVMware-Certs(attherootlevel)forthecertificates.SeveralofthevSphereWeb ServicesSDKbatchfilesassumethispathasthelocationofthekeystoreandfailifyoudonotusethispath.
C:\VMware-Certs

2 3

InstallthevSphereClientonthedevelopmentworkstationifnecessary. LaunchthevSphereClientandthennavigatetotheESX,ESXi,orvCenterServerwebserver. ASecurityWarningmessageboxdisplaysregardingthecertifyingauthorityforthecertificate.

4 5 6 7 8 9

ClickViewCertificatetodisplaytheCertificatepropertiespage. ClicktheDetailstab. ClickCopytoFile...tolaunchtheCertificateExportwizard. SelectDERencodedbinaryX.509 (thedefault)andclickNext. ClickBrowse...andnavigatetotheC:\VMware-Certssubdirectory. Enteranameforthecertificatethatidentifiestheservertowhichitbelongs.

C:\VMware-Certs\<servername>.cer

28

VMware, Inc.

Appendix: vSphere Server Certificates

Afterobtainingthecertificatefromeachtargetserver,followtheothersetupstepsappropriateforyour programinglanguage.ForC#developers,seeSetupInstructionsforC#Developmentonpage 22.ForJava developers,seeSetupInstructionsforJavaDevelopmentonpage 11.

Obtaining Certificates by Connecting Directly to Server Systems

Thisapproachcanbeusedbydeveloperswhohaveappropriateprivilegestodirectlyconnecttothetarget server.TheseinstructionsrequireadministrativeprivilegesontheESXorvCenterServer,andassumethatyou canaccessthenecessarysubdirectory. To obtain server certificates using secure shell client application 1 Fromthedevelopmentworkstation,createadirectoryinwhichtostorecertificatesofserversthatyou wanttotargetduringdevelopment:
~\vmware-certs\

ConnecttotheESXsystemusinganSSLclientfromthedevelopmentworkstation.Remoteconnectionsto theESXserviceconsoleasrootareeffectivelydisabled,soyoumustconnectasanotheruserwith privilegesontheservertoobtainthecertificate. TheservercertificatefilenamesandlocationsofESXandvCenterServerarelistedinthefollowingtable.

Server ESX5.0 vCenterServer5.0 Directory Location for Certificate /etc/vmware/ssl/ C:\Documents and Settings\All Users\Application Data\VMware\VMware VirtualCenter\SSL\ Certificate rui.crt rui.crt

Copythecertificatesfromtheservertothecertificatesubdirectoryofthedevelopmentworkstation,using auniquefilenameforthecertificate(assumingyouarecopyingmultipledefaultcertificatesfrommultiple ESXsystems,forexample). Importtheservercertificateintothecertificatestorefollowingthespecificinstructionsforyour programminglanguage(Java,C#).SeeSettingUpforJavaDevelopmentonpage 11.

Modifying Server Configurations to Support HTTP

ESX,ESXi,andvCenterServersupportthevSphereAPIthroughtheirrespectiveWebservices(SOAP) engines.Bydefault,theseWebservicesrunonport443,asasecureWebservicethatcanbeaccessedusingSSL overHTTP(HTTPS).However,foradevelopmentenvironment,youmaywanttosimplifytheconnection processfromaclientapplicationbyconfiguringthetargetserverstosupportregular(nonSSL)HTTP. ConnectionstotheWebservicesportarehandledbyanHttpReverseProxyservice.Thereverseproxyservice handlesrequeststotheAPI(throughthe/sdkpath)andtotheManagedObjectBrowser(pathis/mob).The reverseproxyservicehasaconfigurationfile,proxy.xml,whichcanbemodifiedtospecifysupportforHTTP astheprotocolfortheWebservice.(Figure A1showsaproxy.xmlfilethathasbeenmodifiedtosupport HTTPforboththeMOBandtheSDK.) To modify the Web proxy service on ESX to support HTTP 1 2 3 4 Logintotheserviceconsoleastherootuser. Changedirectoriesto/etc/vmware/hostd. Useatexteditortoopentheproxy.xmlfile. Navigatetothelistofendpointsinthefile(identifiedbythe<EndpointList>tag)thatcontainssettingsfor theWebservicesupportingtheSDK.Thenestedtagsmaylooksomethinglikethis:
... <e id=1> <_type>vim.ProxyService.NamedPipeServiceSpec</_type> <accessMode>httpsWithRedirect</accessMode>

VMware, Inc.

29

Developers Setup Guide

<pipeName>/var/run/vmware/proxy-sdk</pipeName> <serverNamespace>/sdk</serverNamespace> </e> ...

5 6 7 8

ChangetheaccessModetohttpAndHttps.Alternatively,tocompletelydisableHTTPS,youcansetto httpOnly. (Optional)ChangethesettingfortheMOBaswell. Saveyoursettingsandclosethefile. Restartthevmware-hostdprocessbyenteringthefollowingcommand:

service mgmt-vmware restart

Example A-1. Edited proxy.xml File

<config> <EndpointList> <_length>7</_length> <_type>vim.ProxyService.EndpointSpec[]</_type> <e id=0> <_type>vim.Proxyservice.NamedPipeServiceSpec</_type> <serverNamespace>/</serverNamespace> <accessMode>httpsWithRedirect</accessMode> <pipeName>\\.\pipe\vmware-vpxd-webserver-pipe</pipeName> </e> <e id=1> <_type>vim.ProxyService.LocalServiceSpec</_type> <serverNamespace>/sdk</serverNamespace> <accessMode>httpAndHttps</accessMode> <port>8085</port> </e> <e id=2> <_type>vim.ProxyService.LocalServiceSpec</_type> <serverNamespace>/ui</serverNamespace> <accessMode>httpsWithRedirect</accessMode> <port>8086</port> </e> <e id=3> <_type>vim.ProxyService.NamedPipeServiceSpec</_type> <serverNamespace>/mob</serverNamespace> <accessMode>httpAndHttps</accessMode> <pipeName>\\.\pipe\vmware-vpxd-mob-pipe</pipeName> </e> <e id=4> <_type>vim.ProxyService.NamedPipeServiceSpec</_type> <serverNamespace>/vod</serverNamespace> <accessMode>httpsWithRedirect</accessMode> <pipeName>\\.\pipe\vmware-vpxd-webserver-pipe</pipeName> </e>

To modify the Web proxy service on ESXi to support HTTP BecauseESXihasnoServiceConsole,youcannotusethesameprocessdescribedinTomodifytheWebproxy serviceonESXtosupportHTTPonpage 29.Instead,youmustusetheappropriatevSphereCLIcommand toobtaintheproxy.xmlfilefromtheserver,modifythefiletosupportHTTP,andthenmovethefilebackto theESXisystem.SeethevSphereCLIInstallationandReferenceGuideformoreinformation. To modify the Web proxy service on vCenter Server to support HTTP 1 2 LogintothevCenterServersystemastheWindowsAdministratorofthemachine. Changetothedirectorycontainingtheproxy.xmlfile:
c:\Documents and Settings\AllUsers\Application Data\VMware VirtualCenter

3
30

Useatexteditortoopentheproxy.xmlfile.
VMware, Inc.

Appendix: vSphere Server Certificates

4 5 6

Findthesectionofthefileassociatedwiththe/sdk. ChangetheaccessModetohttpAndHttps. RestarttheservicefromacommandlineorfromtheWindowsServicescontrolpanel.

VMware, Inc.

31

Developers Setup Guide

32

VMware, Inc.

Index

A
Apache Axis, generating stubs 16 API 7 AXISHOME 14

V
VMKEYSTORE 15 VSINSTALLDIR 22 vSphere SDK Package 9 vSphere SDK package, WSDL files 9

C
C# requirements 21 CLASSPATH 14

W
WBEMHOME 15 WSDL (web services description language), defined 7 WSDL files 9 WSDLFILE 22

E
environment variables C# 22 Java 13, 14, 15 error message, not implemented 10

H
http protocol, configuring 29

J
JAVAHOME 14

M
Microsoft .NET requirements 21 Microsoft Visual Studio 2005 22

N
non-SSL, configuring server for HTTP 29

O
operations 7

P
PATH 14

R
Requirements C# development 21 Java development 11

S
samples.jar 9 SDKHOME 14 SOAP toolkits 8 SOAP, defined 7

T
technical support resources 6

VMware, Inc.

33

Developers Setup Guide

34

VMware, Inc.