When multiple versions of ASP.NET are installed on a computer, ASP.NET is said to be running side-by-side. In this setup, Internet Information Services (IIS) needs to know which version of the ASP.NET ISAPI (aspnet_isapi.dll) should process a page in an ASP.NET application. The ASP.NET ISAPI version that is associated with an ASP.NET application determines which version of the CLR is used for the application. An ASP.NET application is associated with an ASP.NET ISAPI version using a script map in IIS. To simplify the configuration process for an ASP.NET application, each version of ASP.NET comes with a linked version of Aspnet_regiis.exe.
.gif) Note |
|---|
| A unique version of Aspnet_regiis.exe is included with each version of the .NET Framework. Since each version of the tool applies only to its associated version of the .NET Framework, be sure to use the appropriate version of the tool to configure an ASP.NET application. |
The ASP.NET IIS Registration tool is commonly used with the -s or -sn option to remap an ASP.NET application to the version of the .NET Framework with which it is associated. Use the -s option to update an application at the specified root path and in all of its subdirectories. If you do not want applications in subdirectories to be updated, use the -sn option. To update the script maps of all existing ASP.NET applications on the computer at one time, use the -r option.
| Note |
|---|
| The path parameter refers to the root path of the application, not the physical path. For example, W3SVC/1/ROOT/SampleApp1. |
Conversely, you can use the ASP.NET IIS Registration tool to remove the script maps to any version of ASP.NET from an application by using the -k or -kn option and specifying the root path of the application. If the root path specified inherits its script map from a parent root path, the -k and -kn options have no effect.
The -norestart option prevents a restart of the World Wide Web Publishing Service after ASP.NET script maps are installed or updated. You should use this option if you do not want all application pools to be recycled. If you are running multiple websites in IIS, in various application pools, and you do not want all of them to be restarted, you should use this option.
Note that any changes made using the ASP.NET tab on the Internet Information Service console application also cause all application pools to be recycled. If you want to change the ASP.NET version an application uses without causing all application pools to be recycled, run the following two commands to change the version.
aspnet_regiis -s w3svc/<instance>/root -norestart
iisapp /a <app pool> /r
The ASP.NET IIS Registration tool can also be used to install and uninstall the linked version of ASP.NET. Use the -i option to install ASP.NET and to update the script maps of all existing ASP.NET applications. Use the -ir option to install ASP.NET without updating the script maps. To uninstall the ASP.NET version that is associated with the tool, use the -u option. If you want to uninstall all versions of ASP.NET from the computer, use the -ua option.
You can also use the ASP.NET IIS Registration tool to view information about ASP.NET. To list the status and installation path of all of the versions of ASP.NET that are installed on your computer, use the -lv option. If you want to see the paths to all of the IIS metabase keys where ASP.NET is mapped, use the -lk option.
Client-side script, such as client-side validation, can be installed and removed by using Aspnet_regiis.exe. Use the -c option to install the client-side script for the version of ASP.NET that is associated with the tool to the Aspnet_client subdirectory of each IIS site directory. To remove the client-side script for just the ASP.NET version associated with the tool, use the -e option. To remove the client-side script for all installed versions of ASP.NET, use the -ea option.
When you are using impersonation, if the impersonation account does not have Read access to the IIS metabase, a COMException exception with the message "Access is denied" is thrown when you try to access DirectoryEntry. This can occur when the Code subdirectory of the application exists in the application root directory. This error can also occur when an application is mapped to a UNC share and the UNC account does not have Read access to the metabase. In both cases, running the ASP.NET IIS Registration tool with the -ga user option for the impersonation or UNC account fixes the issue.
For more information about side-by-side execution in ASP.NET, see Side-by-Side Support in ASP.NET. For more information about script maps and application root paths, see the IIS documentation on the Microsoft Web site.