IIS 7.0 : Hosting ASP.NET Applications

ASP.NET has been the application framework platform of choice for developing rich Web applications for an IIS environment. IIS 7.0 takes this further by integrating ASP.NET 2.0 with its request processing pipeline. This elevates ASP.NET from being an application framework that sits on top of the Web server to being a full-fidelity .NET API for extending the Web server at its core.

This design brings multiple benefits to the IIS 7.0 platform. First, it enables the modular Web server features to be developed with the power of the .NET Framework and the rich features of ASP.NET. Second, it enables many of the existing ASP.NET application services to be used on the Web server in a framework-neutral way, for both ASP.NET and other application frameworks. Thus, server administrators can, for example, apply a single set of authentication, session state, and other ASP.NET features uniformly across an entire Web site that may is using any application framework.

Direct from the Source: Maintaining Backwards Compatibility With ASP.NET Applications

To enable ASP.NET integration, we had to rebuild the ASP.NET 2.0 engine from scratch. The new architecture necessitated many design changes regarding how ASP.NET works on IIS 7.0 underneath the covers, and how ASP.NET applications are configured. These changes promised to significantly impact the compatibility with existing ASP.NET applications.

However, we also wanted to make sure that existing ASP.NET applications continued to work correctly using the new ASP.NET integration mode. Maintaining backwards compatibility was a key design and implementation goal for the ASP.NET integrated pipeline, and it proved to be a major challenge during the development of the project.

In the end, this goal was largely achieved in IIS 7.0. However, certain deployment and development considerations impact the behavior of ASP.NET applications on IIS 7.0. When faced with these changes, keep in mind that they were necessary in order to support the new levels of functionality for ASP.NET applications and the Web server in general. For the majority of these changes, simple workarounds exist that can allow your application to leverage the benefits of Integrated mode. In a few cases, you may opt to configure your application to run in Classic mode, in order to avoid these breaking changes—however, in doing so, you will lose the ability to leverage the many improvements granted by the Integrated mode.

Mike Volodarsky

IIS Core Program Manager

In the remainder of this section, we will discuss the key conceptual changes in how ASP.NET works on IIS 7.0 to facilitate the twofold goal of enabling the new level of Web server extensibility and maintaining compatibility with existing ASP.NET applications.

Understanding the Integrated and Classic ASP.NET Modes

IIS 7.0 offers two modes for hosting ASP.NET applications: Integrated and Classic. The Integrated mode is the new mode, providing tight integration with the IIS Web server and enabling ASP.NET services to be used as application framework–neutral Web server features. This mode is the default mode on IIS 7.0 and maintains backward compatibility with existing ASP.NET applications in the majority of cases. Existing ASP.NET applications may require some configuration changes to work correctly with Integrated mode, and the server automatically detects most of these and provides migration support to prepare the application for Integrated mode in a single step.

The Classic mode provides an option to run ASP.NET applications in the same way as they have been in previous versions of IIS. The Classic mode does not offer any of the additional benefits provided by Integrated mode. It is intended as a fallback option for those ASP.NET applications that are impacted by specific breaking changes in Integrated mode.

Note

Do not confuse the ASP.NET Integration modes (Integrated and Classic) with the IIS worker process isolation mode. They are two completely different concepts. IIS 7.0 supports only the IIS 6.0 Worker Process Isolation Mode and no longer supports the IIS 5.0 Isolation Mode. ASP.NET always runs in-process regardless of the ASP.NET integration mode.

The differences between the two ASP.NET Integration modes are illustrated in Figure 1. In Classic mode, ASP.NET integrates with IIS as an ISAPI extension that processes those requests mapped only to itself. As such, it provides a duplicate request processing pipeline for ASP.NET requests. In Integrated mode, the ASP.NET features provided by ASP.NET modules and handlers plug into the main IIS request processing pipeline, eliminating duplication and executing for all requests to the server.

Figure 1. ASP.NET integration in IIS 7.0.

Integrated mode offers several key advantages—for both the existing ASP.NET applications and for new ASP.NET applications—that make Integrated mode the preferred mode of operation on IIS 7.0 and beyond:

• ASP.NET application services can be used uniformly across the entire Web site, instead of being limited to ASP.NET content only. This includes such ASP.NET features as Forms authentication, Roles, Output Caching, and any custom ASP.NET services provided by modules that are part of the application. This feature also reduces management complexity because a single set of functionality can be managed for the entire Web site.

• It makes it possible to develop modules that provide core Web server features in managed code by using ASP.NET instead of using low-level C++ interfaces. This dramatically reduces the amount of time needed to develop and deploy new server functionality.

• Key ASP.NET and IIS configurations are unified, making it easier to manage the application.

• For shared server environments, such as shared hosting servers or departmental servers, the administrator can allow applications to provide key Web server functionality by using managed modules without requiring administrative privileges or by having to install Web server features globally on the server.

Note

Integrated mode is not required to store IIS and ASP.NET configuration settings in the same web.config files. It is also not required to leverage new IIS 7.0 features such as URL Authorization and Output Caching. These capabilities are part of the Web server platform and do not depend on the ASP.NET integration mode.

IIS 7.0 supports running ASP.NET applications that use both Integrated and Classic mode on the same server, enabling the ASP.NET integration mode to be selected for each application pool. This makes it easy to run most ASP.NET applications by using the default Integrated mode and to place the applications that experience difficulties into Classic mode.

Even if your application does not immediately take advantage of Integrated mode, it is highly recommended to run it using Integrated mode—even in cases in which it may require specific code changes. This is because using Integrated mode ensures that the application is prepared for using Integrated mode-specific Web server features that are available today and/or will be available in the future. In addition, future releases of IIS may remove support for Classic mode. Therefore, any steps you can take today toward removing Classic mode dependencies will make it easier to migrate to new versions of IIS in the future. Classic mode is intended more as a temporary mechanism to enable applications to move to IIS 7.0, rather then as a long-term option.

Running Multiple Versions of ASP.NET Side by Side

Historically, IIS has always supported using multiple versions of ASP.NET side by side to host ASP.NET applications that target different versions of the .NET Framework. This has been supported through mapping the Aspnet_isapi.dll ISAPI extension from the correct .NET Framework version directory to ASP.NET content types for each application. For example, the following script map would result in ASP.NET 2.0 being used to process requests to .aspx pages.

.aspx,E:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\
aspnet_isapi.dll,1,GET,HEAD,POST,DEBUG

Administrators often used the Aspnet_regiis.exe tool located in the %systemRoot%\Microsoft.NET\Framework\version directory to install ASP.NET on previous versions of IIS by creating handler mappings for the corresponding version, either on the entire server or for a specific application. By using this tool, administrators could create script maps for different versions of ASP.NET for each ASP.NET application, and thereby run different ASP.NET versions side by side.

However, this approach was prone to common misconfigurations that resulted in some of the most common problems reported to the ASP.NET Product Support Team. The most infamous one occurred when two applications using different versions of ASP.NET were placed in a single application pool. Because only one version of the common language run time (CLR) is supported per process, the application that happened to be requested second would fail to load. This would result in unexpected and nondeterministic failures.

IIS 7.0 changes the ASP.NET versioning mechanism to be more deterministic by officially recognizing that only one version of ASP.NET can be used in each IIS worker process. Therefore, in IIS 7.0, the version of ASP.NET that is used is explicitly configured for each IIS application pool by using the managedRuntimeVersion configuration attribute. The ASP.NET handler mappings are not used to select the version. Instead, ASP.NET setup registers them globally on the server and configures them to use the version preconditions so that they are automatically selected in each application pool based on its configured CLR version. Following is an excerpt from the system.webServer/handlers configuration section when both ASP.NET v1.1 and v2.0 are installed.

<add name="ASPNET-ISAPI-1.1-PageHandlerFactory" path="*.aspx"
verb="GET,HEAD,POST,DEBUG" modules="IsapiModule"
scriptProcessor="C:\Windows\Microsoft.Net\Framework\v1.1.4322\aspnet_isapi
dll" preCondition="classicMode,runtimeVersionv1.1,bitness32" />
<add name="PageHandlerFactory-Integrated" path="*.aspx"
verb="GET,HEAD,POST,DEBUG" type="System.Web.UI.PageHandlerFactory"
preCondition="integratedMode" />
<add name="PageHandlerFactory-ISAPI-2.0" path="*.aspx"
verb="GET,HEAD,POST,DEBUG" modules="IsapiModule"
scriptProcessor="%systemroot%\Microsoft.NET\Framework\v2.0.50727\
aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv2.0,bitness32"/>

The runtimeVersion precondition is used to precondition the *.aspx handler mapping for a particular ASP.NET version, enabling it to be selected automatically in application pools that use the corresponding managed run-time version. Because these handler mappings are installed globally, you do not need to ever use Aspnet_regiis.exe to manually select the version of ASP.NET for an application or to manually create ASP.NET handler mappings for the right version.

By setting the managedRuntimeVersion configuration attribute for each IIS application pool to the desired version, you ensure that all applications in this application pool will use the correct ASP.NET version. Therefore, the application pool becomes the unit of versioning for ASP.NET applications.

Note

Do not use the Aspnet_regiis.exe tool to install and manage ASP.NET versions for your applications. Instead, use IIS application pools to select the desired version.

The managedRuntimeVersion configuration attribute can have the following values: v1.1, v2.0, and "" (empty). If set to (empty), no CLR version is loaded in the application pool, and ASP.NET applications in that application pool will not work.

To ensure that your application uses a particular version of ASP.NET, you can either create a new IIS application pool that is set to use the correct ASP.NET version, or you can use one of the existing IIS application pools configured with the desired version. 

Installing ASP.NET

Before you can host ASP.NET applications on IIS 7.0, you need to install ASP.NET. IIS 7.0 supports the following versions of the ASP.NET framework:

• ASP.NET 2.0. This is the default version of ASP.NET available in Windows Vista and Windows Server 2008 as part of the .NET Framework 3.0, and it can be installed using Programs And Features in Windows Vista or as a role service by using Server Manager in Windows Server 2008. ASP.NET 2.0 supports both Integrated and Classic modes.

• ASP.NET 1.1. Though not included in the operating system, you can download and install the .NET Framework 1.1 redistributable together with the .NET Framework 1.1 Service Pack 1 (SP1) upgrade to install ASP.NET 1.1. ASP.NET 1.1 supports only Classic mode of operation.

ASP.NET 1.0 and .NET Framework 1.0 are no longer supported. If you need to run applications that use ASP.NET 1.0, you will need to upgrade them to run using ASP.NET 1.1.

After installing ASP.NET, you will need to create an IIS 7.0 application to host your ASP.NET application. You may then also need to create a separate application pool so that you can select the Integrated or Classic ASP.NET integration mode, and you may possibly be required to migrate your application configuration so that it will run correctly in Integrated mode.

Installing ASP.NET 2.0

ASP.NET 2.0 can be installed using Programs And Features in Windows Vista or as a role service by using Server Manager in Windows Server 2008. The installation will perform all necessary steps to install and create required IIS configuration to run ASP.NET 2.0 in both Classic and Integrated modes. This removes the need to run the Aspnet_regiis.exe tool to register ASP.NET with IIS. In fact, you should not use this tool to install ASP.NET on IIS 7.0.

Caution

Do not use Aspnet_regiis.exe to install ASP.NET 2.0 on IIS 7.0.

Another option is also available to you. If you do not need the full ASP.NET functionality, such as support for ASPX pages and the built-in ASP.NET handlers and modules, you do not need to install full ASP.NET support. You can install the .NET Extensibility component, which enables custom ASP.NET modules and handlers to be used on the server in Integrated mode applications. This is a good option if you are leveraging ASP.NET Integrated mode to extend other application frameworks with custom ASP.NET modules and do not use the ASP.NET application framework itself.

Note

Installing the .NET Extensibility component instead of the ASP.NET component enables the use of ASP.NET handlers and modules in Integrated mode applications. It does not install the ASP.NET application framework (ASPX pages and more), and it does not enable Classic mode ASP.NET applications.

Installing ASP.NET 1.1

Unlike ASP.NET 2.0, ASP.NET 1.1 is not available in the operating system by default. To install it, you need to download and install the .NET Framework v1.1 redistributable and apply the .NET Framework v1.1 SP1 update. This update is required to run ASP.NET 1.1 applications.

To install ASP.NET v1.1, you need to perform the following steps:

1. Install the IIS 6 Metabase Compatibility component. This component installs the metabase compatibility APIs that ASP.NET 1.1 uses to both install itself and read IIS configuration at run time. You can install IIS 6 Metabase Compatibility by using Programs And Features in Windows Vista or as a role service by using Server Manager in Windows Server 2008.

2. Download and install .NET Framework v1.1 redistributable.

3. Download and install .NET Framework v1.1 SP1 update.

4. Enable the ASP.NET v1.1.4322 entry in the ISAPI and CGI restrictions. You can do this from IIS Manager, with Appcmd.exe, or as follows.

   %systemroot%\Microsoft.NET\Framework\v1.1.4322\aspnet_regiis –enable

5. Add the IgnoreSection handler for the system.webServer section to the Framework v1.1 machine.config file. This is necessary because ASP.NET 1.1 is not aware of the IIS 7.0 configuration that may be placed in web.config files. Add the following inside the <configSections> element.

   </configSections>
     ...
     <section name="system.webServer"
   type="System.Configuration.IgnoreSection" />
   </configSections>

The installation of the .NET Framework will automatically invoke Aspnet_regiis.exe –i to install ASP.NET 1.1. Windows Server 2008 and Windows Vista SP1 use an application compatibility shim to intercept the invocation of this tool and correctly generate the required configuration for IIS 7.0 to register ASP.NET v1.1. This configuration includes the following:

• ASP.NET v1.1 handler mappings, created at the server level, that are preconditioned to take effect only in application pools configured for .NET Framework v1.1.

• The "ASP.NET 1.1" application pool, which can be used by ASP.NET v1.1 applications by default. This application pool is configured to run in 32-bit mode always (even on 64-bit operating systems) and use the Classic ASP.NET integration mode.

Caution

Do not use the Aspnet_regiis.exe tool to install ASP.NET v1.1 on IIS 7.0 or to set any specific application to use ASP.NET v1.1. Instead, place any application that needs to use this version of ASP.NET in the provided ASP.NET 1.1 application pool or create a new application pool that uses .NET Framework v1.1. 

If creating new application pools to host ASP.NET v1.1 applications, each application pool must:

• Set the managedRuntimeVersion configuration attribute to v1.1.

• Set the managedPipelineMode configuration attribute to Classic. ASP.NET v1.1 does not support running in Integrated mode.

• Set the enable32BitAppOnWin64 configuration attribute to true on 64-bit operating systems. ASP.NET v1.1 does not support running in native 64-bit mode.

Deploying ASP.NET Applications

After you have installed the correct version of ASP.NET, you can deploy ASP.NET applications to the server. To do this, perform the following steps:

1. Create an IIS application.

2. Place the application in the correct application pool by using the correct ASP.NET version and integration mode.

3. Deploy ASP.NET application contents.

4. Migrate ASP.NET application configuration to allow it to run in Integrated mode (this is optional, and only for ASP.NET 2.0 applications that are running in Integrated mode and that require migration).

Creating an IIS Application

Though you can deploy ASP.NET pages to any application, virtual directory, or a subdirectory thereof, you will typically want to deploy an ASP.NET application and all of its contents to a separate IIS application. This is because many associated parts of an ASP.NET application—including the Global.asax, the /BIN directory, the /App_Code directory, and other /App_directories—require being placed in the root of an IIS application. Likewise, many ASP.NET configuration settings must be located in the application root’s web.config to take effect. In addition, you will often want to isolate the contents of one ASP.NET application from another’s contents because they require a different application-level configuration or use incompatible application-level state.

This requirement isn’t new in IIS 7.0, though IIS 7.0 does provide a much firmer definition of an application than previous versions of IIS do. Therefore, you need to make sure that the ASP.NET application is deployed into the root virtual directory of an IIS application, and sometimes you may be required to create a new application for this purpose. You can do this from IIS Manager, or by using Appcmd as follows.

%systemroot%\system32\inetsrv\appcmd.exe add app "/site.name:SiteName"
"/path:VirtualPathOfApplication"
"/physicalPath:PhysicalRootDirectoryOfApplication"

You may also need to create a separate IIS application so that it can be placed in the appropriate application pool that uses the correct .NET Framework version and ASP.NET integration mode. We will discuss this next.

Selecting the Right Application Pool for the Required ASP.NET Version and Integration Mode

After you create the application, you will need to configure it to use an application pool that uses the correct ASP.NET version and integration mode. Unlike IIS 6.0, the version of ASP.NET that the application uses is now set at the application pool level, via the managedRuntimeVersion configuration attribute. This ensures a deterministic mapping between IIS worker processes and the CLR version that they load. Likewise, the ASP.NET integration mode is also set per application pool, using the managedPipelineMode configuration attribute. Therefore, you will need to use the desired settings to ensure that your application is placed in an application pool. Table 1 lists these settings.

Table 1. Default Application Pools for Different Versions of ASP.NET

Desired Environment	Application Pool Settings
ASP.NET 1.1	managedRuntimeVersion: v1.1 managedPipelineMode: Classic Can use the "ASP.NET 1.1" application pool
ASP.NET 2.0 Integrated mode	managedRuntimeVersion: v2.0 managedPipelineMode: Integrated Can use the default application pool named "DefaultAppPool"
ASP.NET 2.0 Classic mode	managedRuntimeVersion: v2.0 managedPipelineMode: Classic Can use the "Classic .NET AppPool" application pool

Because all new applications are by default set to use the "DefaultAppPool" application pool, which by default is configured for ASP.NET 2.0 Integrated mode, all new applications by default use this mode. If you want to run an ASP.NET 2.0 application in Classic mode, you can use the pre-installed "Classic .NET AppPool" application pool.

%systemroot%\system32\inetsrv\appcmd.exe set app "ApplicationPath"
"/applicationPool:Classic .NET AppPool"

If you want to run an ASP.NET 1.1 application, you can place it in the precreated "ASP.NET 1.1" application pool (created by .NET Framework 1.1 setup when ASP.NET 1.1 is installed).

%systemroot%\system32\inetsrv\appcmd.exe set app "ApplicationPath"
"/applicationPool:ASP.NET 1.1"

You can also create new application pools and set their managedPipelineMode and managedRuntimeVersion configuration attributes appropriately to host your new application. 

Migrating ASP.NET 2.0 Applications to Use Integrated Mode

After you have created an IIS application and have placed it in the appropriate application pool, you can deploy your application contents to the IIS application’s root directory. Your application should then be ready to run.

As mentioned earlier, most existing ASP.NET 2.0 applications will work transparently in Integrated mode. However, in some cases, configuration changes are necessary to enable the application to function correctly. These changes are required because IIS 7.0 takes over certain ASP.NET configurations in Integrated mode to enable the integration to occur. If your ASP.NET application defines any of the configuration sections listed in Table 2, you will get an error message when you request content in that application, as shown in Figure 2.

Figure 2. Server error indicating that migration is required to operate application in Integrated mode.

The error indicates that the application contains an unsupported ASP.NET configuration and indicates that it specifically contains the system.web/httpModules configuration section in the Most Likely Causes area. The error also suggests steps to address this issue (not shown in Figure 2), which include migrating the application’s configuration by using the Appcmd.exe command line tool (more on this in a moment).

Table 3 lists cases in which this error will be generated and the suggested migration action to resolve the issue.

Table 3. ASP.NET Configuration That Requires Migration in Integrated Mode

Situation	Suggested Action
Application defines custom modules in the system.web/httpModules configuration section	Move the module entries from the system.web/httpModules section to the IIS system.webServer/modules section. The migration tool can do this automatically.
Application defines custom handler mappings in the system.web/httpHandlers configuration section	Move the handler entries from the system.web/httpHandlers section to the IIS system.webServer/handlers section. The migration tool can do this automatically.
Application enables request impersonation in system.web/identity configuration section	Move the application to Classic mode or configure the application to ignore this error.

The first two cases revolve around the integration of ASP.NET handlers and modules with the IIS handler and module configuration. In Integrated mode, ASP.NET modules and handlers execute directly in the IIS Web server pipeline and are configured in the IIS system.webServer/modules and system.webServer/handlers configuration sections instead of the ASP.NET system.web/httpModules and system.web/httpHandlers sections. You can perform the necessary configuration migration automatically by using the Appcmd Migrate Config command.

%systemroot%\system32\inetsrv\AppCmd Migrate Config "ApplicationPath"

ApplicationPath is the configuration path of the application being migrated. This command will automatically migrate the configuration, enabling the application to work correctly in Integrated mode.

The last case deserves a bit more explanation. ASP.NET applications that are configured to impersonate the authenticated user for the request traditionally have been able to impersonate that user for the entire request. In Integrated mode, because ASP.NET modules can execute earlier in the request processing pipeline, impersonation is not available until after the AuthenticateRequest stage. Typically, this is not a breaking change, because it is uncommon for ASP.NET modules to rely on impersonation early in the request processing pipeline. To be safe, however, IIS recommends moving applications that use impersonation to Classic mode. If you are positive that you do not have custom ASP.NET modules that rely on being impersonated in the BeginRequest and AuthenticateRequest stages, you can ignore this warning by turning off configuration validation for your application. Doing so is described next.

After migration has taken place, Appcmd will generate a special configuration that disables further validation for the application (you can also create this configuration manually after performing the migration yourself). This enables the ASP.NET application to retain its former ASP.NET configuration used in Classic mode/previous versions of IIS. In addition, it also provides the migrated configuration so that it can be safely moved between Classic and Integrated modes, and to down-level platforms. You can also use this configuration to disable validation so that <identity impersonate="true" /> does not cause the validation error. This configuration looks like this.

<system.webServer>
  <validation validateIntegratedModeConfiguration="false" />
</system.webServer>

After this configuration is added to the application’s web.config file, IIS 7.0 will no longer attempt to validate ASP.NET configuration. Because of this, after you initially migrate the application, you are responsible for making sure that new configuration changes are made to both the Classic and Integrated configuration sections.

Taking Advantage of ASP.NET Integrated Mode

Deploying your application in Integrated mode enables you to leverage benefits provided by the ASP.NET integration. The main benefit is the ability to apply services provided by ASP.NET modules for all requests in your application, whether they are ASP.NET content, static files, or any other application content including ASP and PHP. This is especially meaningful for developers, who can quickly build new modules by using familiar ASP.NET APIs to consistently provide services to the entire Web site without having to develop using the more difficult native C++-based Web server APIs such as ISAPI. These modules can take the form of serious Web server features that provide services such as authentication, or smaller application-specific modules that perform services such as redirects or server-side URL rewriting.

In addition, ASP.NET Integrated mode also enables existing applications to immediately begin leveraging their existing modules or the existing modules that are part of ASP.NET. One popular example of this is using the built-in ASP.NET Forms Authentication module to provide forms-based authentication for the entire Web site, leveraging the powerful ASP.NET Login controls and Membership functionality for user management.

More Info

Table 4 lists the ASP.NET modules that can be used effectively in Integrated mode applications to provide services for the entire Web site.

Table 4. Modules Available for All Web Site Content in Integrated Mode

Module	Use To
FormsAuthentication	Protect the entire Web site with ASP.NET’s Forms-based authentication, leveraging ASP.NET Login controls and Membership service.
UrlAuthorization	Protect the entire Web site with declarative access control rules for users and roles specified in configuration (you can also use the IIS Url Authorization module).
RoleManager	Provide rich role support for any authentication method using the ASP.NET Roles service, typically used in conjunction with UrlAuthorization for declarative access control or a custom authorization scheme.
OutputCache	To achieve significant performance gains, store application responses in the ASP.NET output cache for reuse. This typically requires additional code to configure the output cache.

By default, all built-in ASP.NET modules are configured to run only for ASP.NET content types. This is done to provide a backward compatible behavior for Integrated mode applications by default. To enable an ASP.NET module to run for all requests to your application, you need to remove the managedHandler precondition from the corresponding configuration element in the system.webServer/modules configuration section in the application. You can do this through IIS Manager by selecting your application in the tree view, double-clicking the Modules icon, double-clicking the desired module to edit it, and clearing the Invoke Only For Requests To ASP.NET Applications Or Managed Handlers check box, as shown in Figure 3.

Figure 3. Using IIS Manager to enable the Forms Authentication module to run for all requests.

New modules added at the application level will run by default for all requests unless you explicitly chose not to allow them to. 

More Info

You can learn more about leveraging ASP.NET modules to add value to existing applications in the MSDN article titled "Enhance Your Apps with ASP.NET Integrated Pipeline" available at http://msdn.microsoft.com/msdnmag/issues/08/01/PHPandIIS7/default.aspx.

Additional Deployment Considerations

This section lists some of the additional deployment considerations for ASP.NET applications running on IIS 7.0.

Breaking Changes in ASP.NET 2.0 Integrated Mode

Most ASP.NET 2.0 applications will work correctly when hosted in Integrated mode after the required configuration migration. However, some applications may experience specific breaking changes. These may require code changes in the application, or the application to be moved to Classic mode. 

Hosting ASP.NET Applications on Remote UNC Shares

By default, ASP.NET applications execute with the application pool identity. In some cases, ASP.NET applications can also be configured to impersonate the authenticated user. If they do, applications that enable anonymous access will impersonate the anonymous user, which is the built-in IUSR account by default, and will impersonate the authenticated user otherwise.

When the application is hosted on a universal naming convention (UNC) share, the default anonymous user (IUSR) and the default application pool identity (Network Service) do not have the rights to access the remote network share. Because of this, you will need to use one of the following options to configure the ASP.NET application to work correctly on a UNC share:

• Configure fixed credentials for the application’s root virtual directory located on a UNC share, which must have access to the remote share. The Web server and the ASP.NET application will then always impersonate these credentials, instead of the process identity or the authenticated user. This option is recommended in most cases.

• Configure a custom application pool identity that has access to the share. If using anonymous authentication, configure it to use the application pool identity to access the application resources. You can use this option in cases in which you configure your application pool to use a domain account and use that domain account to isolate application and control access to network resources.

If you use a custom application pool identity, you should also use the Aspnet_regiis.exe tool to make sure the custom application pool identity has the correct permissions to run ASP.NET.

Aspnet_regiis.exe -ga Domain\UserName

Domain is the domain for the custom account, and UserName is the user name of the custom account. This will ensure that the custom account has all the correct permissions on the Web server for running ASP.NET applications.

In addition, you should be aware of the following limitations when hosting ASP.NET applications on a UNC:

• ASP.NET applications do not support splitting virtual directories between remote UNC and local directories. Either the root virtual directory must be on a UNC share, or no child virtual directories can be on a UNC share.

• If the ASP.NET application specifies a custom application identity in the system.webServer/identity configuration section, that identity will be impersonated when on a UNC share, and therefore, it must also have access to the UNC share.

To allow .NET assemblies included with the ASP.NET application (in the /BIN or /App_Code directories) that resides on a UNC share to work properly, you also need to modify the UNC Code Access Security policy for that network share path. To do this, you can use the Caspol.exe command tool as follows (where \\myshare\mydir\ is the path to the virtual directory).

%systemroot%\Microsoft.NET\Framework\version\Caspol.exe –m –ag 1. –url
"file://\\myshare\mydir\*" FullTrust

Be aware that other application frameworks the Web site or application are using may access their content in different ways, so you have to select the access model that makes sense for all application components and that minimizes the overhead of managing permissions. This is typically the fixed virtual directory credentials model.