VMware Infrastructure (VI) SDK 2.5.0 Readme
Readme for Java Samples
Readme for C# (.NET) Samples
Welcome to the VMware Infrastructure (VI) SDK. For late-breaking information, including known issues, see the
VMware Infrastructure SDK
page available from the VMware APIs and SDKs Documentation page.
This Readme contains these topics:
Whats in the SDK Package?
The VI 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 an ESX Server and
VirtualCenter Server Web service. Note that the WSDL comprises two separate files:
In this release, the WSDL is available in two different versions, located in the \wsdl sub-directory of the SDK package.
- vimService.wsdl (imports the vim.wsdl. Stubs are generated from the WSDL using the vimService.wsdl file.)
- vim sub-directory contains WSDL files with vim2 namespace, which defines API hosted on Web services running on ESX Server 3.5, VirtualCenter Server 2.5, ESX Server 3i, ESX Server 3.0.x, and VirtualCenter Server 2.0.x
- vim25 sub-directory contains WSDL files with vim25 namespace, which defines API hosted on Web services running on ESX Server 3.5, VirtualCenter Server 2.5, and ESX Server 3i
- 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.
- API reference documentation (VI API ReferenceGuide) that provides language-neutral
descriptive information (object type definitions, properties, and method signatures, for example) about
the VMware Infrastructure API (VI API) and the server-side object model.
The VI 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):
|Directory or filename||Description|
|\doc||Contains SDK Terms and Conditions document; Porting Guide (legacy document); Developers Setup Guide. Be sure to obtain updated versions of the Developers Setup Guide, Programming Guide, and various readme files (available as a zipfile) from the VI SDK product page, at:
|\doc\ReferenceGuide||API Reference for the VMware Infrastructure API. Use a web browser and open index.html. |
|\samples||Top-level directory for the language-specific versions of the sample client applications, one for Java, one for C#. |
|\samples\Axis\java||Directory containing batch files, Java source code (in package hierarchy), compiled bytecodes, Java stub classes for the samples, and a vim.jar file that comprises the client-side stubs built using the vim.wsdl. |
|\samples\Axis\java\java\com\vmware||Directory containing Java samples. See the Readme for Java samples for details.|
|\samples\DotNet\cs||Directory containing batch files, plus several other sub-directories containing Windows C# sample applications (in the appropriate namespace structure), the Microsoft Visual Studio project files (.sln files). |
|\wsdl\vim\vim.wsdl||The Web Services Description Language (WSDL) file containing definition of the VMware Infrastructure Management API. |
|\wsdl\vim\vimService.wsdl||A WSDL file defining the Web services endpoint at which the API is available. The vimService.wsdl file references the vim.wsdl with an import statement, so you'll use the appropriate generation tool with vimService (rather than vim.wsdl directly). |
|\wsdl\vim25\vim.wsdl||The Web Services Description Language (WSDL) file containing definition of the VMware Infrastructure Management API. Supports new features of the VMware infrastructure object model.|
|\wsdl\vim25\vimService.wsdl||A WSDL file defining the Web services endpoint at which the API is available. The vimService.wsdl file references the vim.wsdl with an import statement, so you'll use the appropriate generation tool with vimService (rather than vim.wsdl directly).
What is the VI API?
The VMware Infrastructure API (VI API) provides language-neutral interfaces to the VMware infrastructure management framework. In much the same way that JMX (Java
Management Extension) provides an infrastructure for instrumenting, managing, and monitoring Java applications, the VMware Infrastructure API lets you do the same for VMware Infrastructure 3
components (for example, virtual machines, host systems) and subsystems (such as performance manager).
The VI API is implemented as industry-standard Web services, hosted on VirtualCenter Server and ESX Server
systems. The VI 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,
The Web service provides all the operations necessary, from life-cycle operations, to monitoring and managing
virtual infrastructure componentscompute 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:
The certificate of the target server must reside on the client machine. See the Developers Setup Guide, specifically, Chapter 2, Obtaining Server Certificates for more information.
To configure the server to support HTTP (rather than HTTPS), see the Developers Setup Guide, specifically, Chapter 2, Modifying the Server Configuration to Support HTTP for details.
The VI SDK includes samples for Java and Microsoft .NET (C#).
Current documentation for this release of the VI SDK is available online. 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 VI 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 Developers 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 VI SDK:
- Choose a development language (Java or C#) to use for Web-services client application development.
- Identify the target server (or servers) that youll use during development. (Target servers refers to the VirtualCenter Management Server or ESX Server systems that will be the targets of the client applications that you develop.)
- Verify network access to each server by launching a browser and connect to its URL:
Note that ESX Server and VirtualCenter Management Server 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 Developers 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 Developers Setup Guide.
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).
Install the development environment appropriate for your programming language.
- For C#, youll 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:
- For Java, youll 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:
- Obtain the appropriate Web-services client tools (XML parser, WSDL-to-proxy-code generation tools, runtime) for your programming language:
Configure environment and other settings on the workstation (as detailed in the appropriate language-specific sections in the Developers Setup Guide), or in the respective readme files (readme_java.html, readme_dotnet.html) for the samples.
Copyright © 2007, 2008 VMware, Inc. All rights not expressly granted herein
Last updated 26-Dec-2007 7:00 pm | VI SDK 2.5 | online