Condividi tramite

IIS 7.0, ASP.NET, pipelines, modules, handlers, and preconditions

  • Articolo

1.0 What is the IIS Pipeline

Conceptually, the IIS pipeline is a state machine with the following states:

BEGIN_REQUEST
AUTHENTICATE_REQUEST
AUTHORIZE_REQUEST
RESOLVE_REQUEST_CACHE
MAP_REQUEST_HANDLER
ACQUIRE_REQUEST_STATE
PRE_EXECUTE_REQUEST_HANDLER
EXECUTE_REQUEST_HANDLER
RELEASE_REQUEST_STATE
UPDATE_REQUEST_CACHE
LOG_REQUEST
END_REQUEST

When a request is received, it moves through the state machine step-by-step until completion.  Beginning with IIS 7.0, users can register their own code to be executed within any or all of the steps.  This code is referred to as a module.  In other words, users register modules to handle events in the pipeline.  (I will refer to the stages of the pipeline as steps, events, notifications, and sometimes combinations of one or more of these.  Don't let that confuse you.  They all mean the same thing.)

2.0 Integrated vs. Classic Pipeline Modes

IIS 7.0 has two pipeline modes: integrated and classic.  The latter is sometimes referred to as ISAPI mode. 

Integrated mode allows both managed and native modules to register for events in the IIS pipeline.  This enables many new scenarios, such as applying ASP.NET forms authentication to non-asp.net requests (static files, classic ASP files, etc). 

Classic mode is identical to IIS 6.0.  In classic mode, the ASP.NET pipeline (BeginRequest, AuthenticateRequest,…, EndRequest) runs entirely within the IIS pipeline’s EXECUTE_REQUEST_HANDLER event.  Think of ASP.NET in classic mode as a pipeline within a pipeline.

3.0 Handlers vs. Modules

Modules are units of code that have registered for one or more pipeline events. They perform authentication, authorization, logging, etc. There is one task that is reserved for a special module, known as a handler.  The handler’s unique job is to retrieve the resource that is requested in the URL.  All resources served by IIS are mapped to a handler in configuration.  If the configuration mapping does not exist, requests for the resource will receive a 404 HTTP status.  In addition to the configuration mapping, which takes place before the pipeline begins, the handler mapping can be changed during request execution in the MAP_REQUEST_HANDLER event.  This allows scenarios such as URL rewriting to work.  Handlers are notified, or executed, in the EXECUTE_REQUEST_HANDLER step.  (Note that only the mapped handler is notified, as you would expect.)

4.0 Handler and Module Configuration

IIS 7.0 introduces two new configuration sections: <handlers> and <modules>. The ASP.NET <httpHandlers> and <httpModules> sections still exist, but are only used when running in the classic pipeline mode.  The new IIS sections add a level of complexity which many users find confusing.

First, if you're running in classic mode, your application should not require any changes.  The standard extensions served by ASP.NET ASPX, ASMX, AXD, etc are mapped to a handler in IIS configuration that invokes aspnet_isapi.dll and executes managed code just like it does on IIS 6.  If, however, you made changes to the IIS script mappings on IIS 6, you will need to make corresponding changes in IIS 7.  This will involve adding a <handler> mapping.

On the other hand, if you're running in integrated mode, you will need to migrate your <httpHandler> and <httpModule> sections to the new <handler> and <module> sections.  For example, you can use the following command to migrate the <httpModules> section for the default web site:

%WINDIR%\system32\inetsrv\appcmd migrate config "Default Web Site/" -section:httpModules

The confusion occurs right about the time you start wondering how to add a managed module to the integrated pipeline that only executes for managed requests.  Or when you need to add a handler mapping that only applies to the integrated pipeline.  To perform these type actions, IIS uses preconditions on the module or handler to restrict the conditions under which it executes.

For handlers, if you set preCondition="integratedMode" in the <handler> mapping, the handler will only run in integrated mode.  On the other hand, if you set preCondition="classicMode" the handler will only run in classic mode.  And if you omit both of these, the handler can run in both modes, although this is not possible for a managed handler.

For modules, if you set preCondition=”managedHandler” in the <module> entry, the module will only run for managed requests (a managed request is a request that has a managed handler).  If you omit this, the module will run for all requests.  Managed modules in the <modules> section are only called if you're running in the integrated pipeline.  If you're running in classic mode, then <httpModules> is used.

Note that the “integratedMode” and “classicMode” preconditions only apply to handlers, and the “managedHandler” precondition only applies to modules. Also note that there are other preconditions that we have not discussed here.  These can be used to restrict the handler or module to a version of the framework, or specific processor architecture (32-bit or 64-bit), for example.

The ASP.NET <httpHandlers> section has no knowledge of preconditions, and so you should never use them there.  The same is true for <httpModules>.

5.0 Troubleshooting

If you receive an error similar to the one below, your <handler> section is probably invalid. 

HTTP Error 500.21 - Internal Server Error
Handler "<HANDLER_NAME>" has a bad module "ManagedPipelineHandler" in its module list

You probably have a handler mapping that does not have the correct precondition.  IIS is not forgiving in regard to typos, and preconditions are case-sensitive.  The text must be preCondition=”integratedMode” or preCondition=”classicMode” .

Comments

  • Anonymous
    November 04, 2007
    This is an excellent post on the areas of confusion that might arise about IIS 7 features. Tnx.

  • Anonymous
    August 14, 2008
    Fantastic! Thanks, helped me solve an issue that was driving me around the bend. Cheers, Robert Porter

  • Anonymous
    August 27, 2008
    This post discusses an efficient way to compress content served by the ASP.NET output cache. In .NET

  • Anonymous
    January 24, 2011
    This was very usefult. Thanks! I found that I can also get the "Handler <HANDLER_NAME> has a bad module ManagedPipelineHandler in its module list" if the handler has requireAccess="None". For me, changing this to requireAccess="Read" made the error go away.

  • Anonymous
    January 27, 2014
    Very nice article. This what I was looking for.

  • Anonymous
    June 21, 2014
    Nice post.  Very good clear explanation of a confusing topic.