Managing Multiple Versions of ASP.NET

Article
10/17/2014

The .NET Framework allows you to install multiple versions of the runtime on the same computer. This allows an ASP.NET application to use the version it needs to run 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 installing .NET Framework version is later than the version that is currently mapped to the application.
The installing .NET Framework version 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.

CAUTION Although ASP.NET applications are automatically updated to use the installing version of ASP.NET if the preceding conditions are met, custom configuration settings in the current Machine.config file are not transferred to the installing 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 to the previous version of ASP.NET. For more information on remapping an application, see Configuring an ASP.NET Application for an ASP.NET Version.

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

Dotnetfx.exe /c:"install /noaspupgrade"

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

Security Lockdown Console in IIS 6.0

If you're using Internet Information Services 6.0, you might need to enable ASP.NET in the Internet Information Services management console after installing ASP.NET. IIS 6.0 introduces a new security lockdown console, which allows an administrator to selectively enable and disable functionality in IIS. When ASP.NET version 1.1 or later is installed on a computer that uses IIS 6.0, the installation script creates a metabase key for that version of ASP.NET. This metabase key allows ASP.NET to appear in the console as a configurable component. A separate key is created for each installed version of ASP.NET, allowing each version to be separately configurable in the console. When a version of ASP.NET is uninstalled from a computer, the respective key is also removed.

Note When ASP.NET is installed through the Add or Remove Programs item in Control Panel, or the Configure Your Server Wizard, ASP.NET is enabled in the security lockdown console by default. However, if it is installed through Microsoft Visual Studio .NET, Windows Update, or the .NET Framework redistributable package (Dotnetfx.exe), ASP.NET is disabled by default.

To manage items in the security lockdown console

Open the Internet Information Services management console.
Expand the local computer by clicking the plus sign.
Click the Web Service Extensions folder. The security lockdown console appears in the frame on the right.
With the Extended tab selected, click the Web Service Extension item you want to configure.
Click the Allow or Prohibit button to enable or disable the item.
Click the Add a new Web service extension link to add a new item to the console.

Uninstalling a Version of ASP.NET

If you have multiple versions of ASP.NET installed on a computer, you can uninstall a version on an individual basis. Uninstalling ASP.NET is usually accomplished by uninstalling the .NET Framework through the Add or Remove Programs item in 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).

Note If you just want to uninstall a version of ASP.NET without uninstalling the associated .NET Framework, you can use Aspnet_regiis.exe directly. Each installation of the .NET Framework contains an associated version of the tool. To uninstall only ASP.NET, use the -u option of the tool version associated with the ASP.NET version you want to uninstall. For more information, see the ASP.NET IIS Registration Tool (Aspnet_regiis.exe).

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

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

CAUTION Removing the script maps will cause IIS to serve ASP.NET pages as literal text. This could potentially expose source code to the client.
The ASP.NET state service is shared across all compatible versions of ASP.NET and is always mapped to the latest installed version of ASP.NET. If the ASP.NET version you are uninstalling is currently the latest version, the next-highest compatible version on the computer is then registered to replace it. If no compatible version exists, the ASP.NET State Service is uninstalled.
Performance objects and their associated performance counters specific to the version being uninstalled are removed. The generic performance objects and counters that apply to all installed versions of ASP.NET, ASP.NET and ASP.NET Applications, are directed to the latest installed version remaining on the computer.
The ASPNET user account is shared across all compatible versions of ASP.NET. 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 allows 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. It is up to the third-party application developer to use the options described below when 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 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 this 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 other applications on the computer, the /noaspnetupgrade option is provided as part of Dotnetfx.exe. 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 shows the entire command line.

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 installing version of the .NET Framework, make 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 called SampleApp1.

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

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