VMware vSphere Web Services SDK Readme

 Readme for Java Samples
 Readme for C# (.NET) Samples

What’s in the SDK Package?

The vSphere Web Services SDK is a zipfile that provides:

• Sample code demonstrating common use cases for programmatically managing virtual infrastructure. The sample code includes compiled and ready-to-run Java class files, as well as Java and C# source code files. See the respective Readmes (readme_java.html, readme_dotnet.html) for information about building and using the samples.
  
  
• The WSDL that defines the API available on vSphere servers, such as ESX, ESXi, and vCenter Server systems. Note that the WSDL comprises two separate files:
  • vim.wsdl
  • vimService.wsdl (imports the vim.wsdl. Stubs are generated from the WSDL using the vimService.wsdl file.)
• Batch files and shell scripts to automate the process of generating client-side stubs, and for re-building the sample applications.
  
  • For Java developers, compiled client-side libraries (vim.jar, vim25.jar, apputils.jar, samples.jar) are available for testing and development purposes.
  • For C# developers, the Microsoft Visual Studio project files (.sln) have been included.
  
  
• Reference documentation (VMware vSphere API ReferenceGuide) that provides language-neutral descriptive information (object type definitions, properties, and method signatures, for example) for the VMware vSphere API 4.0.
  
  

The vSphere Web Services SDK zipfile package, as unpacked, contains these top-level directories and sub-directories. For more information about the content within each sub-directory (in particular, the Java samples sub-directory and the C# samples sub-directory), see the appropriate readme file.

Directory structure (under \SDK):

What is the VMware vSphere API?

The VMware vSphere API (vSphere API) provides language-neutral interfaces to the vSphere management framework. In much the same way that JMX (Java Management Extension) provides an infrastructure for instrumenting, managing, and monitoring Java applications, the VMware vSphere API lets you do the same for VMware vSphere components (for example, virtual machines, host systems) and subsystems (such as performance manager).

The API is implemented as industry-standard Web services, hosted on VMware vSphere systems, including ESX, ESXi, and vCenter systems. The API complies with the Web Services Interoperability Organization (WS-I) Basic Profile 1.0, which includes XML Schema 1.0, SOAP 1.1, WSDL 1.1. For more information about the WS-I Basic Profile 1.0, see:

http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html

The Web service provides life-cycle operations and operations for managing virtual infrastructure components—compute resources, virtual machines, networks, storage, and the like.

Accessing the VMware Infrastructure Web Service

By default, the VMware Infrastructure Web service listens on port 443 (the well-known port for Secure HTTP (HTTPS), which uses SSL (secure sockets layer) to encrypt communications between client application and server. To access the Web service programmatically, you use the URN from a web-services client application, as in:

https://FQDN_Server_or_IP_Address/sdk

The certificate of the target server must reside on the client machine. See the Developer’s Setup Guide, specifically, Chapter 2, “Obtaining Server Certificates” for more information.

To configure the server to support HTTP (rather than HTTPS), see the Developer’s Setup Guide, specifically, Chapter 2, “Modifying the Server Configuration to Support HTTP” for details.

Samples Listing

The vSphere Web Services SDK includes samples for Java and Microsoft .NET (C#).

Documentation

The API ReferenceGuide is included in the vSphere Web Services SDK package, located in the /doc sub-directory of the SDK package. Other current documentation, such as Release Notes, Developer’s Setup Guide, and Programming Guide, is located online only.

• For beta and other pre-release product information and documentation, visit the VMware Communities portal.
  
  
• For released product information, including known issues, see the VMware Infrastructure SDK page.

Be sure to read the Release Notes for late-breaking and updated information.

Checklist of Setup Tasks

Setting up your workstation for developing client applications using the vSphere Web Services SDK involves several steps. Assuming you are already developing applications of one kind or another, some of the steps below may be unnecessary. Modify the details of the process as appropriate for the specifics of your system. See the Developer’s Setup Guide for complete details. Also see the appropriate readme for your development platform (readme_java.html, readme_dotnet.html).

To get started with the vSphere Web Services SDK:

1. Choose a development language (Java or C#) to use for Web-services client application development.
   
   
2. Identify the target server (or servers) that you’ll use during development. (“Target servers” refers to the vCenter, ESX, or ESXi systems that will be the targets of the client applications that you develop.)
   
   
3. Verify network access to each server by launching a browser and connect to its URL:
   
   https://esx-server-name-or-virtual-center-server-name
   
   

   Note that ESX and vCenter default configurations use SSL (secure sockets layer) to encrypt communications, thus the default protocol used is HTTPS (as shown above). However, target servers can be configured to use HTTP (rather than HTTPS). See “Modifying the Server Configuration to Support HTTP” in the Developer’s Setup Guide for details. If a target server is configured for HTTPS, you must import its server-certificates as detailed in “Obtaining Server Certificates” in the Developer’s Setup Guide. Note: Java developers can circumvent the server-certificate verification (by the client, which occurs during the SSL handshake) in their code by using the SunFakeTrustSocketFactory class (available in the Axis client libraries (org.apache.axis.components.net package). The Java samples included with the SDK use this technique (via an optional command-line argument, --ignorecert). If you plan to use the --ignorecert option, or use this technique in your own code, you do not need to obtain the server certificates. However, you must still set the VMKEYSTORE environment variable (as discussed in the Readme for Java Samples) to use the Run script (run.bat, run.sh).

4. Install the development environment appropriate for your programming language.
   
   
   • For C#, you’ll need one of the Microsoft development environments, such as Microsoft Visual Studio 2005, Microsoft Visual Studio .NET 2003, or Microsoft Visual C#. (VMware recommends using Microsoft Visual Studio 2005, which includes the required .NET Framework.) For more information, visit:
     http://msdn2.microsoft.com
     
     
   • For Java, you’ll need the Java 2 Platform, Standard Edition (J2SE) 5.0 (JDK 1.5_0_08 or later recommended) or version 1.4.2 (J2SE 1.4.2). For more information, visit:
     http://java.sun.com/javase/downloads/previous.jsp
     
     
5. Obtain the appropriate Web-services client tools (XML parser, WSDL-to-proxy-code generation tools, runtime) for your programming language:
   
   
   • For C#, you’ll need Microsoft .NET Framework 2.0 or Microsoft .NET Framework 1.1. If you have been using Microsoft development tools for any length of time, it's likely you already have what's needed. You can obtain Microsoft .NET Framework from Microsoft, at:
     http://msdn2.microsoft.com/en-us/netframework/default.aspx
     
     
     You will also need the Microsoft .NET 2.0 Software Development Kit, which includes the WSDL-to-stub-generation tool (wsdl.exe) and the command-line version of the C# compiler (csc.exe), both of which are called from the Build2005.cmd. You can obtain the Microsoft .NET 2.0 Sofware Development Kit from:
     http://www.microsoft.com/downloads/details.aspx?FamilyID=FE6F2099-B7B4-4F47-A244-C96D69C35DEC&displaylang=en
     
     
   • For Java, you need Apache Axis 1.4 or Apache Axis 1.2.1 client-side Web services libraries. (However, you can only use Apache Axis 1.4 to use any of the Java samples that ship with the vSphere Web Services SDK.) For more information, visit:
     http://ws.apache.org/axis/java/releases.html
     
     
6. Configure environment and other settings on the workstation (as detailed in the appropriate language-specific sections in the Developer’s Setup Guide), or in the respective readme files (readme_java.html, readme_dotnet.html) for the samples.

VMware Resources

• Developer Center
• Knowledge Base
• User Groups
• VMware Communities

Copyright © 2009 VMware, Inc. All rights not expressly granted herein are reserved.

Last updated: 8-Dec-2008 12:30 pm  |  VMware vSphere Web Services SDK