Side-by-Side Execution of the .NET Framework

 

Dennis Angeline
Microsoft Corporation

December 2002

Applies to:
   Microsoft® .NET® Framework
   Microsoft Visual Studio® .NET 2002

Summary: In-depth information about side-by-side execution of the .NET Framework intended for individuals who are building or configuring .NET Framework applications or components. (6 printed pages.)

Contents

Terminology
More Information
Deciding How to Configure Your Application
Configuring Windows Client Applications
Configuring Unmanaged Applications
Configuring Web Applications
For More Information

Terminology

A 1.0 application is an application that targets version 1.0 of the .NET Framework. All applications built with Visual Studio .NET 2002 are 1.0 applications.

A 1.1 application is an application that targets version 1.1 of the .NET Framework. All applications built with Visual Studio .NET 2003 are 1.1 applications.

More Information

The side-by-side support built into the .NET Framework allows multiple versions of the Framework to be installed on a single system. With the release of version 1.1 of the .NET Framework, application and component developers need to consider how their code operates on systems that have multiple versions of the Framework installed.

The 1.1 Framework is designed to be highly compatible with the 1.0 Framework. Microsoft has gone to great lengths to ensure that the vast majority of applications built on the 1.0 Framework continue to operate on the 1.1 Framework. This includes compatibility at a deeper level than just the public types and APIs. For example, we closely monitor changes in the implementation of APIs that might also affect compatibility. Thus, an API that returns a value that was not returned by its predecessor would still be considered incompatible.

While every effort has been made to retain compatibility, there are certain cases where the development team found it absolutely necessary to break compatibility. This is only done in the most serious cases after a thorough analysis of the impact of the change. Breaking changes are typically only made as a last resort to address security-related issues or serious flaws in existing functionality. Breaking changes are not made to improve the consistency or appearance of an API or to fix bugs that can be addressed through other reasonable means. Whereever compatibility is affected, Microsoft will publicly document the changes and provide potential workarounds. The complete list of breaking changes for the 1.1 Framework can be found at https://www.gotdotnet.com/team/changeinfo/Backwards1.0to1.1/default.aspx.

Despite the high degree of compatibility between the 1.0 and 1.1 Framework, most applications that use the 1.0 Framework are not automatically upgraded when the 1.1 Framework is installed. In fact, installing the newer versions of the .NET Framework does not affect most types of existing applications in any way. The 1.1 Framework is designed so that it can be installed or uninstalled from a system with no impact on applications that are using the 1.0 Framework. Similarly, applications built with the 1.1 version of the Framework are not affected when the older Framework is installed.

Note   Uninstalling an older version of the Framework can affect existing applications that depended on that version and are not perfectly compatible with the newer version.

Side-by-side execution does give application developers and systems administrators the ability to configure existing applications to use the newer version of the Framework, as appropriate. We believe that the decision to use one version of the Framework over another is a decision that only application developers or administrators can make in the context of a given application. In other words, true compatibility can only be assessed in the context of a specific application.

Therefore, applications can be tested with the new version of the Framework and configured to work with the new version when the application developer or administrator decides it is appropriate based on the outcome of their testing. Because of the high degree of compatibility between the two versions, we fully expect the vast majority of 1.0 applications to work equally well with either the 1.0 or 1.1 Framework. In the rare event that the application does not work on the 1.1 Framework, the application can be configured to only support the 1.0 Framework. Applications developers are therefore urged to test their applications with the 1.1 Framework and, when appropriate, configure their applications to work with either 1.0 or 1.1 or both.

While we fully expect version 1.0 applications to execute in the 1.1 Framework, allowing 1.1 applications to execute in the version 1.0 Framework is much more difficult. Getting this to work involves considerable forethought on the part of the developer to avoid using new functionality that is not available in the 1.0 Framework. Applications that use features that are only found in the 1.1 Framework simply will not operate in the 1.0 Framework. A list of these features can be found at https://www.gotdotnet.com/team/changeinfo/Forwards1.0to1.1/default.aspx.

Deciding How to Configure Your Application

The method of application configuration required varies depending on the type of application being built. Traditional Windows™ client applications (Windows Forms, console applications, and Windows services) are configured with an application configuration file. Web applications (ASP.NET and XML Web services) are configured through the Internet Information Services (IIS) administrator.

Configuring Windows Client Applications

An application developer or an administrator can test, or permanently redirect, 1.0 Windows client applications to the 1.1 Framework by providing an application configuration file. The application configuration file can direct the common language runtime (CLR) to load a specific version of the .NET Framework into the application's process. The version of the Framework that is loaded at run time can differ from the version with which the application was actually compiled.

The application configuration file is an .xml file located in the same directory as the application executable (.exe) file. The configuration file name must be the same as the .exe file name with ".config" appended to the end. For example, the application MyApp.exe would have a configuration file named MyApp.exe.config. Note that the configuration file can contain settings that affect other aspects of the application's behavior beside what version of the Framework it should run on.

The Framework version is affected by the contents of the startup section in the configuration file. In particular, the supportedRuntime element affects the choice of the Framework version. The startup section can contain one or more supportedRuntime elements; each element specifies a version of the Framework that the application supports. The supportedRuntime elements are ordered by preference. In other words, the most preferred version of the Framework is listed first. For example, an application that supports both the 1.0 and 1.1 Framework but prefers to use 1.1 Framework would have the following in the startup section of the application configuration file:

<configuration>
…
<startup>
   <supportedRuntime version="v1.1.4322" />
   <supportedRuntime version="v1.0.3705" />         
</startup>
…
</configuration>

The version number specified in the supportedRuntime element must match the subdirectory where the Framework installed. For example, the version 1.0 Framework is installed in the directory C:\Windows\Microsoft.Net\Framework\v1.0.3705; therefore, the version number specified in the configuration file is "v1.0.3705". Similarly, the 1.1 Framework is installed in the C:\Windows\Microsoft.Net\Framework\v1.1.4322 directory. There are no wildcards allowed in the supported runtime version number. Therefore, an application cannot be configured to support a version of the Framework that has not yet been released.

Note   As newer versions of the Framework are released for beta testing, version numbers will be made available.

The CLR determines which version of the Framework to load, based on the versions listed in the application's .config file and the versions that are available on the system where the application is executing. Configured applications will not run on any version of the Framework not included in the supportedRuntime list. The configuration can be modified at any time either before or after the application is deployed. Use care when modifying the configuration file since the setting contained in the file may affect other aspects of application behavior.

Unconfigured Windows Client Applications

Applications that do not carry a configuration file or at least the supportedRuntime element in their configuration files (unconfigured applications) execute with the version of the Framework that was used to build the application, provided that version of the Framework is installed on the local system. (The version of the Framework with which the application was built is contained in the header of the application .exe file.) When that version of the Framework is not available, the CLR uses a later version of the Framework in its place. In other words, an unconfigured application built with Framework 1.0 executes with 1.0 on a system that has both 1.0 and 1.1 installed. That same application executes with the 1.1 Framework on a system with only the 1.1 Framework installed. It is strongly recommended that applications be configured to support all versions of the Framework that are considered compatible, to provide for scenarios where one particular version may be available on the target machine. Note that an application can also provide for such situations by redistributing the version of the .NET Framework it requires, as explained at Redistributing the .NET Framework.

No Suitable Version Available

When no suitable version of the Framework is found to execute an application, the CLR displays a dialog box which lists the versions of the Framework that the application supports and asks the user to install one of the listed versions. This dialog can be suppressed by the setting the NoGuiFromShim key in the registry:

HKLM\\Software\\Microsoft\\.NETFramework\\NoGuiFromShim = 1

Configuring Unmanaged Applications

Many unmanaged Windows client applications (Windows client applications not built using the .NET Framework but rather an alternative programming model) use the services of managed components (components built using the .NET Framework) through COM Interop. Hosting a managed component on a Web page viewed within Internet Explorer is a perfect example of an unmanaged application (Internet Explorer) using the services of a managed component. Managed Windows client applications deployed to the desktop through no-touch deployment with Internet Explorer is another example. The unmanaged host applications can all be configured to use a specific version of the Framework for their managed components. By default, when the components are loaded by an unmanaged application, the managed component is loaded along with the newest available version of the Framework into the application's process. This behavior is somewhat different from the behavior of managed Windows client applications previously described. Unlike a fully managed application, unmanaged .exes lack the information in their header that describes the version of the Framework the code in question was built with; this leaves the CLR with no choice other than to load the latest available version of the Framework.

However, when a component requires a very specific version of the Framework, a configuration file like the one previously described can be provided for the unmanaged .exe (Internet Explorer, for example) that hosts the component. Note that the configuration file must exist for the .exe that hosts the component, not for the managed component itself. Ultimately, this means all managed components called by a particular unmanaged application run on the same version of the Framework, either the latest available version or the one designated in the application's .config file. These configuration files can be created from scratch using the XML example previously shown. The .config files should be named in the same manner: [Unmanaged App Exe Name] .exe.config (e.g., iexplore.exe.config).

Configuring Web Applications

Web servers can be configured to use separate versions of the .NET Framework for each individual Web site built using the .NET Framework (i.e., the ASP.NET libraries). All code executing within a given site uses the version specified for that site or for the server if a version is not specified for the site.

Rather than using configuration files to choose the Framework version, the configuration for each site is set within the IIS Administrative Console by selecting the specific versions of the ASP.NET ISAPI filter. The ASP.NET filter is set on ISAPI Filter tab of the Web Site Properties dialog. The filter can be set for each individual site. It can also be set for the entire Web server by changing the filter at the root Web site. The ASP.NET filter is implemented in the file aspnet_filter.dll. The 1.0 filter is located in the %windir%\ Microsoft.Net\Frameworks\v1.0.3705 directory. The 1.1 filter is located in the %windir%\ Microsoft.Net\Frameworks\v1.1.4322 directory.

The installation of the version 1.1 Framework automatically adds the 1.1 ASP.NET filter to the filter list on the Web server's root Web site. Updating the filter at the root level causes all sites that are not individually configured to start using the 1.1 version of the Framework. Any site that needs to continue to use the 1.0 Frameworks needs to be individually configured to use the 1.0 ISAPI filter. The configuration of the ISAPI filter can only be at the Web site level. Individual VRoots cannot be configured to use a different ISAPI filter.

For More Information

For more side-by-side configuration examples, see https://www.gotdotnet.com/team/changeinfo/default.aspx.