How to: Add Silverlight to a Web Page by Using HTML

Microsoft Silverlight will reach end of support after October 2021. Learn more.

The object element enables you to embed and configure the Silverlight plug-in in your HTML in a way that is compatible with all supported browsers. This topic describes how to accomplish the following common tasks using the object element:

• Embed the Silverlight plug-in and specify the application to host.

• Specify alternate HTML to display when Silverlight is not installed.

These tasks correspond to different parts of an HTML page and specifically to different configuration parameters of the object element. The following procedures describe several tasks in isolation, but build up to a complete cross-browser HTML example at the end of this topic.

You should use the final example as a template for your projects instead of using the snippets in each procedure. The final example ensures cross-browser compatibility and is based on the template that Visual Studio and Expression Blend use to dynamically generate test pages. Note, however, that this example provides only a basic installation and upgrade experience. For more information on improving this experience, see Microsoft Silverlight Installation Experience White Paper and Sample Code.

You can accomplish additional configuration tasks using the HTML object element. For more information, see Silverlight Plug-in Object Reference and Property Values of the HTML Object Element. The topics listed in the See Also section provide additional coverage of specific embedding scenarios.

An alternative to using the object element is to use the JavaScript embedding functions provided by the Silverlight.js helper file. These functions ultimately generate object elements, and are provided as a convenience in JavaScript development. For more information, see How to: Add Silverlight to a Web Page by Using JavaScript.

Procedures

To embed the plug-in

• Add the object element to your HTML and specify attributes and a child param element as shown in the following example.

  Note:
  You will typically specify additional HTML to provide an installation experience and ensure cross-browser compatibility. For a complete HTML example, see the end of this topic.

  <object width="300" height="300"
      data="data:application/x-silverlight-2," 
      type="application/x-silverlight-2" >
      <param name="source" value="SilverlightApplication1.xap"/>
  </object>
  

  The width and height attributes are required for cross-browser compatibility. You can specify fixed pixel values or percentages relative to the width and height of the parent element. If you use relative sizing, you can respond to plug-in size changes by handling the Content.Resized event. For more information, see Silverlight Plug-in Sizing.

  The type attribute and the specific value shown are also required. This value uses the Silverlight MIME type to identify the plug-in and the required version. Note that the indicated MIME type is used with Silverlight version 2 and all later versions. For more information, see Silverlight Plug-in Versioning.

  The data attribute and its value are recommended to avoid performance issues on some browsers. Note the trailing comma in the data value. This indicates a second data parameter that has an empty value.

  The param element named source is required, and indicates the location and name of your application file. You typically specify a .xap application package in a location relative to the HTML file. For more information, see Source (Silverlight Plug-in Object). For more information about application development, see Application Model.

To specify alternate HTML to display when Silverlight is not installed

• Add HTML content to the object element after the child param elements, as shown in the following example.

  <object id="SilverlightPlugin1" width="300" height="300"
      data="data:application/x-silverlight-2," 
      type="application/x-silverlight-2" >
      <param name="source" value="SilverlightApplication1.xap"/>
  
      <!-- Display installation image. -->
      <a href="https://go.microsoft.com/fwlink/?LinkID=149156&v=4.0.60310.0" 
          style="text-decoration: none;">
          <img src="https://go.microsoft.com/fwlink/?LinkId=161376" 
              alt="Get Microsoft Silverlight" 
              style="border-style: none"/>
      </a>
  
  </object>
  

  This example shows the default install image source and installer URIs. With these URIs, the server detects the user's browser settings to provide the correct version of the installation image and installer. If the user's browser is not supported, clicking the image causes the browser to open the Silverlight Requirements page.

  You can provide arbitrarily complex alternate HTML in order to integrate the Silverlight install experience with your Web page. However, in many cases, users will have to restart or refresh their browsers after installing Silverlight. With Internet Explorer, only a browser refresh is required unless the user has an older version of Silverlight installed and upgrades through the installation link.

  You can refresh the browser automatically or eliminate the refresh requirement by using helper functions in the Silverlight.js file. You can also use Silverlight.js to perform fine-grained browser requirements detection. For more information, see the Microsoft Silverlight Installation Experience White Paper and Sample Code and the Silverlight.js Reference.

Example

Description

The following code example provides a complete HTML page for a Silverlight application that uses the entire browser window. This example is based on the default HTML used by Visual Studio when you choose to dynamically generate a test page.

This example uses cascading style sheets (CSS) and a div element to contain the plug-in. This ensures that the plug-in extends to the edges of the browser window. This and other additions to the HTML help ensure cross-browser compatibility.

Note:
Because of browser differences, the Silverlight plug-in does not support the cascading style sheets (CSS) overflow property on the object element or on a parent container element, such as a div element.

The iframe element is also for cross-browser compatibility. The presence of the iframe prevents the Safari browser from caching the page. Safari caching prevents the Silverlight plug-in from reloading when the user navigates back to a previously-visited Silverlight page. For more information, see the Safari Developer FAQ.

This example uses a JavaScript function to handle the plug-in's OnError event. A JavaScript error handler is useful during debugging, but you typically remove it when you deploy your application.

This example also includes minRuntimeVersion and autoUpgrade settings to provide an upgrade experience if the specified version of Silverlight is not installed. (As mentioned previously, the "2" in the type and data settings do not indicate the Silverlight version.) For more information, see Silverlight Plug-in Versioning.

To view this example in your Web browser window, you must specify a valid Silverlight application package in the source parameter. For more information, see How to: Create a New Silverlight Project.

Code

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<!-- saved from url=(0014)about:internet -->
<head>
    <title>SilverlightApplication1</title>

    <style type="text/css">
    html, body {
        height: 100%;
        overflow: auto;
    }
    body {
        padding: 0;
        margin: 0;
    }
    #silverlightControlHost {
        height: 100%;
        text-align:center;
    }
    </style>
    
    <script type="text/javascript">
        function onSilverlightError(sender, args) {
            var appSource = "";
            if (sender != null && sender != 0) {
                appSource = sender.getHost().Source;
            }

            var errorType = args.ErrorType;
            var iErrorCode = args.ErrorCode;

            if (errorType == "ImageError" || 
                errorType == "MediaError") {
              return;
            }

            var errMsg = "Unhandled Error in Silverlight Application " 
                + appSource + "\n";

            errMsg += "Code: " + iErrorCode + "    \n";
            errMsg += "Category: " + errorType + "       \n";
            errMsg += "Message: " + args.ErrorMessage + "     \n";

            if (errorType == "ParserError") {
                errMsg += "File: " + args.xamlFile + "     \n";
                errMsg += "Line: " + args.lineNumber + "     \n";
                errMsg += "Position: " + args.charPosition + "     \n";
            }
            else if (errorType == "RuntimeError") {
                if (args.lineNumber != 0) {
                    errMsg += "Line: " + args.lineNumber + "     \n";
                    errMsg += "Position: " + args.charPosition + 
                        "     \n";
                }
                errMsg += "MethodName: " + args.methodName + "     \n";
            }

            throw new Error(errMsg);
        }
    </script>
</head>

<body>
    <div id="silverlightControlHost">
        <object width="100%" height="100%"
            type="application/x-silverlight-2" 
            data="data:application/x-silverlight-2," >
            <param name="source" value="SilverlightApplication1.xap"/>
            <param name="onerror" value="onSilverlightError" />
            <param name="background" value="white" />
            <param name="minRuntimeVersion" value="4.0.60310.0" />
            <param name="autoUpgrade" value="true" />
            <a href="https://go.microsoft.com/fwlink/?LinkID=149156&v=4.0.60310.0" 
                style="text-decoration: none;">
                <img 
                    src="https://go.microsoft.com/fwlink/?LinkId=161376" 
                    alt="Get Microsoft Silverlight" 
                    style="border-style: none"/>
            </a>
        </object>
        <iframe id="_sl_historyFrame" 
            style='visibility:hidden;height:0px;width:0px;border:0px'>
        </iframe>
    </div>
</body>
</html>

See Also

Tasks

How to: Specify and Retrieve Custom Initialization Parameters

Reference

Silverlight Plug-in Object Reference

Concepts

Adding Silverlight to a Web Page by Using HTML or JavaScript

Silverlight Plug-in Sizing

Silverlight Splash Screens

Security Settings in HTML Bridge

Other Resources

HTML Bridge: Interaction Between HTML and Managed Code

Silverlight Requirements

Microsoft Silverlight Installation Experience White Paper and Sample Code