ASP.NET Side-by-Side Overview

The .NET Framework allows you to install multiple versions of the common language runtime on the same computer. By default, when the .NET Framework is installed on a computer where the runtime is already installed, all ASP.NET applications are automatically updated to use that version of the .NET Framework. Although later versions of the .NET Framework are designed to be backward compatible, you might want to configure an ASP.NET application to use a specific version of the runtime.

Background

Traditionally, when a component or application is updated on a computer, the older version is removed and replaced with the newer version. If the new version is not compatible with the previous version, this usually breaks other applications that use the component or application. The .NET Framework provides support for side-by-side execution, which allows multiple versions of an assembly or application to be installed on the same computer concurrently. Since multiple versions can be installed simultaneously, managed applications can select which version to use without affecting other applications that use a different version.

In ASP.NET, applications are said to be running side-by-side when they are installed on the same computer, but use different versions of the .NET Framework. The following topics describe side-by-side support in ASP.NET and how to configure ASP.NET applications for side-by-side execution.

The .NET Framework allows you to install multiple versions of the common language runtime on the same computer. By default, when the .NET Framework is installed on a computer where the runtime is already installed, all ASP.NET applications are automatically updated to use that version of the .NET Framework. The only exceptions are applications that are bound to an incompatible version of the runtime or to a later version of the runtime. (Compatibility is typically determined by the .NET Framework version number. Major version differences are usually incompatible, whereas minor updates and build number version differences are compatible.) Although later versions of the .NET Framework are designed to be backward compatible, you might want to configure an ASP.NET application to use a specific version of the runtime.

Script Maps for ASP.NET Applications

When multiple versions of the .NET Framework are installed on the same computer, each installation has its own version of the ASP.NET ISAPI extension (Aspnet_isapi.dll). The ASP.NET ISAPI extension determines which version of the .NET Framework an application will use. You can configure an ASP.NET application to use any ASP.NET ISAPI extension. To specify which ASP.NET ISAPI extension to use for an ASP.NET application, a script map (sometimes referred to as an application map) is registered with Internet Information Services (IIS) for the application.

A script map associates a file name extension (such as .aspx) and HTTP verb (such as GET and POST) with the appropriate ISAPI extension. For example, when IIS receives a request for an .aspx file, the application's script map directs IIS to forward the .aspx file to the appropriate version of the ASP.NET ISAPI extension. The script map for each ASP.NET application is normally set in the Internet Information Services management console and can be applied directly to an application, or it can be inherited from a parent application. By default, when the .NET Framework is installed, the script maps for all existing ASP.NET applications are automatically updated to use new ASP.NET ISAPI extension, unless the application uses a later version or an incompatible version.

To make it easier to reconfigure the script map for an ASP.NET application, each installation of the .NET Framework has its own version of the ASP.NET IIS Registration tool (Aspnet_regiis.exe). By default, this tool is installed in the following directory:

%system root%\Microsoft.NET\Framework\versionNumber

You can use this tool to map an ASP.NET application to the version of the ASP.NET ISAPI extension that matches the tool.

The tool can also be used to display the status of all installed versions of ASP.NET, register the associated version of ASP.NET, create client-script directories, and perform other configuration operations.

For more information about script maps and IIS configuration, see Setting Application Mappings in IIS 6.0 (IIS 6.0). For more information on updating script maps for an ASP.NET application, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe).

ASP.NET Performance Counters

Performance counters enable you to monitor the operation of ASP.NET from the Windows Performance console. Each version of the .NET Framework installs a separate set of performance counter objects to monitor ASP.NET applications and to monitor ASP.NET as a whole. These objects use the naming conventions "ASP.NET Apps v.X.X.XXXX.X" and "ASP.NET v.X.X.XXXX.X", respectively, where v.X.X.XXXX.X denotes the ASP.NET version.

In addition, the .NET Framework also installs ASP.NET system and ASP.NET application performance counters that apply to any installed versions of ASP.NET. Although these counters are valid for all versions of ASP.NET, they always correspond to the latest installed version. If the latest version of ASP.NET is uninstalled, these counters are automatically re-associated with the latest remaining version of ASP.NET.

ASP.NET State Service

ASP.NET state service can be used to manage session state on a computer. All versions of ASP.NET that are installed on the same computer share the state service that is installed with the latest version of ASP.NET. This version is registered with a service name of aspnet_state. Therefore, when this version of ASP.NET is uninstalled, the latest remaining version of the service on the computer is then registered and used in its place. For more information on the ASP.NET state service, see Session-State Modes.

ASP.NET SQL State Server

ASP.NET SQL state server is used to manage session state in SQL on a computer. All versions of ASP.NET that are installed on the same computer share the SQL state server that is installed with the latest version of ASP.NET. When this version of ASP.NET is uninstalled, the latest remaining version on the computer is then registered and used in its place. For more information on the ASP.NET SQL state server, see Session-State Modes.

Managing Multiple Versions of ASP.NET

The .NET Framework enables you to install multiple versions of the common language runtime (CLR) on the same computer. This enables an ASP.NET application to use the version it needs without affecting other applications. The following sections describe how to install, uninstall, and redistribute multiple versions of ASP.NET on the same computer.

Installing Multiple Versions of ASP.NET

To add a version of ASP.NET to a computer, run the .NET Framework redistributable package setup program (Dotnetfx.exe) for the version you want to install. By default, all existing ASP.NET applications are automatically reconfigured during installation to use the installing version of the runtime if the following conditions are met:

• The .NET Framework version being installed is later than the version that is currently mapped to the application.

• The .NET Framework version being installed is compatible with the version mapped to the application. In general, the version number determines compatibility. Minor revision and build number changes are usually compatible, whereas major revision numbers are not.

  Note

  Although ASP.NET applications are automatically updated to use the version of ASP.NET being installed if the preceding conditions are met, custom configuration settings in the current Machine.config file are not transferred to the newly installed Machine.config file. If your application uses custom configuration settings, be sure to either manually update the new Machine.config file or use the ASP.NET IIS Registration tool (Aspnet_regiis.exe) to remap the application back to the previous version of ASP.NET.

To prevent automatic remapping of all existing applications to the version of the .NET Framework being installed, use the /noaspupgrade command-line option with the Dotnetfx.exe setup program. The following command shows the syntax:

Dotnetfx.exe /c:"install /noaspupgrade"

For more information on the .NET Framework redistributable package, see Redistributing the .NET Framework.

Uninstalling a Version of ASP.NET

If you have multiple versions of ASP.NET installed on a computer, you can uninstall a specific version. You usually uninstall ASP.NET by uninstalling the .NET Framework through the Add or Remove Programs item in the Windows Control Panel. During the uninstall process, the setup program calls the ASP.NET IIS Registration tool (Aspnet_regiis.exe) with the -u option (uninstall flag).

The -u option of the Aspnet_regiis.exe tool performs the following actions:

• All ASP.NET applications currently mapped to the ASP.NET version being uninstalled are remapped to the latest compatible version of ASP.NET on the computer. If no compatible version exists, the script map for the application is removed completely.

  Warning

  Removing the script maps will cause IIS to serve ASP.NET pages as literal text. This could potentially expose source code to the client.

• If the ASP.NET version you are uninstalling is currently the latest version, the ASP.NET state service is mapped to the latest compatible version. If no compatible version exists, the ASP.NET state service is uninstalled. (The ASP.NET state service, which is shared across all compatible versions of ASP.NET, is always mapped to the latest installed version of ASP.NET.)

• Performance objects and the associated performance counters for the version being uninstalled are removed. The generic performance objects and counters that apply to all installed versions of ASP.NET and those for ASP.NET applications are directed to the latest installed version remaining on the computer.

• If no additional ASP.NET installations remain on the computer, the ASPNET user account and the associated access control lists are removed.

For information on other effects of installing multiple versions of ASP.NET, see ASP.NET Side-by-Side Overview.

Third-Party Redistribution of the .NET Framework

Third-party applications can package and install the .NET Framework as part of their setup under a special redistribution license. This enables an application to install the specific version of the .NET Framework it needs to run. The .NET Framework redistributable package (Dotnetfx.exe) is provided for an application to deploy with the runtime. The default installation script of Dotnetfx.exe might not suit the needs of your application. If so, it is up to you to use the options described below for installing the .NET Framework as part of an application's setup.

For more information on the .NET Framework redistributable package, see Redistributing the .NET Framework. For more information on the end user license agreement (EULA) of the redistributable package, see Where to Obtain the .NET Framework Redistributable Package.

Disabling Automatic Script Map Updates

By default, when the .NET Framework is installed on a computer with an existing installation, all ASP.NET applications are automatically updated to use the new version of the .NET Framework, unless the applications are bound to an incompatible version of the runtime or to a later version of the runtime. Usually, only a system administrator performs this type of installation. When the .NET Framework is installed as part of an application's setup, it should not force other applications on the computer to use that version of the runtime.

As part of the setup script, Dotnetfx.exe normally calls the ASP.NET IIS registration tool (Aspnet_regiis.exe) with the -i option to install ASP.NET. This option attempts to update the script maps of all existing ASP.NET applications. To prevent the installation from automatically updating the script maps of other applications on the computer, use the /noaspnetupgrade option when issuing the Dotnetfx.exe command. This option causes the setup program to use the -ir option of Aspnet_regiis.exe instead, which skips the automatic script map updates, default documentation, and MIME swapping steps. The following command shows the syntax:

Dotnetfx.exe /c:"install /noaspupgrade"

Manually Updating Script Maps

Sometimes it is necessary to manually set up the script maps for an application. If the application needs its own virtual directory that targets the version of the .NET Framework being installed, be sure the application's setup program also explicitly calls Aspnet_regiis.exe with the -s or -sn option to set up the script maps.

The following shows a sample command line that updates the script maps for an application named SampleApp1.

Aspnet_regiis.exe -s W3SVC/1/ROOT/SampleApp1

For more information, see the ASP.NET IIS Registration Tool (Aspnet_regiis.exe).

.NET Framework Assembly Unification

In side-by-side execution, it is possible for an application to be composed of components that are built using different versions of the .NET Framework. This can create conflicts between the dependencies of the components. For example, suppose component A is built using .NET Framework version 1.1 and needs to use version 1.1 of the System.Data assembly. Component B is built using the .NET Framework version 1.1 and needs to use version 2.0 of the System.Data assembly. If the assembly versions are incompatible, but are loaded at the same time, this could lead to unintended type mismatches or other problems.

How an Application Determines Which .NET Framework Version to Use

To allow different versions of the same assembly to be used, when an application uses components that are built on different versions of the .NET Framework, the version that is associated with an application determines which version of the .NET Framework assemblies are used by the application and by all of its components. In the example, if the application is mapped to version 2.0 of the .NET Framework, version 2.0 of the System.Data assembly is loaded and shared by all components used in the application. The reference from component A to version 1.1 of the System.Data assembly is promoted at run time to reference version 2.0.

If you obtain an updated version of a specific assembly, you can associate your application with the assembly independently of the version of the .NET Framework your application is mapped to. To do so, you can add <bindingRedirect> elements to the Machine.config or Web.config files. These elements associate an application with an updated assembly that replaces an existing assembly for certain types of applications. For example, if an updated version of System.Web.Service.dll is released in the future that supports SOAP version 1.2, you might want your application to use that version instead of the version that was installed with the .NET Framework originally.

This behavior can also be overridden in the ASP.NET host configuration file (Aspnet.config). ASP.NET uses this file to ensure that the versions of System.Web.dll and System.Web.RegularExpressions.dll always match the version associated with an application, regardless of any overrides specified in the Web.config file.

Sometimes you might want to use a component that was built using a later version of ASP.NET in an application built with an earlier version. The ASPNET ISAPI version associated with an application always determines the version of the runtime used for an application. If the application is configured to use the earlier version of the .NET Framework, the component will automatically be redirected at run time to use that version as well.

When using a component built with a later version of the .NET Framework in an application built on an earlier version, consider the following:

• Make sure the component does not use any features or depend on any behaviors specific to the later version of the .NET Framework. These features might not be available in the earlier version of the runtime.

• ASP.NET uses script maps in IIS to bind an application to a version of the runtime. <supportedRuntime> and <requiredRuntime> configuration elements are not applicable to ASP.NET applications.

Alternatively, if the runtime version used to build the component is installed on the computer, you could also reconfigure the application to use the later runtime version. Since later versions of the .NET Framework are designed in general to be backward compatible, most application features should work without many modifications. However, you should test carefully to be sure that running the application under a new version of the .NET Framework does not introduce errors into your application.

Back to top

See Also

Reference

Back to top

Other Resources

Side-by-Side Execution