Silverlight Versions and Version Compatibility

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

Version Compatibility for Existing Silverlight Applications

In general, the Silverlight runtime is engineered such that the most current version of the runtime is capable of running applications that were compiled with previous versions of the tools, and targeting a specific preceding version number. However, there are occasionally breaking changes that are introduced into the Silverlight runtime behavior, usercode API, and codebase.

The Concept of Quirks Mode

In some cases, rather than introducing a breaking change, the newest version of the Silverlight runtime introduces a quirks mode that applies to a particular behavior or usercode API. The idea behind a quirks mode is that the Silverlight runtime uses the deliberate version targeting of a Silverlight application as an indication of which runtime the application was originally built and tested for. If the target version is a previous version, the codepath that defines the quirks mode is entered. The quirks mode either emulates or actually is the same behavior that the previous version runtime had when using that behavior or calling that API. In other words, the application runs as it did before, when tested against the runtime it originally targeted.

However, if the target version is the current version, the default behavior of the API is engaged. The default behavior in the most current runtime typically represents an improvement in a feature, or a fix for a bug. Nevertheless, the improvement might have had side effects that are not desirable for previously existing applications when run against the most current runtime, and thus the old behavior was preserved under a quirks mode.

Silverlight 5 and Silverlight 4 specifically introduced a number of quirks mode cases, to support migration from previous versions. Each such quirks mode is documented in Ensuring That Your Silverlight Applications Work with Silverlight 5 and Ensuring That Your Silverlight Applications Work with Silverlight 4.

Version Information in API Reference Documentation

Multiple versions of Silverlight are covered in the same set of API reference documentation. For API reference topics, you should check the Version Information section of the API reference topic to determine which versions of Silverlight are supported by that API. Occasionally, specific version-related behavior differences are called out in Version Notes in the Remarks section of the API reference topic. Reference information for Silverlight as it applies to Windows Phone is also included in this documentation set, and version support for Windows Phone is also noted in the Version Information section. In API listings such as the members tables for classes and interfaces, Windows Phone version support is noted by the presence of a special Windows Phone icon on the left side of the table row for the API.

For more information on documentation conventions that are related to Silverlight versioning, including how versioning information is communicated in conceptual documentation, see About the Silverlight Documentation.

Versioning and Compatibility for Windows Phone

This topic does not discuss versioning or compatibility with Silverlight for Windows Phone; all versioning issues discussed in this topic pertain to the different versions of Silverlight for the desktop. For more information about versions of Silverlight for Windows Phone, and for some general guidance on feature sets that might be useful if migrating from Silverlight for the desktop to Silverlight for Windows Phone, see What's New in Silverlight for Windows Phone or Features Differences Between Silverlight and Silverlight for Windows Phone.