Microsoft .NET Framework 1.1 and 2.0 Compatibility

  • Article

 

Development and Deployment Best Practices

Microsoft Corporation

May 2006

Contents

Introduction
Executive Summary
Definition of Breaking Changes
Application Load Mechanisms and Possible Issues
Testing an Application Developed Using the .NET Framework 1.1 Against the .NET Framework 2.0
Tactics for Mitigating Possible Compatibility Issues
Potential Hotspots
Call to Action
Appendix and Background

Introduction

The Microsoft .NET Framework 2.0 builds on the success of the Microsoft .NET Framework 1.0 and 1.1 to provide the best runtime environment for Web and Microsoft Windows client applications. Microsoft's compatibility goal for .NET Framework 1.1 applications is that they should work smoothly on the .NET Framework 2.0 except for a set of documented changes as provided here.

This article discusses application compatibility scenarios and provides recommendations on best practices for developers to handle compatibility issues.

Executive Summary

  • A complete list of known breaking changes is available here.
  • Microsoft recommends testing your .NET Framework 1.1 applications against the .NET Framework 2.0. Instructions for doing that are provided in Compatibility Testing Scenarios.
  • Standalone Microsoft Windows client or Web applications that were built with the .NET Framework 1.1 will automatically run against that framework even if the .NET Framework 2.0 is installed on the computer.
  • Managed add-ins to native applications, such as Microsoft Office or Internet Explorer, will automatically run against the latest version of the .NET Framework installed on the computer. Developers and IT managers should test add-ins against the .NET Framework 2.0 before deploying that version of the Framework.
  • To discuss and publish information about application compatibility use this MSDN forum: .NET Framework Deployment

Definition of Breaking Changes

Breaking changes are changes in either the .NET Framework (runtime breaking changes) or Visual Studio (design/compile/project upgrade) that make certain application and development scenarios behave differently. These are not necessarily changes that we have found to be breaking an application; rather, these are changes in behavior discovered during design review and testing that could potentially impact an application. Indeed, in all of our application compatibility testing, fewer than 10 of these have been found to impact an application.

Runtime changes can be classified into two categories: The first (and rarest) is an API breaking change where the signature of a function changed or a function was removed. In almost all cases these changes were made due to security concerns. There are fewer than 5 of these throughout the entire .NET Framework 2.0.

The second, more common type of breaking change is a behavior breaking change where the behavior of a method changed. Examples of this type of change include changing the exception thrown due to a particular error and changing the precision of floating point operations.

All known breaking changes in the .NET Framework 2.0 were reviewed in detail and are documented here.

Breaking changes were made for a number of reasons including standards compliance, customer feedback, and correctness. We have attempted to be exhaustive in documenting changes, but believe that many of these changes will impact very few users. An example of each of the types of runtime changes follows:

  • Standards Compliance: The ISO tag in System.Globalization for Kyrgyzstan was updated from KZ to KY.
  • Standards Compliance: The HTML rendering in ASP.NET was updated to be XHTML 1.0 Transitional, which is standards compliant
  • Customer Feedback: The ASP.NET project model was changed in response to customer feedback.
  • Correctness: Floating point precision was increased in certain cases. This is something that was already documented in the CLI specification as being possible.

To discuss and publish information about application compatibility use this MSDN forum: .NET Framework Deployment

Application Load Mechanisms and Possible Issues

By default, an application built using the .NET Framework will run using the version of the Framework it was built against if that version is installed on the computer. The following table specifies the loading behavior of applications under different configurations of the .NET Framework on the target computer.

Table 1.

Application type Computer with 1.1 Computer with 2.0 Computer with 1.1 and 2.0
1.1 stand-alone application (Web or Microsoft Windows client) Loads with 1.1 Loads with 2.0 Loads with 1.1
2.0 stand-alone application (Web or Microsoft Windows client) Fails Loads with 2.0 Loads with 2.0
1.1 add-in to a native application (such as Office or Internet Explorer) Loads with 1.1 Loads with 2.0 Loads with 2.0 unless the process is configured to run against 1.1
2.0 add-in to a native application (such as Office or Internet Explorer) Fails Loads with 2.0 Loads with 2.0

On the occasions where application code built against the .NET Framework 1.1 is loaded by the .NET Framework 2.0 and encounters a breaking change, the application may fail. The situations where this is possible are indicated by the bolded cells in the table above. The following sections provide information on how to mitigate potential problems in these cases.

Testing an Application Developed Using the .NET Framework 1.1 against the .NET Framework 2.0

Since applications will run using the version of the Framework with which they were built, there are two possibilities for running an application using the .NET Framework 2.0:

  • Install and test on a computer with only the .NET Framework 2.0 installed (recommended).
  • Install the framework on a computer that already has the .NET Framework 1.1. Use the steps outlined on gotdotnet.com to force the application to run using the .NET Framework 2.0.

Tactics for Mitigating Possible Compatibility Issues

Developers can mitigate the possibility of an application being impacted by changes to the .NET Framework by following one of the tactics described below. More information on testing is available in Compatibility Testing Scenarios.

  1. Test and fix
    Always works; recommended

    One possibility for using an application built against the .NET Framework 1.1 is to test it against the .NET Framework 2.0, make any necessary changes, and ensure that the application works against both versions of the Framework.

    ***Development and Testing Implications
    ***This will expand the test matrix of an application by requiring teams to test against two versions of the Framework. It may also potentially require developers to make modifications to the source code to ensure that the application works with both the .NET Framework 1.1 and the .NET Framework 2.0.

    ***Marketing and Operations Implications
    ***Application owners will need to communicate the issue to customers and users and potentially provide them with an updated version of the application that is compatible with both versions of the Framework.

  2. Deploy with the .NET Framework 1.1
    Works for stand-alone managed applications

    By default, managed applications built using the .NET Framework will run with the version that they were built against. If the .NET Framework 1.1 is installed on the target computer it will not require any application change. To enable this scenario, application owners should continue to distribute (or make sure the framework is available) the .NET Framework 1.1 with their application or ensure that it is installed on all target computers.

    If a .NET Framework application is hosted inside a native host such as Microsoft Office or Microsoft Internet Explorer, the application will use the latest version of the .NET Framework installed on the computer. This may mean that an application that was built on the .NET Framework 1.1 will be forced to run using the .NET Framework 2.0. If you wrote the native application that hosts the managed code, either through direct hosting or through COM Interop, then you have the ability to configure the native exe and choose the runtime version your managed code was built on; otherwise your component will need to run on the latest version installed on the computer. For more details, see the side-by-side documentation below (configuring an exe to target previous framework versions is not recommended in a case of Internet Explorer and Office applications).

    ***Development and Testing Implications
    ***From a development and testing point of view, this requires ensuring that the .NET Framework 1.1 is installed on all computers. In the case of hosted components (applications that load managed components), you may need to modify the application's config file to ensure that the hosting process loads the .NET Framework 1.1 even if the .NET Framework 2.0 is installed on the computer.

    ***Marketing and Operations Implications
    ***From a marketing and operations point of view, this involves communicating the need to have the .NET Framework 1.1 installed. In the case of a native host, it may also require having customers and users install a new version (or an application config file update) if they are installing the .NET Framework 2.0 on their system.

  3. Upgrade to 2.0:
    Works for all applications, but requires the .NET Framework 2.0

    Developers who want to take advantage of the new features in the .NET Framework 2.0 should upgrade the application to target the .NET Framework 2.0. This includes recompiling the code, testing the application, and making any necessary changes.

    ASP.NET developers will need to be aware of changes in the project system and compilation model that might affect how their application upgrades to 2.0.

    ***Development and Testing Implications
    ***This requires updating the application to adapt to any breaking changes, testing the application against the .NET Framework 2.0, and modifying the application to take advantage of any .NET Framework 2.0 features. Developers will need to update application installation programs to distribute the .NET Framework 2.0.

    ***Marketing and Operation Implications
    ***Application owners will need to communicate to customers and users the need to install the .NET Framework 2.0 and the updated application bits.

Potential Hotspots

There are two well-known hotspots for compatibility that are worth mentioning:

  • Serialization: Any data serialized between versions of the .NET Framework is potentially fragile, since serialization relies on the internal structure of the object. This can impact data that is serialized to a file or data that is serialized for communication through .NET Remoting. If you encounter this problem, you can mitigate it by serializing into a common format (like XML).
  • Checking for a particular version of the .NET Framework: Applications that check whether a particular version of the Framework has been installed on the computer during setup or check for a specific version of the Framework while running are version-brittle. This has been a particularly common concern among setup programs that leverage managed code running as customer action.

Call to Action

  • Test your 1.1 applications on 2.0 and find if there are issues. Report the issues (especially if you have a fix for them) in this discussion forum: .NET Framework Deployment
  • Talk to your customer about this and inform them about issues and solutions you have for them.

Appendix and Background

NET Framework SDK documents and articles describe side-by-side in further detail and how to configure your application to run a particular release of the .NET Framework for a particular application model, for example .EXE application, Web application, or managed COM component.

MSDN Documentation

Background on Side-by-Side Frameworks and Features

There are multiple releases of the .NET Framework (v1.0, v1.1, v2.0). These multiple .NET Framework releases can be installed "side-by-side" on a single computer, in the same way that a user can install multiple versions of an application such as Office (for example, Office XP and Office 2003 on one computer). On Windows XP and Windows Server 2003, the .NET Framework releases run side-by-side in different processes. In other words, one process can be running an application on the .NET Framework 1.0 and at the same time another process can be running an application on the .NET Framework 1.1.

Side-by-Side Runtime Behavior of Applications on the .NET Framework 1.0, 1.1, 2.0

Managed applications: When the application is started up on the .NET Framework 1.0, 1.1 or 2.0, the CLR (mscoree) looks at the .NET Framework version recorded in the application and tries to run the application on the version of the .NET Framework that the application was compiled with. If that version is not installed on the computer, the CLR will attempt to start the application on the latest .NET Framework and CLR, for example, an application compiled for .NET Framework 1.0 running on a computer with only .NET Framework 1.1 will be rolled forward to run on the .NET Framework 1.1. Likewise, an application compiled for .NET Framework 1.1 running on a computer with only the .NET Framework 2.0 will be rolled forward to run on the .NET Framework 2.0.

Managed components for native applications: A managed component for a native application is managed code that is loaded, either directly through the hosting APIs or through COM interop, inside a process that was started by a native exe. There are two main scenarios when managed code is loaded in this manner:

  • Scenario 1: the managed code is an add-in to a native third-party application
  • Scenario 2: the managed code is part of the native application

The default behavior in these cases is to load the latest runtime installed on the computer.

In scenario 1 there is no way to know what other managed components might be loaded inside of the process and thus the managed add-in cannot make a choice about what runtime to load and must load with the latest on the computer (Microsoft Office and Internet Explorer are examples for such applications).

In scenario 2, however, the managed code is actually part of the application and the developer knows exactly which runtimes the managed code requires. In these cases we recommend that the application specifies which runtime it wants to load. If it hosts the runtime it should specify an exact runtime (rather than null) via the hosting APIs. If the managed code is loaded via COM interop, then the application developer should place a config file on the native exe that specifies a supported runtime.

ASP.NET applications: Web applications are different, in that the version of the .NET Framework is chosen by configuring a particular IIS virtual directory to use a particular version of the ASP.NET ISAPI DLL via the IIS administration tools. The ASP.NET ISAPI DLL loads the corresponding version of the .NET Framework for the Web application.