Version Compatibility in the .NET Framework

Backward compatibility means that an app that was developed for a particular version of a platform will run on later versions of that platform. The .NET Framework tries to maximize backward compatibility: Source code written for one version of the .NET Framework should compile on later versions of the .NET Framework, and binaries that run on one version of the .NET Framework should behave identically on later versions of the .NET Framework.

Version compatibility for apps

By default, an app runs on the version of the .NET Framework that it was built for. If that version is not present and the app configuration file does not define supported versions, a .NET Framework initialization error may occur. In this case, the attempt to run the app will fail.

To define the specific versions on which your app runs, add one or more <supportedRuntime> elements to your app's configuration file. Each <supportedRuntime> element lists a supported version of the runtime, with the first specifying the most preferred version and the last specifying the least preferred version.

      <supportedRuntime version="v2.0.50727" />  
      <supportedRuntime version="v4.0" />  

For more information, see How to: Configure an App to Support .NET Framework 4 or 4.x.

Version compatibility for components

An app can control the version of the .NET Framework on which it runs, but a component cannot. Components and class libraries are loaded in the context of a particular app, and therefore automatically run on the version of the .NET Framework that the app runs on.

Because of this restriction, compatibility guarantees are especially important for components. Starting with the .NET Framework 4, you can specify the degree to which a component is expected to remain compatible across multiple versions by applying the System.Runtime.Versioning.ComponentGuaranteesAttribute attribute to that component. Tools can use this attribute to detect potential violations of the compatibility guarantee in future versions of a component.

Backward compatibility and the .NET Framework 4.5

The .NET Framework 4.5 and its point releases (4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, and 4.7) are backward-compatible with apps that were built with earlier versions of the .NET Framework. In other words, apps and components built with previous versions will work without modification on the .NET Framework 4.5. However, by default, apps run on the version of the common language runtime for which they were developed, so you may have to provide a configuration file to enable your app to run on the .NET Framework 4.5. For more information, see the Version compatibility for apps section earlier in this article.

In practice, this compatibility can be broken by seemingly inconsequential changes in the .NET Framework and changes in programming techniques. For example, performance improvements in the .NET Framework 4.5 can expose a race condition that did not occur on earlier versions. Similarly, using a hard-coded path to .NET Framework assemblies, performing an equality comparison with a particular version of the .NET Framework, and getting the value of a private field by using reflection are not backward-compatible practices. In addition, each version of the .NET Framework includes bug fixes and security-related changes that can affect the compatibility of some apps and components.

If your app or component does not work as expected on the .NET Framework 4.5 (including its point releases, the .NET Framework 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, or 4.7, use the following checklists:

Compatibility and side-by-side execution

If you cannot find a suitable workaround for your issue, remember that the .NET Framework 4.5 (or one of its point releases) runs side by side with versions 1.1, 2.0, and 3.5, and is an in-place update that replaces version 4. For apps that target versions 1.1, 2.0, and 3.5, you can install the appropriate version of the .NET Framework on the target machine to run the app in its best environment. For more information about side-by-side execution, see Side-by-Side Execution.

See Also

What's New
What's Obsolete in the Class Library
Application Compatibility
Microsoft .NET Framework Support Lifecycle Policy
.NET Framework 4 Migration Issues