vSphere Web Client SDK Setup

Table of content:

  1. Web Client and SDK installation
  2. Development Environment Setup
  3. Eclipse IDE and Flash Builder
  4. Virgo Server setup
  5. Web Browser setup
  6. Start and Run
  7. Software Requirements Summary
  8. Mac OS Setup notes and tips

Introduction

This document describes how to set up your development environment for extending the vSphere Web Client with UI and Service plug-ins. The SDK can be used on Windows or Mac OS. We assume here that you are starting a manual installation from scratch; you can skip these instructions if you are using a pre-configured VM.

1. vSphere Web Client (VWC) and SDK installation

We assume that you have already installed vSphere 5.5 somewhere else on Windows or as a VCVA appliance. In order to use the VWC SDK you need to copy the Web Client component of vSphere onto your development machine (Windows or Mac OS) and install the additional SDK files.

To install VWC in your development machine

You have 3 options:

  1. Use the Windows vSphere Installer, and install only the vSphere Web Client.
    Important:
  2. Or, you can download the file serenity-client.zip, expand it in a top directory and rename the folder vmware-vsphere-client.
  3. Or, after deploying a VCVA appliance, copy the entire directory /usr/lib/vmware-vsphere-client to your development machine (you may want to compress it first and copy a single zip file because long path names may create problems with copy).

You should end up with a folder like C:\VMware\vmware-vsphere-client, i.e. preferably located in a top directory without spaces.

C:\VMware\vmware-vsphere-client contains the following sub-folders:

To install the SDK

Download the SDK .zip archive and unzip the content in a directory of your choice such as C:\VMware\vsphere-client-sdk. It contains the following:

Define a VSPHERE_SDK_HOME environment variable to point to that location, it will be used by the Ant build scripts when run either from the command line or from Eclipse.
See the Mac OS Setup notes at the end for tips on setting environment variables.

2. Development Environment Setup

Java JDK

Ant

Ant is used to build the SDK samples but you are not required to use Ant in your environment (Maven is more powerful):

See also this Adobe article on Flex and Ant.

3. Eclipse IDE and Flash Builder

Eclipse is the only supported IDE at this time. We recommend the SpringSource Tool Suite (STS) as your Eclipse-powered environment because it comes with other good developer tools that you may be interested in. The rest of the document uses "Eclipse/STS" to indicate that both IDEs can be used.

Eclipse/STS

Add these 2 lines to tell Eclipse/STS to use your installed JDK. Remove any space before each line! (on Mac OS, this is not necessary if you used the Java Preferences app to set the correct JDK as default)

-vm
C:/<your JAVA_HOME directory>/bin/java.exe

Add or change these VM arguments to increase memory (more is even better if you can afford it):

-Xmx1024m
-XX:MaxPermSize=512m

In order to build SDK examples you need to set two VSPHERE_CLIENT_SDK variables. (We recommend that you use VSPHERE_CLIENT_SDK as well in your new Flex and Java projects in order to avoid hard-coding the location of the SDK and make your projects portable):


Flash Builder and Flex SDK

Adobe Flash Builder is not required for compiling Flex code, the Flex compiler is included in the Flex SDK (see how it is used by the Ant scripts provided with the SDK samples). However it is highly recommended to install Flash Builder in order to take advantage of the debugger and have a better development experience within Eclipse/STS.

If the file $FLEX_HOME/frameworks/libs/player/11.5/playerglobal.swc is not present you need to download it separately:

If your older version of Flash Builder doesn't include Flex SDK 4.6 or if you decide not to use Flash Builder, install Flex SDK separately.
Download Adobe Flex SDK 4.6. Either the free Adobe Flex SDK or the Open Source version works.

SDK Tools Eclipse Plug-in

The vSphere Web Client SDK includes an Eclipse plug-in with various tools to help your Web Client development, including a wizard to create Flex and Java plug-in projects easily.
Before trying to installing new software please make sure that Eclipse's Network Connections settings are correct, otherwise the UI won't be responsive. If your location requires a proxy go to Window > Preferences > General > Network Connections to set it up.

After you restart STS you can verify that the plugin is correctly installed:

For more information on how to use this wizard please see the SDK-Tutorial doc.

4. Virgo Server setup

In order to use the Virgo server in the Eclipse IDE during development you must install the Eclipse Virgo Tools:

Once you have restarted Eclipse/STS:

In the next screen, for the installation directory, select the server directory in your installed vsphere-web-client (The message "Valid installation" will popup at the top once you select the right directory). You can leave the default server name as is.

Finally you should increase the memory used by the Virgo Server process:

-XX:+CMSClassUnloadingEnabled
-XX:MaxPermSize=256m

For more information see the Virgo Guides available through Help > Help Contents.

5. Web Browser Setup

The last step is to setup your browser for Flex development. Flex is supported by all major browsers: Internet Explorer, Firefox, Google Chrome, and also Safari on Mac.

6. Start and Run

Now that you have configured your environment let's run a simple example to make sure everything is working.

Add the Helloworld plug-in

Import the example helloworld-ui in Eclipse and add if to your server:

The project is built automatically if you kept the option Project > Build Automatically selected. See the build output in war/target/helloworld-ui-war.

Sdk-helloworld-ui.png

The next step is to deploy this plugin to the Virgo Server within Eclipse.
(In case vSphere Web Client server is already running outside Eclipse/STS on this machine stop the server now in the Windows Services panel. The same instance will be started from Eclipse.)

Sdk-virgo-addremove.png

Sdk-virgo-addremove2.png

The plugin bundle is now visible under the Virgo server

Sdk-virgo-addremove3.png

Next you must create a Run/Debug Configuration to launch the vSphere Client:

Sdk-debugconfig.png

Start vSphere Client

Sdk-virgo-start.png

The server takes a couple of minutes to start, the Console tab shows all the bundles being loaded and should be clean of errors.

The bundles loaded by the server are both the runtime bundles installed in server/repository and the plug-ins' Flex and Java bundles from vsphere-web-client/plugin-packages.

In case your server never reaches the state Started, Synchronized, or you see other errors, please check the trouble-shooting steps in the FAQs.

Sdk-redeploy-helloworld.png

Initial registration of your vCenter Server(s)

vSphere Web Client 5.5 is compatible with vCenter servers version 5.1 and 5.5. The vCenter 5.x installation requires an SSO server for authentication (Single Sign-On): vCenter registers with the SSO server and Lookup Service component (LS) that it was installed with. Then the Web Client "discovers" the registered vCenter at login time when it connects to LS. So you need to configure the Web Client in your development environment to talk to the right Lookup Service:
This setup is done automatically if you used the Windows installer initially.

  1. Create a file client.properties in vsphere-web-client/server/configuration
  2. In order to get the thumbprint you can either:
  3. Restart Virgo in Eclipse/STS after client.properties was changed.

Launch the vSphere Client

Use the Debug or Run menu to start the vSphere-client configuration you created above.

Or you can also right-click on the project and select Debug As/ Run As > Web App

Sdk-debug-webapp.png

It will appear as a short-cut in the Run or Debug menu only after your have used it once.

Sdk-debug-shortcut.png

Notes:

Your target browser is launched and lands in the login page.

Try other plug-ins

Once the Virgo server is running you can add and remove plug-ins without having to restart it.


7. Software Requirements Summary

Components Minimum versions Downloads Comments
Java JDK 1.7.0_17 + Java SE Downloads Java compiler must be set to 1.6 compatibility. Set JAVA_HOME to the JDK location.
Apache Ant 1.7.1 + ant.apache.org Set ANT_HOME to the ant directory.
Eclipse
or STS
Eclipse indigo (3.7.x) +
STS 2.9.x +
eclipse.org
SpringSource STS
64-bits versions OK with Flash Builder 4.7
STS 3.2.0 works great.
Eclipse Virgo Tools 1.0.0.201207122033 See Virgo setup instructions above for installing in Eclipse/STS
vSphere Client SDK Tools (your SDK version) Provided with the SDK See SDK Tools Eclipse Plug-in above for installing in Eclipse/STS
Flash Builder 4.6 or 4.7 Adobe Flash Builder 60 days trial available. Must be installed as a plug-in to Eclipse or STS
Flex SDK 4.6 (only) Included with FB 4.7
or Flex SDK download
Either Adobe Flex SDK or the Open Source version. Set FLEX_HOME to the sdk directory.
Flash Player
+ Content Debugger
11.5 + Flash player download Install Flash player and its Content Debugger in the browser of your choice.


8. Mac OS Setup notes and tips

Here are some important things to remember when setting up your development environment on Mac OS:

See also: FAQs - SDK Tutorial - SDK samples - Flex API docs - Java API docs