Ensuring That Your Silverlight Applications Work with Silverlight 5

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

Several changes have been made to the Silverlight runtime and the Silverlight Tools between Silverlight 4 and Silverlight 5. For these changes, the following principles apply:

  • Most Silverlight 4 applications will work with Silverlight 5 without any changes.

  • When breaking changes are required, Silverlight will try to maintain support for the old behavior, as well as the new behavior, by using a quirks mode.

Nevertheless, some changes made to Silverlight components can potentially cause your older Silverlight-based applications to fail (compile time, XAML load time, or possibly design time) or to behave differently.

This topic describes the changes that were made between Silverlight 4 and Silverlight 5. This topic does not describe new features or enhancements for Silverlight 5. For information about what is new in Silverlight 5, see What's New in Silverlight 5.


For corrections and additions to this topic, see the Silverlight SDK blog.

Upgrading Projects Using Silverlight 5 Tools

There are no known breaking changes between Silverlight 4 and Silverlight 5 in the Silverlight core runtime. Applications that were originally compiled using Silverlight 4 tools, and that continue to target the Silverlight 4 runtime, should work without issues on a client that has the Silverlight 5 runtime.

To retarget an existing Silverlight 4 project for the Silverlight 5 runtime specifically, you should change the project targeting in Visual Studio, using the Silverlight Build Options / Target Silverlight Version section of the Visual Studio project configuration dialog. Then, recompile the project.

For more information on how version targeting can influence the behavior of your application, see Silverlight Plug-in Versioning.

Referencing Assemblies

If your project references any Silverlight SDK client assemblies (for example System.Windows.Controls.dll) make sure that your project specifically references the Silverlight 5 version of the SDK client assemblies that were distributed with the Silverlight 5 Visual Studio tools. A project that targets Silverlight 5 cannot use the Silverlight 4 SDK assemblies.

Any custom assemblies or third-party assemblies that are referenced by a project that targets Silverlight 5 do not necessarily need to be recompiled for Silverlight 5.

Note that quirks mode behaviors do not apply to the behavior of specific third-party assemblies. Quirks mode applies to the overall application, and versioning settings are made by applications, not assemblies. A third-party assembly is always executed under the application's versioning.

Quirks Mode Behavior

This section describes where the runtime or its API include version-specific behavior differences. These behavior differences are based on which runtime version the application targets. Often, the changes represent bug fixes to Silverlight 5, but the Silverlight 4 behavior remains accessible as a specific quirks mode, which is used only when the application targets a Silverlight 4 runtime. This is done in case the logic of your application relied on the Silverlight 4 behavior.

  • In Silverlight 4, the default value for RelativeSource.Mode was TemplatedParent. In Silverlight 5, the FindAncestor mode was added and set as the new default.

  • In Silverlight 5, ItemsControl uses the TextInput event to handle text searching. The previous behavior is maintained for existing versions in case applications have custom implementations.

  • In Silverlight 5, the tick-synchronized timing in the ClientHttp code was moved off of the UI thread. The ClientHttp code should emulate the tick-synchronized timing present before its implementation was moved.

  • Prior to Silverlight 5, if you set the SelectedIndex, SelectedItem, or SelectedValue before setting a Selector's ItemsSource, that value would be coerced to null. In Silverlight 5, the values stay set so there is selection when the ItemsSource is set. This enables a number of binding scenarios and matches the behavior in WPF.

  • Vector Printing is the default printing format for Silverlight 5.

  • Prior to Silverlight 5, the old selection was cleared during collection changed Reset even if they still existed in the Items. In Silverlight 5, the selection is preserved, which matches WPF.

  • Multicore JIT on application startup is only used for Silverlight 5 applications or in 64 bit.

  • Prior to Silverlight 5, ButtonBase does not change the visual state when Visibility is set to Collapsed, so when the control is visible again, it stays in the visual state before it is made invisible. In Silverlight 5, the visual state is updated when Visibility is set to Collapsed.

  • In Silverlight 5, Selector's SelectedValue should be null if the property path listener could not resolve the value. This matches the WPF behavior.

  • Prior to Silverlight 5, the default background color for writeable bitmap is transparent black, which is not desirable for printing. In Silverlight 5, transparent white is used as the default.

  • In Silverlight 5, Selector will defer calling ScrollIntoView when setting the focus on an item if it is not possible to scroll the view.

  • Prior to Silverlight 5, in a ListBox, focus was set to an item for a selection change when oldIndex != newIndex only in the case when the newIndex != -1. In Silverlight 5, the focus is set even if newIndex == -1. If newIndex == -1, the focus is set to the ListBox.