vSphere Web Client SDK Setup
Table of content:
- Web Client and SDK installation
- Development Environment Setup
- Eclipse IDE and Flash Builder
- Virgo Server setup
- Web Browser setup
- Start and Run
- Software Requirements Summary
- 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:
- Use the Windows vSphere Installer, and install only the vSphere Web Client.
Important:
- The installer only works on 64-bits processors.
- You will be asked to enter the SSO information from your vSphere 5.5 setup (This will save you the manual steps of configuring client.properties later in this document.)
- After the installation succeeds be sure to stop the service VMware vSphere Web Client in the Administrative Tools' Services dialog, since you will be starting the same server from Eclipse/STS.
- Also, you should change the default location C:\Program Files\VMware\Infrastructure\vSphereWebClient to something like C:\VMware\vmware-vsphere-client.
- Or, you can download the file serenity-client.zip, expand it in a top directory and rename the folder vmware-vsphere-client.
- 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:
- /plugin-packages: the Web Client installed packages.
- /server: the Virgo application server used for the Java
middle-tier. You will point to this location when you configure the
Virgo Server inside Eclipse later in the process.
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:
- README
- /docs: the API documentation
(asdoc and javadoc) and other useful docs to get started.
- /samples: the source code examples.
- /libs: the Flex and Java
libraries to compile with.
- /tools: SDK tools to install in Eclipse
and Ant scripts.
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
Check which version of java you already have with the command:
java -version
- Install JDK 1.7.0_17 (64 bit) or newer to your local disk from
Java SE Downloads.
The 64 bit version is recommended if you need to allocate more memory
- Check the JAVA_HOME environment
variable to the correct jdk location, for example C:\Program Files\Java\jdk1.7.0_17
(JAVA HOME is not required on Mac OS).
- Set the Java compiler option -target 1.6 in your build script and in Eclipse's Java compiler preferences
(in this release the platform libraries are still compiled in in Java 1.6 mode because of internal dependencies).
Note that this is not the same as setting the Compiler compliance level to 1.6, because this would
force you to have installed JRE 1.6 as well.
Ant
Ant is used to build the SDK samples but you are not required to use
Ant in your environment (Maven is more powerful):
- To run the Ant build scripts from Eclipse you can rely on
the Ant version packaged with Eclipse.
- To use Ant from the command line:
- Download Apache Ant (version 1.7.1
or above)
- Set the environment variable ANT_HOME to that location on your disk.
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
- Download Eclipse Indigo (3.7.x) or Eclipse Juno (4.2.x) from eclipse.org,
or STS 2.9.x or 3.2.x from SpringSource,
and install it anywhere on your disk.
Note: the 64-bits version are OK as long as you will be using Flash Builder 4.7 (4.6 was not compatible).
Also, FYI, newer versions of Eclipse/STS are not officially supported by Adobe Flash Builder, but they should work.
- Edit the Eclipse.ini or STS.ini file.
(on Mac OS the .ini file is hidden, right-click on the application icon and select Show Package Contents, the file is in Contents/MacOS):
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
- Start STS and go to Window > Preferences
- In General you can check "Show
heap status" to display a memory indicator.
- In General/Network Connections
you can setup proxy settings for your location.
- In General/Workspace we recommend
to keep "Build automatically" on, and also turn on "Refresh using native hooks"
in case you edit sources outside Eclipse from time to time.
- In Java/Code Style/Formatter you
should define your code formatting conventions.
- In Java/Installed JREs add the
JDK you had installed earlier and make sure it is the default.
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):
- Go to Window > Preferences >
General > Workspace > Linked Resources as shown below, and add
a new path variable VSPHERE_CLIENT_SDK pointing to the location of
your vsphere_client_sdk directory.
- Go to Window > Preferences >
Java > Build path > Class variables as shown below, and add a
path variable VSPHERE_CLIENT_SDK pointing to the location of your
vsphere_client_sdk directory.
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.
- Download Adobe Flash Builder and install it as an Eclipse plug-in, it will be exactly the same Flash Builder features within the IDE.
- You can start with the free 60-days trial version.
- Run the Adobe Flash Builder 4.7 Plug-in Utility under /utilities and select your Eclipse or STS folder.
- When this is done you should see a file [Eclipse]/dropins/fb-4_7-plugin.link containing the path to your FB 4.7 folder.
- Start Eclipse/STS and check that Flash Builder is installed, it will appear in the Help menu.
- Go to Window > Preferences > Flash Builder > Installed Flex SDKs
and check that Flex SDK 4.6 is the default SDK.
- Define a FLEX_HOME environment variable pointing to the SDK directory, for instance
C:\Program Files (x86)\Adobe\Adobe Flash Builder 4.7\sdks\4.6.0.
FLEX_HOME will be used by the Ant build scripts.
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.
- Go to Help > Install New Software...
- Click Add... to select a new site location
- Click Local... and browse to your vsphere-client-sdk/tools/vSphere
Client SDK plugin site directory
- You can name this local site "vSphere Client SDK plugin
site" (you will be able to re-use it later if you install the
versions of the Eclipse plugin are the same place)

- Select the vSphere Web Client Plug-in Creator that appears in
the list and click Next

- Continue the wizard.
- Click Finish, this starts the Eclipse plugin installation.
- A popup comes up to warn you that this plugin doesn't have a
certificate.
- Finally you are asked to restart STS before you can use the
new plugin.
After you restart STS you can verify that the plugin is
correctly installed:
- Open Help > About SpringSource Tool Suite
- Click on Installation Details
- See "vSphere Web Client Plug-in Creator" in the list of Installed Software
- Note that you can also uninstall the plugin from this view
- Finally, if you select File >
New > Other... you should see a vSphere Web Client folder
containing the wizard to create new projects:
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:
- Open Help > Install New
Software... and click Add...
- Add the repository http://dist.springsource.com/release/TOOLS/virgo-ide
as shown below.
(if the URL is not responding check your
Eclipse proxy settings Window > Preferences > General > Network Connections)
- Select Eclipse Virgo Tools and nothing else
- Follow the installation wizard (you will need to restart Eclipse/STS at the end).
Once you have restarted Eclipse/STS:
- Select the Servers view under Window > Show Views
- Look for the Servers tab in the bottom panel and right
click to create a new server.
- In the new server wizard, select the type Eclipse
RT > Virgo Runtime and click Next.
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.
- Click Finish.
- Double click on the server instance in the Server view, this
opens an Overview page.
- Check options Start server with -clean option and Tail application trace files ..
at the bottom right.
- Remove *.xml from the list under Redeploy Behavior
(so that changes in plugin.xml files trigger hot deployment of the bundle).
Finally you should increase the memory used by the Virgo Server process:
- Click on Open Launch Configuration in the server Overview
page
- Click on the Arguments tab
- Insert the following VM arguments:
-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.
- Pick the browser you want to develop and test with and set it
as your default external browser in Eclipse/STS.
- In Window > Preferences >
General > Web Browser select the external web browser of your
choice. i.e. the browser used when starting a Flex session from
Eclipse.
- You can keep Default system web browser selected or select a browser that won't change if you modify your default browser outside Eclipse.
- Note that you can always run vSphere Web Client in any other browser outside
Eclipse if you are not interested in debugging client code.

- Then install the latest Flash Player (version
11.5 or above) for the browser of your choice.
- Install also the Flash Player Debugger from the same
Adobe site for your target browser, otherwise you won't be able to
launch client debugging sessions.
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:
- Select File > Import >
General > Existing projects into Workspace
- Browse to
vsphere-client-sdk/samples/helloworld/helloworld-ui
- Select the existing project helloworld-ui and click Finish.
The project is built automatically if you kept the option Project > Build Automatically selected. See
the build output in war/target/helloworld-ui-war.
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.)
- Open the Servers tab view at the bottom.
- Right click on the Virgo Server instance and select Add and Remove.
- Select the helloworld-ui resource on the left and click Add
to move it to the right list.
The plugin bundle is now visible under the Virgo server
Next you must create a Run/Debug Configuration to launch the vSphere Client:
- Open Run > Run Configurations...
- Select the Web Application category on the left and press the New button
(Note that you will see this category only if you have
installed Flash Builder with Eclipse)
- Name it vSphere Client for instance as you will
use the same configuration regardless of the plug-ins you have deployed.
- Under Project select the project Helloworld-ui.
(Note that it doesn't matter which Flex project is selected, the run
configuration will be available as long as the project stays open)
- Under URL or path to launch, uncheck Use default and set the URL to be
https://localhost:9443/vsphere-client
9443 is the default port used when installing VWC, but it may be different in your case.
Start vSphere Client
- Start the server by clicking on the run (or debug) buttons in
the panel toolbar or in the right-click menu.
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.
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.
- Create a file client.properties in
vsphere-web-client/server/configuration
- In order to get the thumbprint you can either:
- Use the script vsphere-web-client/scripts/ls-cmd.bat
with the argument https://YOUR-VCVA-IP:7444/lookupservice/sdk, it will generate client.properties.
(ls-cmd.bat won't be available if you used the Windows Installer.)
- Or go to https://YOUR-VCVA-IP:7444/lookupservice/sdk in your browser and look at the certificate details.
Note that it is normal to get an error when accessing this URL directly in your browser, what matters is the certificate information!
- 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
It will appear as a short-cut in the Run or Debug menu only
after your have used it once.
Notes:
- The Debug session requires that you have installed the Flash
Debugger in your browser as described above.
- If you don't want to debug you can also open the vSphere
Client by going directly to https://localhost:9443/vpshere-client in your
preferred browser.
Your target browser is launched and lands in the login page.
- Login with your vCenter credentials
- This opens the Flex Client showing vCenter Servers that were
registered.
- Go to the Home view and see the Helloworld button.
This opens a view with the "Hello world" text in it.
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:
The Finder hides many files by default, it is easiest to make them all visible using this command in your terminal window:
defaults write com.apple.Finder AppleShowAllFiles YES
You can use the system's Java Preferences app to set the correct JDK as default: do a Spotlight search (Command-Space) to find it.
The Eclipse.ini or STS.ini file used to configure startup options is hidden, right-click on the application icon and select Show Package Contents, the file is in Contents/MacOS.
When starting Virgo under your user account (on the command line or from Eclipse) your plugin code may not have read/write permissions in local directories being used. The solution is to set the proper permission for your account. For instance, when saving setting values in the globalview sample, you will get an error if you haven't set write permission to /var/lib because the data is saved in /var/lib/globalview.
Environment variables are a little tricky on the Mac...
When using scripts on the command line (Terminal window) the easiest is to set them in your ~/.bash_profile.
See this article for other solutions.
However this won't work if you run the Ant build scripts from Eclipse/STS unless you start Eclipse/STS from the command line which is not always practical.
One solution is to edit the JRE in Eclipse's Java Preferences, adding 2 VM arguments defining VSPHERE_SDK_HOME and FLEX_HOME as shown below (Note: this may not work if you use multiple workspaces):
Another solution which seems more stable is to edit the Ant Runtime Preferences, adding 2 properties for VSPHERE_SDK_HOME and FLEX_HOME as shown below:
Make sure NOT to use quotes around your paths, even if they contain spaces like Abobe Flash Builder above!
See also: FAQs - SDK Tutorial - SDK samples -
Flex API docs - Java API docs