Microsoft. NET Framework 1.1 and 2.0 (Beta) compatibility

Brief introduction

Microsoft. NET Framework 2.0 is built on the successful foundation of Microsoft. NET Framework 1.0 and 1.1 to provide the best runtime environment for WEB and Microsoft Windows client applications 。 For. NET Framework 1.1 applications, Microsoft's compatibility goal is that these applications can run smoothly on the. NET Framework 2.0 (except for a set of recorded changes). During the Beta 2 release, we have not yet achieved this goal and are looking for feedback on these application issues to resolve these issues before the. NET Framework 2.0 is released. This article explores the compatibility scenarios for applications and provides best practices recommendations for each phase.

Back to the top of the page

Executive Summary

•

A complete list of known destructive changes is provided here. This list is available for Beta 2 and will be updated further for RTM. If you are experiencing changes other than this list, please send the message to netfxcmp@microsoft.com.

•

Microsoft recommends that you test your. NET Framework 1.1 applications for the. NET Framework 2.0 during the Beta 2 period. The compatibility test scenario provides guidance for this operation.

•

Even if the. NET Framework 2.0 is installed on your computer, a stand-alone version of Microsoft Windows client or WEB application built using the. NET Framework 1.1 will also automatically run on the 1.1 framework.

•

A managed add-in for a native application (for example, Microsoft Office or Internet Explorer) will automatically run on the latest version of the. NET Framework installed on your computer. Before deploying this version of the framework, developers and IT managers should test these add-ins against the. NET Framework 2.0.

•

Now, we are still looking for more applications to test. If you are interested in providing your. NET Framework 1.1 application, please send the message to netfxcmp@microsoft.com.

Back to the top of the page

Definition of destructive changes

Destructive changes are those that make some application or development scenarios behave abnormally in the. NET Framework (the run-time Disruptive change) or Visual Studio (Design/compile/project upgrade). These changes are not necessarily those that we have discovered that destroy the application, or, more precisely, the behavioral changes found during design inspection and testing that might affect the application. In fact, in all of our application compatibility tests, less than 10 changes were found to affect the application.

Runtime changes can be grouped into two categories: the first (and most rare) is an API disruptive change, including changing function signatures or deleting functions. In almost all cases, these changes are for security reasons. In the entire. NET Framework 2.0, this class changes less than 5.

The second category (the more common destructive type of change) is a destructive change of behavior, including the behavior of changing the method. Examples of such changes include changing the exceptions that are thrown due to a particular error, and changing the precision of floating-point operations.

All known destructive changes in the. NET Framework 2.0 have been carefully examined and recorded for Beta 2. There are a number of reasons for disruptive changes, including conformance to standards, customer feedback, and correctness issues. We have tried to record these changes in detail, but we believe many of these changes will still affect a small number of users. Examples of each type of Run-time library change follow these guidelines:

•

Standard: The ISO mark in the Kyrgyzstan System.Globalization is updated from the KZ to KY.

•

Compliant: The HTML rendered in asp.net is updated to conform to the standard XHTML 1.0 transitional.

•

Customer feedback: Changed the ASP.net project model to respond to customer feedback.

•

Correctness: Floating point precision has been added in some cases. This has been documented as a possibility in the CLI specification.

As with all beta products, we are looking for more feedback. If you are experiencing questions about Beta 2 products, please report to us via Msdnproductfeedbackcenter. For deployment and compatibility issues, please send a message to netfxcmp@microsoft.com. We will update the list of destructive changes to the. NET Framework version 2.0 based on the feedback received.

Back to the top of the page

Application loading mechanisms and possible issues

By default, applications built using the. NET Framework will use the version of the Framework that is used at build time, if the version is installed on the computer. The following table specifies the loading behavior of applications under different. NET Framework configurations on the target computer.

The application type installs 1.1 of the computer installs 2.0 of the computers at the same time installs 1.1 and 2.0 computers

1.1 Standalone applications (WEB or Microsoft Windows clients)

Using 1.1 load

Using 2.0 Load

Using 1.1 load

2.0 standalone applications (WEB or Microsoft Windows clients)

Failed

Using 2.0 Load

Using 2.0 Load

1.1 Add-ins for native applications (for example, Office or Internet Explorer)

Using 1.1 load

Using 2.0 Load

If the process is not configured to run in 1.1, then use the 2.0 load

2.0 add-ins for native applications (for example, Office or Internet Explorer)

Failed

Using 2.0 Load

Using 2.0 Load

The application may fail if the application code built with. NET Framework 1.1 is loaded through the. NET Framework 2.0 and a destructive change is encountered. In the table above, bold cells indicate where these situations may occur. The following sections provide information about how to reduce potential problems in these situations.

Back to the top of the page

Testing applications developed with the. NET Framework 1.1 in. NET Framework 2.0

Because the application will run with the Framework version used at build time, there are two ways to run an application using the. NET Framework 2.0:

•

Install and test on a computer that has only the. NET Framework 2.0 Beta 2 installed.

•

Install the beta version on a computer that has the. NET Framework 1.1 installed. Use the steps outlined on gotdotnet.com to force your application to run with the. NET Framework 2.0.

Back to the top of the page

Strategies to reduce possible compatibility issues

By following one of the strategies described below, developers can reduce the likelihood that an application will be affected by the. NET Framework changes. More information about testing is provided in the compatibility test scenario.

Before releasing the final version of the. NET Framework 2.0, we will examine the compatibility status and consider restoring those changes when the destructive changes affect the application. When you perform a compatibility test, if you find that your application needs to make some changes to run correctly on the new version, log the error on the Msdnproductfeedbackcenter.

1.

Testing and Repair
Always proceed;

One possible way to use applications built from. NET Framework 1.1 is to test the application with the. NET Framework 2.0, make some necessary changes, and ensure that the application runs on the two versions of the framework.

Developing and testing meaning this will require the team to test the two versions of the Framework, thus extending the application's Test matrix. It may also require the developer to make some modifications to the source code to ensure that the application runs on the. NET Framework 1.1 and the. NET Framework 2.0.

Market and operational implications the application owner needs to communicate the problem with customers and users, and provide them with an updated version of the two versions of the compliant Framework.

2.

Use the. NET Framework 1.1 Department
For standalone managed applications

By default, managed applications built using the. NET Framework will run with the version that is used at build time. If you have installed the. NET Framework 1.1 on the target machine, you do not need to change any applications. To enable this scenario, the application owner should continue to publish the. NET Framework 1.1 along with its application, or ensure that the. NET Framework 1.1 is installed on all target machines.

If a. NET Framework application is hosted on a local host (such as Microsoft Office or Microsoft Internet Explorer), the application will use the latest. NET Framework version installed on the computer. This could mean that an application built on the. NET Framework 1.1 might be forced to run with the. NET Framework 2.0. If you write a native application that hosts managed code, whether through a direct host or through COM Interop, you can configure the native EXE and choose the version of the runtime that is used to build managed code, otherwise your component needs to run on the latest version installed on your computer. For more detailed information, see the following parallel documentation.

Development and test implications from the perspective of development and testing, this requires ensuring that the. NET Framework 1.1 is installed on all machines. If you are a boarding component (an application that loads a managed component), you may need to modify the application's configuration file to ensure that the. NET Framework 2.0 is loaded by the hosting process, even if you have installed the.

Market and operational implications from a market and operational point of view, this involves communicating the need for users to install the. NET Framework 1.1. In the case of a local host, when a user installs the. NET Framework 2.0 on its system, it may also need to have customers and users install a new version (or update the application configuration file).

3.

Upgrade to 2.0:
Applies to all applications, but requires installation of the. NET Framework 2.0

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

In Beta 2, ASP.net developers need to understand the changes made in the project system and the compilation model that may affect how their applications are upgraded to 2.0. Based on user feedback, we have implemented a supplement to the ASP.net project upgrade system, which means that most applications require only minimal changes.

Developing and testing meaning this requires updating the application to accommodate all destructive changes, testing the application in the. NET Framework 2.0, and modifying the application to take advantage of all. NET Framework 2.0 features. Developers need to update the application installer to publish the. NET Framework 2.0. (Note: During Beta 2 "Keep active", ISVs may not republish the. NET Framework 2.0.) ）

Market and operational implications the application owner needs to communicate with the customer, and the user needs to install the. NET Framework 2.0 and the updated application BITS.

Back to the top of the page

Potential hotspots

There are two well-known compatibility issues that are worth mentioning:

•

Serialization: Any serialized data between versions of the. NET Framework may be unstable because serialization relies on the internal structure of the object. This may affect data serialized to a file, or data serialized through. NET Remoting for communication. We are currently investing in version-fault-tolerant serialization and are expected to provide version-tolerant serialization when publishing Visual Studio 2005 and. NET Framework 2.0.

•

Check for specific versions of the. NET Framework: The application will check at the time of installation whether a specific version of the framework is installed on your computer, or check that a specific version of the framework is version sensitive (version-brittle) at run time. This is a common consideration in installing programs that take advantage of managed code.

Back to the top of the page

Submit the application to test

We have always wanted to extend the list of applications for testing compatibility, especially for line-of-business applications. If you submit your application, you will receive the following services:

•

We will test your application on the latest Whidbey BITS. Depending on the compatibility requirements of the test, the test levels for each application vary.

•

We will report you through/fail results and Microsoft discovery (in case of failure) application issues and recommendations to mitigate the problem.

•

We are not committed to ensuring that your application runs correctly on the latest BITS. However, the results will help us understand all the compatibility issues that customers may experience. We will do our best to ensure that existing applications can run correctly on the. NET Framework 2.0.

•

You are responsible for providing the application, all necessary prerequisites (test data, other resources), and installation instructions on how to install and run the application on a new computer. Microsoft cannot test any applications that require domain-specific resources or that contain real customer data.

Some additional information we would like to collect include:
Company Name
Application Name
Application types (Web applications, desktop applications, COM, etc.)
Application development technology (including language)
Application features (including the importance of the business)
Application Size (LOC, module)

If you want to submit the application, please send the message to netfxcmp@microsoft.com.

Back to the top of the page

Put into action

•

Test your 1.1 applications on 2.0 and find out if there is a problem. Report these issues through Msdnproductfeedbackcenter.

•

Provide feedback through netfxcmp@microsoft.com on other issues, including compatibility and deployment issues.

•

Submit more applications to test.

Back to the top of the page

Appendix and background

NET Framework SDK Documentation and articles describe the parallel issues in more detail, and how to configure your application for a specific application model (for example,. EXE application, Web application, or managed COM component to run a specific version of the. NET Framework.

MSDN Documentation

•

The. NET Framework Developer ' s guide:targeting a. NET Framework Version
Http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcontargetingnetframeworkversion.asp

•

Big Red Switch information on GotDotNet
http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=4caff66c-df51-40ab-bd88-090d34e77520

•

. Config File Information
Http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconSpecifyingWhichRuntimeVersionToUse.asp

•

Side-by-side Execution of the. NET Framework
Http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnnetdep/html/sidexsidenet.asp

•

asp.net application in IIS; The. NET Framework Developer ' s guide:configuring a asp.net application for a asp.net Version
Http://msdn.microsoft.com/library/en-us/cpguide/html/cpconconfiguringaspnetapplicationforaspnetversion.asp

•

NET Framework Developer ' s guide:side-by-side Execution for COM Interop
Http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconSide-By-SideExecutionForCOMInterop.asp

•

Compatibility Considerations and Version Changes
Http://www.gotdotnet.com/team/changeinfo/default.aspx

Background of parallel frameworks and functions

There are multiple versions of the. NET Framework (v1.0, v1.1, v2.0). Multiple. NET Framework versions can be installed "parallel" on the same computer, and users can install multiple versions of an application such as Office (for example, installing OfficeXP and Office2003 on the same computer). On Windows XP and Windows Server 2003, multiple. NET Framework versions can run in parallel in different processes. In other words, a process can run applications on the. NET Framework 2.0, while other processes can also run applications on the. NET Framework 1.1.

Parallel runtime behavior of applications on the. NET Framework 1.0, 1.1, and 2.0

Managed application: When an application is started on the. NET Framework 1.0, 1.1, or 2.0, the CLR (Mscoree) looks at the version of the. NET Framework that is recorded in the application and attempts to compile the. NET Framework version of the application Run the application on. If the version is not already installed on the computer, the CLR will attempt to start the application on the most recent. NET Framework and CLR. For example, if an application that is compiled for. NET Framework 2.0 runs on a computer that has only the. NET Framework 1.1 installed, the application will be forward compatible to run on the. NET Framework 1.1. Similarly, if an application that is compiled for. NET Framework 1.1 runs on a computer that has only the. NET Framework 2.0 installed, the application is backward compatible to run on the. NET Framework 2.0.

Managed components for native applications: managed components for native applications are managed code that is loaded directly through the hosting API or COM Interop in a process that is started in the native EXE. There are two main scenarios for loading managed code in this way:

•

Scenario 1: Managed code is an add-in for a native third-party application

•

Scenario 2: Managed code is part of a native application

In these cases, the default behavior is to load the latest runtime that is installed on the computer.

In Scenario 1, you cannot understand which other managed components might be loaded in a process, so the managed add-in cannot choose which runtime to load, but instead must load the latest runtime on the computer.

However, in Scenario 2, managed code is actually part of the application, so the developer knows very well which runtime the managed code needs. In these cases, we recommend that the application specify the runtime that it will load. If the application hosts the runtime, it should specify the exact runtime (rather than empty) through the host API. If managed code is loaded through COM interop, the application developer should place a configuration file on the native EXE and have the configuration file specify a supported runtime.

asp.net applications: Web applications are different because versions of the. NET Framework are selected by configuring specific IIS virtual directories to use a specific version of the ASP.net ISAPI DLL through the IIS administration tools. The asp.net ISAPI DLL can load the appropriate. NET Framework version for the WEB application.