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”.