Silverlight: Embedding on a Page


Microsoft provides JavaScript helper files that make embedding Silverlight applications on a web page easy. These helper files provide a consistent method for passing in parameters and take care of cross-browser differences in addition to providing users a seamless install experience if they don't have Silverlight installed. These files require JavaScript to be enabled. For a non-JavaScript method, see Embedding using the <object> tag.

It is important to provide users who don't have Silverlight installed the best possible user experience. This includes providing the user with a preview of the content they will get in return for taking the time to install, keeping them within your page and automatically showing the Silverlight enabled content once the installation has completed. Unfortunately, currently all other browsers except Internet Explorer on Windows will require the user to restart their browser after installation. More details can be found in the Silverlight Installation Experience Guide provided by Microsoft.

An easy way to test the experience users without Silverlight will get is to use Internet Explorer 7's add-on manager to temporarily disable the Silverlight "Microsoft Silverlight" or "AgControl Class" add-on.

Using the Helper Files

Silverlight.js & CreateSilverlight.js

The two helper files Microsoft provides are Silverlight.js and CreateSilverlight.js. The former is the main file you will need, while the latter is an optional encapsulation of the settings that will be passed when the plug-in and application are created. These files, including their localized versions, can be found in the Silverlight SDK Tools folder.

Silverlight.js is minified (8kB) and contains the code required to embed the Silverlight plug-in. CreateSilverlight.js on the other hand only contains a call-thru to Silverlight.js with a set of parameters.

To embed a Silverlight application on a web page, you will need the following on your page:

  1. A <script> tag that references the Silverlight.js file.
  2. An HTML block element, usually a <div> tag, that will contain the Silverlight plug-in and thus the application.
  3. A <script> tag that contains code (usually createObjectEx();) to render the plug-in.
  4. (Optional) A <script> tag that references the CreateSilverlight.js file.

Since the CreateSilverlight.js file essentially only contains one function, you may want to avoid using this file to minimize unnecessary network calls. Instead, consider including the code directly within your page or, even better, within another external JavaScript file, such as the file where you have your application code. See Rule 8 - Make JavaScript and CSS External and the YDN Performance blog for additional tips.

The Silverlight Class

The Silverlight.js file creates a class named Silverlight that provides methods and properties to create the application on the page and also to help get information about the environment, such as whether Silverlight is installed and which browser is running.

The following table lists public properties and methods of the Silverlight class.

Name Description
available A property that returns a Boolean value indicating whether any version Silverlight has been installed.
createObject(...) Creates a Silverlight application with the given list of parameters.
createObjectEx(parametersObject) Creates a Silverlight application with parameters given in a JSON dictionary.
isInstalled(versionString) A method that returns a Boolean value indicating whether the specified version of Silverlight has been installed.
supportedUserAgent() A method that returns a Boolean value indicating whether the current operating system and browser combination is supported.
ua.Browser A property that gets a string representing the running browser. Values returned include Firefox, MSIE, and Safari.
ua.OS A property that gets a string representing the running operating system. Values returned include Unsupported, MacIntel, MacPPC, and Windows.

The createObject() & createObjectEx() Methods

The createObject and createObjectEx are the methods used to create the Silverlight application on a page. The difference between the two methods is that createObject takes parameters as method arguments in a predefined order and createObjectEx takes a single JSON object with named key-value pairs. Thus createObjectEx is less prone to typing errors and also provides a cleaner way to use built-in default values.

The following table lists the required parameters.

Name Description
source The source XAML file or ID of an inline XAML script block prefixed with #.
parentElement The HTML block element that will contain the application.
id The HTML element ID for the newly created application.
properties A JSON object containing initialization properties, such as width, height, and version.
events A JSON object containing global level event handlers onError and onLoad.

The detailed method signatures and full list of available parameters that can be set can be found in the Silverlight SDK documentation.

Detecting If Silverlight Is Installed

You can use the Silverlight.isInstalled(version) method to check if the required version of Silverlight is installed on the client. This will allow your site to provide additional information and sample content to users who haven't installed Silverlight yet or don't have the correct version.


The following example loads a Silverlight application from the myApplication.xaml file in the MyApplication folder. If Silverlight isn't installed, it will display a preview image and reattempt to display the application every three seconds until the installation has completed.

View Sample

Further Reading

Related information on the web is listed below.

Yahoo Forum Discussions