Creating portable ASP.NET applications that work on IIS 6.0, IIS 7.0 Classic, and IIS 7.0 Integrated modes

ASP.NET applications in IIS 7.0 Integrated mode requires configuration changes if they define custom modules or handlers. The primary changes involve moving the module and handler configuration from the ASP.NET’s <httpModules> and <httpHandlers> sections to the IIS 7.0 <modules> and <handlers> sections used by the Integrated pipeline.

However, <modules> and <handlers> are not recognized on down-level platforms, such as IIS 6.0. They are also isn’t supported in Classic mode on IIS 7.0.

For applications that need to work in both IIS 7.0 Integrated mode, and IIS 7.0 Classic mode or previous versions of IIS, this raises the question of whether two different versions of the application are needed to allow this.

In fact, it is possible to create portable ASP.NET applications that can function in all three environments without configuration changes.

The design of the configuration specifically allows this to happen, by specifying both sets of configuration concurrently. Depending on the mode the application is in, the right set of configuration is selected to determine the modules and handlers for the application.

Let’s take a look at such a configuration for an application that adds a module and a handler:

<configuration>

  <system.web>

    <!-- Modules for IIS 6.0 and IIS 7.0 Classic mode -->

    <httpModules>

        <add name="MyModule" type="MyApp.MyModule" />

    </httpModules>

    <!-- Handlers for IIS 6.0 and IIS 7.0 Classic mode -->   

    <httpHandlers>

      <add path="*.myh" verb="GET" type="MyApp.MyHandler" />

    </httpHandlers>       

  </system.web>

  <system.webServer>

    <!-- Modules for IIS 7.0 Integrated mode -->

    <modules>

      <add name="MyModule" type="MyApp.MyModule" />     

    </modules>

    <!-- Handlers for IIS 7.0 Integrated mode -->   

    <handlers>

      <add name="MyHandler" path="*.myh" verb="GET" type="MyApp.MyHandler" preCondition="integratedMode" />

    </handlers>

    <!-- Disable detection of IIS 6.0 / Classic mode ASP.NET configuration -->   

    <validation validateIntegratedModeConfiguration="false" />

  </system.webServer>

</configuration>

The things to notice here are:

1)       The module and handler are first configured in the ASP.NET <httpModules> and <httpHandlers> sections, precisely the way you would do it for an ASP.NET application running on IIS 6.0, or running in Classic mode on IIS 7.0.

2)       The module and handler are then configured in the IIS 7.0 <modules> and <handlers> sections. This enables them to be recognized by IIS 7.0 in Integrated mode.

3)       The validateIntegratedModeConfiguration attribute in the <validation> section is used to disable runtime rejection of Integrated mode applications that have legacy ASP.NET settings, which we do have.

In fact, this configuration is exactly what is generated by default when you use the AppCmd Migrate Config command on your ASP.NET application for the first time. The migration logic creates the migrated configuration needed for IIS 7.0 Integrated mode, and keeps your old configuration if you ever want to take the app to Classic mode or to down-level versions of IIS.

Now, the dangerous thing here is that after migration, the server will no longer complain about the presence of the legacy ASP.NET configuration. Even if it gets out of sync with your Integrated mode configuration – for example, if you add a module to <httpModules>, but not to <modules>, that module will run in Classic mode but not in Integrated mode.

Because of this, it is your responsibility to make sure that any changes made to the Classic configuration set are also made to the Integrated configuration set, and visa versa.

To understand this further, let’s see what happens when this application is deployed to the IIS 7.0 Integrated mode, Classic mode, and IIS 6.0:

IIS 7.0 Integrated mode: ASP.NET modules and handlers are loaded from the combined <modules> and <handlers> configuration sections.  ASP.NET’s <httpModules> and <httpHandlers> sections are ignored, and no error is generated because we disabled validation.

IIS 7.0 Classic mode: ASP.NET modules and handlers are loaded from the <httpModules> and <httpHandlers> configuration sections. Managed modules in <modules> are ignored, and the managed handlers in the <handlers> section are preconditioned away.

IIS 6.0: ASP.NET modules and handlers are loaded from the <httpModules> and <httpHandlers> configuration sections. IIS 6.0 has no knowledge of the <handlers> and <modules> sections, and ASP.NET 2.0 does not complain because the entire <system.webServer> section group is registered with an “IgnoreSectionHandler” (ASP.NET 1.1 doesn’t have this, so you need to manually do this).

NOTE that in the IIS 7.0 Classic mode, and on down-level versions of IIS, you will also need to add a script map mapping the MYH extension to ASP.NET 2.0, in order for your handler mapping to take effect. On IIS 7.0, this will actually produce another <handlers> entry in the web.config file as follows:

      <add name="MyHandler-Classic" path="*.myh" verb="GET" modules="IsapiModule" scriptProcessor="%windir%\Microsoft.NET\Framework\v2

.0.50727\aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv2.0,bitness3

2" responseBufferLimit="0" />   

On IIS 6.0 and below, it will add a script map entry to the scriptmaps metabase property for the application.

Because this is a different step for IIS 7.0 vs. IIS 6.0 and earlier servers, I do not include this configuration in the portable web.config, but rather create it as an additional step. If you just want portability between Integrated and Classic mode, you can add the entry above to your portable web.config (NOTE that the automatic migration also does not produce this entry).

Finally I should note that in many cases, ASP.NET modules in Integrated mode perform tasks that are only possible in Integrated mode applications. After all, if Classic mode was the same as Integrated, what would be the point of going through all this pain of having two modes?

In those cases, these modules may need to be registered only in the Integrated configuration set. Or, they may necessitate two versions of the application, one with fewer features for Classic mode and another with the full feature set for Integrated mode.

This should make it easier to produce ASP.NET applications for Integrated mode that require to work on multiple platforms. In a future post, I'll cover development tricks you can use to develop modules that work in both modes.

Thanks,

Mike