• Article

Silverlight Plug-in Versioning

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

To run a Silverlight-based application within a Web page, users must have the correct version of the Silverlight plug-in installed. Depending on how you embed the plug-in, you can specify the version that your Web page requires in one of two ways:

  • With the HTML object element.

  • With the Silverlight.js helper functions.

With both options, you can prompt users to install the correct version if it is not already installed. For more information about providing an installation and upgrade experience, see Microsoft Silverlight Installation Experience White Paper and Sample Code.

You can also specify a required Silverlight runtime version in the manifest of your application assembly. For more information, see Deployment.RuntimeVersion. This is useful if your application has a dependency on a version-specific behavior that has changed in a subsequent Silverlight release. For more information, see Ensuring That Your Silverlight Applications Work with Silverlight 5.

You will not typically need to provide special handling for application versioning. The Web hosting model enables you to replace your application with an updated version at any time. Users who visit your Web site will always see the latest version. However, there are a few special considerations if your application uses out-of-browser support or application library caching. For more information, see Out-of-Browser Support or How to: Use Application Library Caching.

Versioning with the HTML Object Element

With the object element, you specify the required Silverlight version by including a type attribute and setting the value to a Silverlight MIME type. Each major release has its own MIME type, as indicated in the table at the end of this topic.

If a Silverlight plug-in version with the specified MIME type is not installed, the HTML content of the object element is shown instead. You can use this to provide an installation link. For more information, see How to: Add Silverlight to a Web Page by Using HTML.

You can optionally specify a MinRuntimeVersion value in the form majorVersion.minorVersion.buildNumber.revisionNumber, where all values are optional except majorVersion. In this case, if a user has an earlier version of the plug-in installed, the plug-in will not load the application package. Instead, it will display the message "Click to install the required version". This prevents malicious applications from exploiting bugs in earlier versions of Silverlight that are fixed in more recent versions. If your plug-in size is too small to display the default message, you should prompt the user to upgrade, as described in the following text.

If you specify a MinRuntimeVersion value, you can optionally specify an AutoUpgrade value. If an upgrade is required and you set AutoUpgrade to true, the plug-in will prompt the user to upgrade and then to restart the Web browser. The upgrade prompt is displayed in addition to the default message that appears in the plug-in.

If an upgrade is required, the following errors occur, regardless of the AutoUpgrade setting:

  • 8001 - Upgrade required.

  • 8002 - Browser restart required.

You can respond to these errors in an OnError handler in order to display your own upgrade and browser restart prompts. In this case, however, you typically do not set AutoUpgrade to true.

For more information about handling errors with the errors in an OnError event, see Error Handling and Error Messages.

Versioning with the Silverlight.js Helper Functions

With the Silverlight.js helper functions, you specify a Silverlight version number in the form majorVersion.minorVersion.buildNumber.revisionNumber where all values are optional except majorVersion. Version numbers are used by the following functions:

  • isInstalled. This function accepts a version parameter and indicates whether that version of Silverlight is installed.

  • createObject and createObjectEx. These functions accept a version value in the properties parameter array. If the specified version of Silverlight is installed, the plug-in is embedded in the Web page. Otherwise, these functions display alternative HTML.

  • getSilverlight. This function accepts a version parameter and attempts to download the corresponding Silverlight installer.

You can use these and other Silverlight.js functions to embed the Silverlight plug-in and customize the installation and upgrade experience. For more information, see How to: Add Silverlight to a Web Page by Using JavaScript and Silverlight.js Reference.

Version Information

The following table lists the MIME type and version number associated with each major version of the Silverlight plug-in. Each version is backward compatible with the previous versions. If you specify that your application requires Silverlight 1.0, then your application will run in Silverlight 3, but it will only be able to use the JavaScript API. For more information, see Application and Programming Models.

Version

MIME Type

Version Number

Installer URL

Silverlight 1.0

application/x-silverlight

1.0.30715

https://go.microsoft.com/fwlink/?LinkId=110408

Silverlight 2

application/x-silverlight-2

2.0.40115

https://go.microsoft.com/fwlink/?LinkID=124807

Silverlight 3

application/x-silverlight-2

3.0.50106

https://go.microsoft.com/fwlink/?LinkID=149156&v=3.0.50106.0

Silverlight 4

application/x-silverlight-2

4.0.60310.0

https://go.microsoft.com/fwlink/?LinkID=149156&v=4.0.60310.0

Silverlight 5

application/x-silverlight-2

5.0.60401.0

https://go.microsoft.com/fwlink/?LinkID=149156&v=5.0.60401.0
NoteNote:

The MIME type "application/x-silverlight-2" is used for Silverlight 2 and all subsequent versions.

The beta releases of each Silverlight version use the same major and minor version numbers (for example, 4.0) as the final release. Therefore, you should always include the build number (for example, 50917) to indicate the final release.

The installer URLs redirect to the appropriate installer or error message depending on the user's platform and browser. For example, the Silverlight 1.0 installer URL redirects to the latest installer except on platforms that do not support Silverlight or support Silverlight 1.0 only.