Share via

ASP.NET IIS Registration Tool (Aspnet_regiis.exe)

  • Article

The ASP.NET IIS Registration Tool (Aspnet_regiis.exe) is used for registering ASP.NET applications with Internet Information Services (IIS).). This topic describes the options, syntax, and other information for using the tool.

Note

This topic applies to running Aspnet_regiis.exe on the .NET Framework 3.5 SP1. If you are running a different version of the .NET Framework, use one of the following links to go to the Aspnet_regiis documentation for your version: 1.1, 2.0, 3.0, 4.0.

When multiple versions of the .NET Framework are executing side-by-side on a single computer, the ASP.NET ISAPI version mapped to an ASP.NET application determines which version of the common language runtime (CLR) is used for the application. The ASP.NET IIS Registration Tool (Aspnet_regiis.exe) allows an administrator or installation program to easily update the script maps for an ASP.NET application to point to the ASP.NET ISAPI version that is associated with the tool. The tool can also be used to display the status of all installed versions of ASP. NET, register the ASP.NET version that is coupled with the tool, create client-script directories, and perform other configuration operations.

Warning

For information about how to find the correct version of Aspnet_regiis.exe, see Finding the Correct Version of Aspnet_regiis.exe later in this document.

aspnet_regiis [options]

Options

Option

Description

-c

Installs the client-side scripts for ASP.NET, such as client-side validation scripts, to the aspnet_client subdirectory of each Internet Information Services (IIS) site directory.

Only the client-side scripts for the ASP.NET version that is associated with Aspnet_regiis.exe are installed.

-disable

Disables ASP.NET in the IIS Security Console.

This option can be combined only with the -i, -ir, or -r options. It is not available with IIS versions earlier than IIS 6.0.

-e

Removes the client-side scripts for ASP.NET from the aspnet_client subdirectory of each IIS site directory.

Only the client-side scripts for the ASP.NET version associated with Aspnet_regiis.exe are removed.

-ea

Removes the client-side scripts for all versions of ASP.NET from the aspnet_client subdirectory of each IIS site directory.

-enable

Enables ASP.NET in the IIS Security Console.

This option can be combined only with the -i, -ir, or -r options. It is not available with IIS versions earlier than IIS 6.0 or with ASP.NET versions earlier than ASP.NET version 2.0.

-ga user

Grants the specified user or group access to the IIS metabase and other directories that are used by ASP.NET.

This option is not available with ASP.NET versions earlier than ASP.NET 2.0.

-i

Installs the version of ASP.NET that is associated with Aspnet_regiis.exe and updates the script maps at the IIS metabase root and below.

Only the script maps for applications that use an earlier version of ASP.NET are updated. Applications that use a later version are not affected.

-ir

Installs the version of ASP.NET that is associated with Aspnet_regiis.exe and only registers ASP.NET in IIS.

This option does not update the script maps. To install ASP.NET and update the script maps, use the -i option.

-k path

Removes the script maps to all versions of ASP.NET from all ASP.NET applications at the specified application root path and its subdirectories.

-kn path

Removes the script maps to all versions of ASP.NET from the ASP.NET application only at the specified application root path.

This option does not affect applications in subdirectories of the specified path.

-lk

Lists the path and version of all IIS metabase keys where ASP.NET is mapped.

The keys that inherit ASP.NET script maps from a parent key are not displayed.

-lv

Lists the status and installation path of all versions of ASP.NET that are installed on the computer.

-norestart

Inhibits the restart of the World Wide Web Publishing Service after installing or updating ASP.NET script maps. If you do not use this option, all application pools are recycled.

Use this option with the -i or -r options when the IIS worker process will be restarted manually.

-r

Updates all of the script maps in the IIS metabase and below to point to the ASP.NET ISAPI version that is associated with Aspnet_regiis.exe.

All existing script maps are updated to point to the ASP.NET ISAPI version that is associated with the ASP.NET IIS Registration tool, regardless of the current version.

-s path

Installs the script map that points to the ASP.NET ISAPI version associated with Aspnet_regiis.exe to all ASP.NET applications at the specified application root path and its subdirectories. All existing script maps in the specified path and below that use an earlier version of the ASP.NET ISAPI are updated.

-sn path

Installs the script map that points to the ASP.NET ISAPI version associated with the tool to the ASP.NET application at the specified application root path. All existing script maps in the specified path that use an earlier version of the ASP.NET ISAPI are updated.

This option does not affect applications in subdirectories of path.

-u

Uninstalls the version of ASP.NET that is associated with the ASP.NET IIS Registration tool from the computer. Existing script maps to this version of the ASP.NET ISAPI are automatically remapped to the most recent remaining ASP.NET ISAPI version installed.

-ua

Uninstalls all versions of ASP.NET from the computer.

-?

Displays the command syntax and options for the ASP.NET IIS Registration tool.

Configuration Options

Option

Description

-config+

Enables remote access to ASP.NET configuration on the computer.

-config-

Disables remote access to ASP.NET configuration on the computer.

-pa container account

Grants permission for the specified user or group account to access the specified key container. This argument takes the following optional modifiers:

  • -pku   Substitutes a user-specified container for the default machine container.

  • -csp provider   Specifies the container provider to use.

  • -full   Specifies that full access should be added, rather than the default read-only access.

-pc container

Creates an RSA public/private key pair in the specified container. This argument takes the following optional modifiers:

  • -size keySize   Specifies the key size. The default is 1024 bytes.

  • -pku   Substitutes a user-specified container for the default key container on the computer.

  • -exp   Specifies that private keys must be able to be exported.

  • -csp provider   Specifies the container provider to use.

-pd section

Decrypts the configuration section. This argument takes the following optional parameters:

  • -app virtualPath   Specifies that decryption should occur at the level of the included path.

  • -location subPath   Specifies the subdirectory to decrypt.

  • -pkm   Specifies that the Machine.config file should be decrypted instead of the Web.config file.

-pdf section webApplicationDirectory

Decrypts the specified configuration section of the Web.config file in the specified physical (not virtual) directory.

-pe section

Encrypts the specified configuration section. This argument takes the following optional modifiers:

  • -prov provider   Specifies the encryption provider to use.

  • -app virtualPath    Specifies that encryption should occur at the level of the included path.

  • -location subPath   Specifies the subdirectory to encrypt.

  • -pkm   Specifies that the Machine.config file should be encrypted instead of the Web.config file.

-pef section webApplicationDirectory

Encrypts the specified configuration section of the Web.config file in the specified physical (not virtual) directory.

-pi container file

Imports an RSA public/private key pair to the specified container from the specified XML file. This argument takes the following optional modifiers:

  • -pku   Substitutes a user-specified container for the default machine container.

  • -exp   Specifies that private keys can be exported.

  • -csp provider   Specifies the container provider to use.

-pr container account

Removes permission for the specified user or group account to access the specified key container. This argument takes the following optional modifiers:

  • -pku   Substitutes a user-specified container for the default machine container.

  • -csp provider   Specifies the container provider to use.

-px container file

Exports an RSA public/private key pair from the specified container to the specified XML file. This argument takes the following optional modifiers:

  • -pku   Substitutes a user-specified container for the default machine container.

  • -csp provider   Specifies the container provider to use.

-pz container

Deletes the specified key container. This argument takes the following optional modifier:

  • -pku   Substitutes a user-specified container for the default machine container.

Remarks

When multiple versions of ASP.NET are installed on a computer, the versions of ASP.NET are said to be running side-by-side. In this scenario, you must configure IIS to indicate which version of the ASP.NET ISAPI (aspnet_isapi.dll) should process a page in an ASP.NET application. In IIS 7.0, in both Classic and Integrated mode, the CLR version set for the application pool determines which version of ASP.NET and which associated version of the CLR are used to run an application. In IIS 6.0, a scriptmap is used to associate an application with a specific ASP.NET ISAPI version, and the ISAPI version in turn determines which version of the CLR is used to run the application.

There are 32-bit and 64-bit versions of Aspnet_regiis.exe. For Windows Vista and , you can run the 32-bit version of the tool on a 64-bit installation of IIS. This lets you run mixed 32-bit and 64-bit worker processes on the same 64-bit system. The following table lists special cases and limitations that apply when you run the 32-bit version of the tool on a 64-bit version of IIS.

IIS Version

Special cases for 32-bit versions of Aspnet_regiis.exe

6.0

You can run the 32-bit version of Aspnet_regiis.exe under a 64-bit IIS 6.0 installation on Windows Server 2003 with the following restrictions:

  • The 32-bit version runs only if IIS has been set to run in 32-bit mode.

  • The 64-bit version runs only if IIS has been set to run in 64-bit mode.

7.0

On Windows Vista, , or Windows 7, when you run the 32-bit version of Aspnet_regiis.exe under IIS 7, the tool does not automatically set the enable32BitAppOnWin64 attribute of the applicationPools element. On a default 64-bit operating system installation, with Windows on Windows 64 enabled, you can use 32-bit Aspnet_regiis.exe to configure IIS 7, but you will not be able to run any 32-bit applications, unless you explicitly change the enable32BitAppOnWin64 attribute to enable running the application in Windows on Windows 64. For more information about IIS 7.0 configuration options, see the documentation for the applicationPools element in the Applicationhost.config file.

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 that it is associated with. 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.

Note

The path parameter refers to the root path of the application, not the physical path. For example, W3SVC/1/ROOT/SampleApp1.

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.

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.

You can use Aspnet_regiis.exe to install and remove system client-side script, such as script for client-side validation. Use the -c option to install client script for the version of ASP.NET that is associated with the tool. (Script is installed in the Aspnet_client subdirectory of each IIS site directory.) To remove the client-side script for just the ASP.NET version that is 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 and 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 scriptmaps and application root paths, see the IIS documentation on the Microsoft Web site.

Examples

The following command installs the ASP.NET version that is associated with the version of the ASP.NET IIS Registration tool that you are using, and updates existing ASP.NET applications. On IIS 6.0, the command updates the scriptmaps of existing ASP.NET applications that are currently mapped to an earlier version of ASP.NET. On IIS 7.0, the command updates both classic mode and integrated mode handlers in the IIS metabase. It also switches the DefaultAppPool and the Classic  .NET AppPool applications pools to use the .NET Framework 4 CLR.

aspnet_regiis -i

The following command installs the ASP.NET version that is associated with the tool without updating existing applications. On IIS 7.0, the command does not update the version of the .NET Framework associated with the DefaultAppPool and Classic .NET AppPool application pools.

aspnet_regiis -ir

The following command displays the status and installation path of all versions of ASP.NET that are installed on the computer.

aspnet_regiis -lv

The following command updates a Web application and all of its sub-applications to use the ASP.NET version that is associated with the tool. On IIS 6.0, the scriptmaps are updated. On IIS 7.0, the application is mapped to a new application pool.

aspnet_regiis -s W3SVC/1/ROOT/SampleApp1

The following command performs the same functions as the -s command, except that it does not affect applications in subdirectories.

aspnet_regiis -sn W3SVC/1/ROOT/SampleApp1

The following command grants the specified user or group accounts access to the IIS metabase and the other directories used by ASP.NET.

aspnet_regiis -ga MyUserGroup W3SVC/1/ROOT/SampleApp1

Finding the Correct Version of Aspnet_regiis.exe

Aspnet_regiis.exe is installed in the Microsoft.NET Framework directory. If the computer is running multiple .NET Framework versions side-by-side, multiple versions of the tool might be installed. The following table lists the locations where the tool is installed for different versions of the .NET Framework.

Version of .NET Framework

Location of Aspnet_regiis.exe file

.NET Framework version 1

%windir%\.NET\Framework\v1.0.3705

.NET Framework version 1.1

%windir%\Microsoft.NET\Framework\v1.1.4322

.NET Framework version 2.0, version 3.0, and version 3.5 (32-bit systems)

%windir%\Microsoft.NET\Framework\v2.0.50727

.NET Framework version 2.0, version 3.0, and version 3.5 (64-bit systems)

%windir%\Microsoft.NET\Framework64\v2.0.50727

Directories for the .NET Framework versions 3.0 and 3.5 do not have a copy of the tool. For more information, see the entry How to set an IIS Application or AppPool to use ASP.NET 3.5 rather than 2.0 on Scott Hanselman's blog.

See Also

Reference

.NET Framework Tools

Other Resources

Side-by-Side Execution