vSphere Web Services SDK Developer’s Setup Guide VMware vSphere 6.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.
vSphere Web Client Extensions 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 © 2007–2015 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
Contents About This Book 5 1 About the vSphere Web Services SDK 7 Knowledge Required for Using the vSphere Web Services SDK 7 Programming Languages Supported by the vSphere Web Services SDK Types of Applications That You Can Build Using This SDK 8 Downloading the vSphere Web Services SDK 9 Configurations for Sample Authentication with Single Sign-On 9 vSphere Web Services SDK Package Contents 9 SDK Versions and VMware vSphere Product Compatibility 10 8 2 Setting Up for Java Development 11 Java Developm
vSphere Web Services SDK Developer’s Setup Guide A vSphere Server Certificates 25 Secure Client-Server Communications 25 Simplified Security Setup for Development Environment 25 Obtaining Server Certificates 26 Obtain Certificates Using the vSphere Web Client 26 Updating the Active Directory Group Policy to Accept Certificates 27 Modifying Server Configurations to Support HTTP 27 HTTP Configuration for ESXi 5.1, 5.5, or 6.0 28 HTTP Configuration for ESX 4.1, ESXi 4.1, or ESXi 5.
vSphere Web Services SDK Developer’s Setup Guide About This Book This book, the vSphere Web Services SDK Developer’s Setup Guide, provides information about setting up your development environment to use the VMware® vSphere Web Services SDK 6.0. VMware provides several different APIs and SDKs for various applications and goals.
vSphere Web Services SDK Developer’s Setup Guide 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. 6 VMware, Inc.
1 About the vSphere Web Services SDK 1 The VMware vSphere® Web Services SDK includes all the components necessary to work with the VMware vSphere API, including WSDL files, sample code, and libraries. The vSphere Web Services SDK facilitates development of client applications that target the VMware vSphere API.
vSphere Web Services SDK Programming Guide You should also know about basic ESX, ESXi, and vCenter Server operations. See the VMware vSphere Documentation page on the VMware Web site. Programming Languages Supported by the vSphere Web Services SDK Because the vSphere API is based on Web services, you can use any programming or scripting language that provides utilities for generating client-side stubs from Web-services WSDL files.
Chapter 1 About the vSphere Web Services SDK This list is not comprehensive. Also, some of the operations pertain to the service as a whole, not specific hosts or virtual machines. For example, load balancing can be a service-wide operation rather than a per-host or per-virtual machine operation. Downloading the vSphere Web Services SDK The vSphere Web Services SDK, along with other VMware SDKs, is contained in the vSphere Management SDK. You can find the vSphere Management SDK at https://developercenter.
vSphere Web Services SDK Programming Guide Batch files and shell scripts (run.bat and run.sh) that facilitate running the Java samples from the Windows command prompt. The vSphere API Reference, which provides language-neutral descriptive information about the VMware vSphere API and the object model, such as object type definitions, properties, and method signatures.
2 Setting Up for Java Development 2 This chapter explains how to set up an environment to develop Java clients. This chapter includes these topics: “Java Development Requirements” on page 11 “Set Up for Java Development” on page 11 “Running the SimpleClient Sample Application to Validate Setup” on page 15 Java Development Requirements Developing Java Web-services client applications using the VMware vSphere Web Services SDK requires the Java SDK and a Java Web services development toolset.
vSphere Web Services SDK Developer’s Setup Guide Obtain the VMware vSphere Web Services SDK from https://developercenter.vmware.com. It is included in the vSphere Management SDK package. Set Up for Development Using JAX-WS The samples generated using JAX-WS libraries and compiled using Java JDK 1.7 include vim25.jar and samples.jar. You can use these libraries without generating new stubs and recompiling if you are using the same version of the JDK.
Chapter 2 Setting Up for Java Development Table 2-1. Batch Files and Shell Scripts for Java Filename Description Usage note build.bat Checks for environment variable JAVAHOME and sets PATH, using the JAVAHOME variable. Cleans up existing Java files (by calling clean.bat or clean.sh). build.bat sets the local classpath (by calling lcp.bat). Creates the vim25.jar, and samples.jar files. Use this script to generate client stubs and rebuild all sample applications.
vSphere Web Services SDK Developer’s Setup Guide 5 Create a password for the keystore by entering it at the prompt. The keystore utility displays the certificate information at the console. For example: Owner: OID.1.2.840.113549.1.9.2="1183400896,564d7761726520496e632e", CN=sdkpubslab-01.vmware.com, EMAILADDRESS=ssl-certificates@vmware.com, OU=VMware ESX Server Certificate, O="VMware, Inc.", L=Palo Alto, ST=California, C=US Issuer: OID.1.2.840.113549.1.9.
Chapter 2 Setting Up for Java Development 3 Run the build.bat (or build.sh) script by entering its name at the command prompt. build The console displays output, starting with Generating stubs from wsdl. In a few minutes, the process finishes. The word Done appears at the command prompt, as shown in Example 2-1. The Generating stubs from wsdl message appears twice, because this build file generates client stubs using both sets of WSDL declarations, found in the \vim and \vim25 subdirectories.
vSphere Web Services SDK Developer’s Setup Guide Example 2-2. Sample Output of a Successful Run of SimpleClient, Using 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.
3 Setting Up for Microsoft C# Development 3 This chapter explains how to set up an environment to develop C# clients for the vSphere Web Services SDK. This chapter includes these topics: “C# Development Requirements” on page 17 “Setting Up for C# Development” on page 17 “Building the C# SSO DLL” on page 19 “Building the C# vSphere DLLs” on page 20 “Building the C# Sample Programs” on page 21 “Running the Microsoft .
vSphere Web Services SDK Developer’s Setup Guide To set up a development workstation to use C# 1 Install the Microsoft Visual programming environment, such as Microsoft Visual C# or Microsoft Visual Studio. Use Microsoft Visual Studio 2008 or later, which includes the required .NET Framework. 2 Obtain the Microsoft .NET Framework, if it is not included in the Microsoft Visual programming environment. Use .NET version 3.5 or later, depending on your Visual Studio version.
Chapter 3 Setting Up for Microsoft C# Development To set environment variables 1 Open a Visual Studio command shell window. 2 Create the WSE_HOME environment variable, setting its value to the absolute path to the directory where WSE was installed. For example: set WSE_HOME="C:\Program Files (x86)\Microsoft WSE\v3.0" 3 Add the WSE tools directory to the PATH environment variable: set PATH=%PATH%;%WSE_HOME%\Tools 4 Create the WS_SDK_HOME environment variable, setting its value to the absolute path to
vSphere Web Services SDK Developer’s Setup Guide Building the C# vSphere DLLs In the vSphere Web Services SDK, VMware supplies sample vSphere clients for Visual Studio 2008. The SDK includes a project (.csproj) file for each sample, and a solution (.sln) file for the whole set of samples. The project files reference the DLLs through which a client communicates with the Web service. XML Serializers For best performance, precompile the XML serializers to a separate DLL.
Chapter 3 Setting Up for Microsoft C# Development 7 Annotate the VimService class in the VimService.cs file that you generated in Step 3, adding this XmlSerializerAssemblyAttribute to point to the location of the XML serializer assembly: [System.Xml.Serialization.XmlSerializerAssemblyAttribute(AssemblyName = "Vim25Service.XmlSerializers")] The result should look something like the following example: // ... Some code here ... [System.Xml.Serialization.
vSphere Web Services SDK Developer’s Setup Guide Figure 3-1. Build Process for C# Sample Programs start 1 open .sln are you running VS > 2008? NO YES (1) Conversion Wizard prompt do you also run VS 2008? NO YES (1) save backup any unconverted .proj files? NO YES convert a .csproj file 2 3 build solution end Prerequisites for Building the C# Sample Programs Before you build a sample program, you must build the relevant DLLs: STSService.dll Vim25Service.dll Vim25Service.
Chapter 3 Setting Up for Microsoft C# Development To build the C# sample programs 1 Launch Visual Studio and load the solution file, Samples2008.sln. The solution file is found in the %SDK_HOME%\vsphere-ws\dotnet\cs\samples directory. If you are using a version of Visual Studio later than 2008, the Visual Studio Conversion Wizard prompts you to convert the 2008 solution file to the newer version.
vSphere Web Services SDK Developer’s Setup Guide 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 the Setup If you cannot successfully run the SimpleClient, first check your environment settings and all other setup tasks.
A vSphere Server Certificates A The VMware vSphere API is available as a secure Web service. Secure Web service means that, by default, ESX, ESXi, and vCenter Server are configured for HTTPS and support SSL to encrypt communications. This appendix explains how to manage the certificates needed for secure communications.
vSphere Web Services SDK Developer’s Setup Guide Obtaining Server Certificates VMware products use standard X.509 version 3 (X.509v3) certificates to encrypt session information sent over SSL connections between server and client systems. When a client application initiates an SSL session with the server, the server sends its certificate to the client application, which checks the X.509 certificate against a list of known Certificate Authorities (CAs) to verify the authenticity of the certificate.
vSphere Server Certificates After you obtain the certificate from each target server, follow the other setup steps appropriate for your programing language. For C# developers, see “Setting Up for C# Development” on page 17. For Java developers, see “Set Up for Java Development” on page 11. For the latest information about certificates, see the vSphere Security guide at http://www.vmware.com/support/pubs/.
vSphere Web Services SDK Developer’s Setup Guide “HTTP Configuration for ESX 4.1, ESXi 4.1, or ESXi 5.0” on page 29 “HTTP Configuration for vCenter Server” on page 30 HTTP Configuration for ESXi 5.1, 5.5, or 6.0 You can modify ESXi configuration from a shell window over an SSH connection, using the following procedure.
vSphere Server Certificates 14 Signal the reverse proxy service to update its configuration by entering the following command: /etc/init.d/rhttpproxy restart Example A-1. An endpoints.conf File Modified To Support HTTP connections to the SDK and the MOB / local 8309 redirect allow /sdk local 8307 allow allow /client/clients.
vSphere Web Services SDK Developer’s Setup Guide service mgmt-vmware restart Example A-2. A proxy.xml File Modified To Support the SDK and the MOB <_length>7 <_type>vim.ProxyService.EndpointSpec[] <_type>vim.Proxyservice.NamedPipeServiceSpec / httpsWithRedirect \\.\pipe\vmware-vpxd-webserver-pipe <_type>vim.ProxyService.
B Scripting the C# DLL Build B When you generate the .NET stubs to run C# samples in the SDK, you get best performance if you pre-compile the XML serializers into separate DLLs. The procedure in “Build the C# vSphere DLLs” on page 20 describes how to pre-compile the XML serializers and modify the class declaration to use a pre-compiled serializer DLL. The result of these changes is to decrease initialization time when you instantiate the VimService class.
vSphere Web Services SDK Developer’s Setup Guide rem These 2 long SED lines wrap: "%SED_HOME%"\sed.exe "s#\[System.Xml.Serialization.XmlIncludeAttribute#//&#" VimService.cs.temp "%SED_HOME%"\sed.exe "s#public partial class VimService #\[System.Xml.Serialization.XmlSerializerAssemblyAttribute\(AssemblyName = \"Vim25Service.XmlSerializers\")\]\n &#" VimService.cs rem This long line wraps: csc.exe /t:library /out:Vim25Service.dll /r:"%WSE_HOME%\Microsoft.Web.Services3.
Index A API 7 application design 8 software downloads 11 using batch files and shell scripts 12 Java stubs, generating and compiling 14 JAX-WS 12 C C# M building sample DLLs 19, 20 building samples 21 development workstation 17 environment variables 18 requirements 17 running SimpleClient 23 certificates 25, 26 bypassing 25 installing in Java 13 obtaining from vSphere Client 26 client libraries vim.jar 9 vim25.jar 9 configuring server for HTTP 27 Management SDK 9 Microsoft .
vSphere Web Services SDK Developer’s Setup Guide vSphere Management SDK 9 downloading 9, 12, 18 vSphere SDK Package 9 vSphere SDK package, WSDL files 9 W Web Services SDK package contents 9 product compatibility 10 requirements 7 WSDL (web services description language), defined 7 WSDL files 9 WSDLFILE 18 X XML serializers 20 34 VMware, Inc.
