VMware vSphere - 6.0 User’s Manual
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.
EN-001412-01
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. 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
2 VMware, Inc.
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 8
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
2 Setting Up for Java Development 11
Java Development Requirements 11
Set Up for Java Development 11
Software Downloads 11
Set Up for Development Using JAX-WS 12
Batch Files and Shell Scripts for Building and Running Samples 12
Import Server Certificates into the Java Keystore 13
Generating Stubs and Compiling Classes 14
Precompiled JAX-WS Samples 14
Use the Included Build Scripts 14
Running the SimpleClient Sample Application to Validate Setup 15
Run a Sample Application Using the Provided Scripts 15
3 Setting Up for Microsoft C# Development 17
C# Development Requirements 17
Software Downloads for C# Development 17
Setting Up for C# Development 17
Set Up a Development Workstation To Use C# 17
Set Environment Variables To Build C# DLLs and Samples 18
Building the C# SSO DLL 19
Build the C# SSO DLL 19
Prerequisites for Building the C# SSO DLL 19
Building the C# vSphere DLLs 20
XML Serializers 20
Build the C# vSphere DLLs 20
Prerequisites for Building the C# vSphere DLLs 20
Building the C# Sample Programs 21
Build the C# Sample Programs 21
Prerequisites for Building the C# Sample Programs 22
Running the Microsoft .NET C# Version of SimpleClient 23
Run the SimpleClient C# application 23
Prerequisites To Run the SimpleClient C# Application 23
Troubleshooting the Setup 24
Proxy Server Connection Problem 24
sgen Configuration Issues 24
VMware, Inc. 3
vSphere Web Services SDK Develo per’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.0 29
HTTP Configuration for vCenter Server 30
B Scripting the C# DLL Build 31
Index 33
4 VMware, Inc.
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
VMware provides several different APIs and SDKs for various applications and goals. This book provides
information about using the vSphere Web Services SDK for developers who are interested in creating client
applications for managing VMware
VMware vCenter Server systems.
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. Ta bl e 1 summarizes the significant changes in each version of this guide.
Table 1. Revision History
Revision Description
11Feb2016 Correct the procedure for modifying the Web proxy service.
12Mar2015 vSphere 6.0 release. Changed destination directory for C# DLLs.
20Feb2014 Corrected instructions for modifying reverse proxy configuration.
04Dec2013 Clarified location of Web Services SDK.
01Oct2013 Revised C# setup instructions to reflect simplified procedure in 5.5 release and use new tools. Corrected
path to Java sample. Updated Java version. Fixed minor typographical errors in code.
09Sep2012 Removed Axis support for 5.1 release. Made more corrections and expansions to C# instructions.
17Nov2011 Corrected setup instructions for C# stubs.
24Aug2011 Updated for vSphere 5.0 (included information on using JAX-WS bindings).
13Jul2010 Minor updates for vSphere 4.1 (new WSDL file configuration, example syntax).
07May2009 Revised release of the vSphere Web Services SDK Developer’s Setup Guide for vSphere Web Services SDK 4.0.
Server-certificate setup information is located in the reference section. Changed directory name for
WSDLFILE environment variable.
29Nov2007 Initial release of vSphere Web Services SDK Developer’s Setup Guide for VMware Infrastructure SDK 2.5.
®
vSphere Web Services SDK 6.0.
®
vSphere components available on VMware ESXi and
Intended Audience
This book is intended for anyone who wants to develop applications using the
VMware vSphere Web Services SDK. vSphere Web Services SDK developers typically include software
developers creating client applications using Java or C# (in the Microsoft .NET environment) targeting
VMware vSphere.
VMware, Inc. 5
vSphere Web Services SDK Develo per’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 W eb Services SDK
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.
With the vSphere Web Services SDK, developers can create client applications to manage, monitor, and
maintain VMware vSphere components, as deployed on VMware
VMware
This vSphere Web Services SDK Programming Guide explains how to set up the development environment to
create new applications with Java and the Microsoft .NET environment, using the C# programming language.
This guide also includes information about running the sample applications included with the vSphere Web
Services SDK.
This chapter includes these topics:
“Knowledge Required for Using the vSphere Web Services SDK” on page 7
“Programming Languages Supported by the vSphere Web Services SDK” on page 8
“Types of Applications That You Can Build Using This SDK” on page 8
“vSphere Web Services SDK Package Contents” on page 9
“SDK Versions and VMware vSphere Product Compatibility” on page 10
®
vCenter™ Server systems.
®
VMware vSphere® ESX®, ESXi™, and
1
Knowledge Required for Using the vSphere Web Services SDK
Developing applications with the vSphere Web Services SDK requires expertise with Java, C#, or another
programming language. You must also understand the following Web services programming concepts:
Web services technology provides operations, also known as methods in the context of client applications.
Using the vSphere Web Services SDK and your choice of programming language, you can create client
applications that invoke these operations to perform the full range of server-side management and
monitoring tasks.
The Web services API is defined in Web Services Description Language (WSDL) files. The WSDL files are
used by client-side Web-services utilities to create proxy code (stubs) that client applications use to
interact with the server.
Client applications invoke operations by calling proxy interface methods. The client proxy encodes an
operation invocation into a SOAP message and sends it to the server. Simple Object Access Protocol
(SOAP) is a programming-language neutral XML format. SOAP message translation is transparent to the
developer.
Communications between client and server occur over HTTP or HTTPS. HTTPS is a secure form of HTTP
that uses SSL to encrypt client-server communications. The default is HTTPS, but you can configure the
VMware vSphere Web server to support HTTP. (See “Modifying Server Configurations to Support HTTP”
on page 27.)
VMware, Inc. 7
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 W eb 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. The
vSphere Web Services SDK package includes sample client applications developed in both Java and C#. SOAP
toolkits are readily available for both languages.
See “vSphere Web Services SDK Package Contents” on page 9 for additional packaging details and for some
caveats about the Java samples and for specific version requirements for the JDK, the
Java API for XML Web Services libraries, and the JAX-WS libraries.
Table 1-1. Langua ge and Tools Matrix for Client Application Development
Language/Tool Context Java C#
Development environment or framework J2SE 7, also known as J2SE 1.7. For best
results, use J2SE 1.7 or higher.
Web-services-client application
development toolset, also known as a
SOAP toolkit
JAX-WS 2.1 (Java API for XML Web
Services).
Microsoft Visual Studio
Microsoft Visual C#
Microsoft .NET Framework
Developers, scripters, and administrators using Microsoft PowerShell or Perl can use the
vSphere Web Services API through toolkits that VMware provides. For more information, see
http://communities.vmware.com/community/developer.
Types of Applications That You Can Build Using This SDK
You can use the vSphere Web Services SDK to develop system administration, provisioning, and monitoring
applications for VMware vSphere systems.
The VMware vSphere Client application and VMware vSphere Web Access are two examples of client
applications that were developed using vSphere API. The vSphere Client is a traditional Windows client
application. Web Access is a browser plug-in that is available through the Web server port on ESX, ESXi, and
vCenter Server systems.
With the vSphere Web Services SDK, you can create your own client applications that automate many
administration, provisioning, or monitoring tasks associated with virtual infrastructure management and
operations. The following examples are operational tasks that you can automate using the
vSphere Web Services API:
Create, configure, power cycle, or suspend virtual machines explicitly or by using profiles or templates to
facilitate faster provisioning.
Create, configure, and manage virtual devices, such as virtual CD-DVD drives, virtual network interface
cards, virtual switches, and other components.
Connect, power cycle, and disconnect ESX and ESXi host systems.
Capture the state of a virtual machine to a snapshot and restore the state of a virtual machine from a
snapshot, such as in a backup application.
Gather statistics about host system and virtual machine performance.
Manage events generated by the server, such as those created by alarms set for specific thresholds.
Move virtual machines between hosts automatically.
Manage load balancing and failover through the distributed resource scheduler (VMware DRS) and high
availability (VMware HA) subsystems. VMware DRS and VMware HA require vCenter Server.
8 VMware, Inc.
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.vmware.com, which links to the My VMware service.
After you expand the vSphere Management SDK package, the Web Services SDK is in the subdirectory
SDK/vsphere-ws. You also need the SDK/ssoclient subdirectory for client authentication.
Configurations for Sample Authentication with Single Sign-On
The vSphere 6.0 release introduces a Platform Services Controller that can run on the same host as the vCenter
Server, or can be configured on a separate host. At this time, the two possible configurations are:
vCenter Server with an embedded Platform Services Controller (vCenter Single Sign-On Server,
Lookup Service Server,...). This is like traditional vSphere deployments.
vCenter Server with an external Platform Services Controller.
You will have to provide the vCenter Single Sign-On URL explicitly in order to run samples with the second
configuration. With the first configuration, there is no need to provide the vCenter Single Sign-On URL (since
the vCenter Single Sign-On service is embedded in the management node) and our SDK will continue to work
as before.
The SDK samples have always had the option to explicitly specify the vCenter Single Sign-On URL (whether
the vCenter Single Sign-On service is running inside or outside the management node). This is useful in cases
where the vCenter Single Sign-On service is deployed outside the vSphere management node like the second
configuration above.
When you log in to a vCenter Single Sign-On Server, you must be i n a d oma in t hat has been added as a vCenter
Single Sign-On identity source. If that domain is not the default domain, you must include the domain name
as part of your user name, such as, administrator@vsphere.local. To learn more about configuring the vCenter
Single Sign-On Server, see vSphere Security.
vSphere Web Services SDK Package Contents
The vSphere Web Services SDK is a bundle that includes the following items:
WSDL files that define the API available on a VMware vSphere server (ESX, ESXi, and vCenter Server)
Web serv ice.
Precompiled client-side libraries (vim.jar, vim25.jar) available for test purposes that were generated
from the WSDL. The vSphere Web Services API is packaged in the vim25.jar file and is available in the
SDK\vsphere-ws\wsdl\vim25 subdirectory.
Sample code demonstrating common use cases associated with managing virtual infrastructure. The
sample code includes compiled and ready-to-run Java class files and both Java and C# source code files.
(For C# developers, the Microsoft Visual Studio project files (.sln) are included.)
N
OTE The precompiled Java samples (samples.jar) were compiled using JDK 1.7 from stubs generated
by the Java API for XML Web Services (JAX-WS) libraries in J2SE 7.0, and work only with these specific
versions of Java and JAX-WS. To use a different version of Java, or a different client-side Web services
library, use the build script to rebuild the samples.
Batch files and shell scripts (build.bat and build.sh) that automate the build process for Java and C#
client applications.
VMware, Inc. 9
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.
Complete information about setting up the environment, and about generating, compiling, and running
applications is included in Chapter 2, “Setting Up for Java Development,” on page 11, and in Chapter 3,
“Setting Up for Microsoft C# Development,” on page 17.
SDK Versions and VMware vSphere Product Compatibility
VMware has released SDK products to support various versions of the VMware vSphere product family. You
can use the VMware vSphere Web Services SDK 6.0 with many previous versions of VMware vSphere servers
and its predecessor, VMware Infrastructure, including:
ESX/ESXi 6.0, 5.5, 5.1, and 5.0
ESX/ESXi 4.1 and 4.0
ESX/ESXi 3.5 Update 5
vCenter Server 6.0, 5.5, 5.1, 5.0, 4.1, 4.0
VirtualCenter Server 2.5 Update 5
All versions are supported by using the appropriate WSDL files, as follows:
SDK\vsphere-ws\wsdl\vim25 contains WSDL files for use with ESXi 5, ESX/ESXi 4, vCenter Server 5,
vCenter Server 4, ESX 3.5, and VirtualCenter 2.5 systems. As of vSphere 4.1, the vSphere API WSDL
definitions are divided into several files. Backwards compatibility is achieved because both WSDL
configurations (vim25 and vim directories) use a top level file with the same name (vimService.wsdl).
The VMware vSphere API is a Web service that runs on VMware vSphere servers, including ESX, ESXi, and
vCenter Server. The API exposed is the same in all products. However, vCenter Server provides the following
capabilities which are not available through an ESX or ESXi Web service:
Collecting historical performance data
Optimizing resources, including managing distributed resources
Enabling migration from one host system to another by using VMware vMotion
Providing distributed resource management, including recovery, across all host systems under its control
If you attempt to invoke an operation on an ESX or ESXi system that is supported only on vCenter Server, the
server returns a fault saying “not implemented” or “not supported.” For example, the ExtensionManager API
is available only on VirtualCenter Server 2.5 and subsequent releases of vCenter Server. Attempting to register
an extension to an ESX system returns a fault, “not supported.”
10 VMware, Inc.
2
Setting Up for Java Development
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. For best results, use Java 2, Standard Edition, version
7.0 (J2SE 1.7.x), specifically JDK 1.7 or later.
The Java Web services development toolset must be a SOAP implementation that can be deployed to a Tomcat
server. For example, you can use the client-side libraries in JAX-WS version 2.1. The JAX-WS 2.1 libraries are
included with the JDK 1.7.
You can use other client-side tools and libraries, such as IBM WebSphere and several open source
implementations, with the vSphere Web Services SDK. However, only the JAX-WS client libraries were tested
with this guide.
2
The samples archive, in samples.jar, includes all vSphere Web Services SDK samples. The samples include
client-side stub classes generated using the JAX-WS libraries. Samples using JAX-WS were generated using
JDK 1.7.
N
OTE If you are not using JDK 1.7, you must use the build.bat on Windows, or the build.sh on Linux, to
generate stubs and compile the sample files (vim25.jar and samples.jar). The build scripts perform all
necessary tasks for you, including setting the CLASSPATH and PATH environment variables. See “Generating
Stubs and Compiling Classes” on page 14 for details.
Set Up for Java Development
Specific setup instructions depend on whether your development workstation already meets some or all of the
requirements, which client-side Web service library you plan to use, and whether you plan to use the provided
samples. Specific setup instructions also depend on whether your target server uses the HTTPS protocol or
HTTP.
Software Downloads
You can obtain the software you need for Java client development from the following Web sites:
The J2SE is available from http://www.oracle.com. For best results, use JDK 1.7 or later.
VMware, Inc. 11
Loading...