Version Compatibility in the .NET Framework
Backward compatibility means that an application 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 Applications
By default, an application runs on the version of the .NET Framework that it was built for. If that version is not present and the application configuration file does not define supported versions, a .NET Framework initialization error may occur. In this case, the attempt to run the application will fail.
To define the specific versions on which your application runs, add one or more <supportedRuntime> elements to your application'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.
Version Compatibility for Components
An application 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 application, and therefore automatically run on the version of the .NET Framework that the application runs on.
Because of this restriction, compatibility guarantees are especially important for components. Starting with the .NET Framework version 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
The .NET Framework 4 is backward-compatible with applications that were built with the .NET Framework versions 1.1, 2.0, 3.0, and 3.5. In other words, applications and components built with previous versions of the .NET Framework will work on the .NET Framework 4.
However, 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 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 applications and components.
You should test your .NET Framework applications and components to ensure that they are compatible with other versions of the .NET Framework. To ensure that an application or component successfully runs on the .NET Framework 4, use the .NET Framework 4 Application Compatibility Walkthrough.
If your application or component does not work as expected on the .NET Framework 4, use the following checklists.
For .NET Framework 2.0, 3.0, and 3.5 applications:
Check .NET Framework 4 Migration Issues for any changes that might affect your application and apply the workaround described.
If you are recompiling existing source code to run on the .NET Framework 4, or if you are developing a new version of an application or component that targets .NET Framework 4 from an existing source code base, check What's Obsolete in the .NET Framework for obsolete types and members, and apply the workaround described. (Previously compiled code will continue to run against types and members that have been marked as obsolete.)
If you determine that a change in the .NET Framework 4 has broken your application, check the Runtime Settings Schema to determine whether you can use a runtime setting in your application configuration file to restore the previous behavior.
If you encounter an issue that is not documented, file a Microsoft Connect bug and contact netfxcf@microsoft.com with the bug number.
For .NET Framework 1.1 applications:
Check .NET Framework 4 Migration Issues for any changes that might affect your application and apply the workaround described.
Check Changes in .NET Framework 3.5 SP1 and Changes in .NET Framework 2.0 for any changes made in those versions.
If you are recompiling existing source code to run on the .NET Framework 4, or if you are developing a new version of an application or component that targets .NET Framework 4 from an existing source code base, check What's Obsolete in the .NET Framework for obsolete types and members, and apply the workaround described. (Previously compiled code will continue to run against types and members that have been marked as obsolete.)
If you determine that a change in the .NET Framework 4 has broken your application, check the Runtime Settings Schema to determine whether you can use a runtime setting in your application configuration file to restore the previous behavior.
If you encounter an issue that is not documented, file a Microsoft Connect bug and contact netfxcf@microsoft.com with the bug number.
Compatibility and Side-by-Side Execution
If you cannot find a suitable workaround for your issue, remember that the .NET Framework 4 runs side by side with 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 application in its best environment. For more information about side-by-side execution, see Side-by-Side Execution.
See Also
Concepts
What's New in the .NET Framework 4
.NET Framework 4 Migration Issues