ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.

0
This topic outlines the life cycle of ASP.NET applications, listing important life-cycle events and describing how code
that you write can fit into the application life cycle. The information in this topic applies to IIS 5.0 and IIS 6.0. For
information about the ASP.NET application life cycle in IIS 7.0, see ASP.NET Application Life Cycle Overview for IIS
7.0.

Within ASP.NET, several processing steps must occur for an ASP.NET application to be initialized and process
requests. Additionally, ASP.NET is only one piece of the Web server architecture that services requests made by
browsers. It is important for you to understand the application life cycle so that you can write code at the
appropriate life cycle stage for the effect you intend.

Application Life Cycle in General

The following table describes the stages of the ASP.NET application life cycle.

Stage Description

User requests an The life cycle of an ASP.NET application starts with a request sent by a browser to the
application Web server (for ASP.NET applications, typically IIS). ASP.NET is an ISAPI extension
resource from under the Web server. When a Web server receives a request, it examines the file-name
the Web server. extension of the requested file, determines which ISAPI extension should handle the
request, and then passes the request to the appropriate ISAPI extension. ASP.NET
handles file name extensions that have been mapped to it, such as .aspx, .ascx, .ashx,
and .asmx.
Note:
If a file name extension has not been mapped to ASP.NET, ASP.NET will not receive the
request. This is important to understand for applications that use ASP.NET
authentication. For example, because .htm files are typically not mapped to ASP.NET,
ASP.NET will not perform authentication or authorization checks on requests for .htm
files. Therefore, even if a file contains only static content, if you want ASP.NET to check
authentication, create the file using a file name extension mapped to ASP.NET, such as
.aspx.
Note:
If you create a custom handler to service a particular file name extension, you must
map the extension to ASP.NET in IIS and also register the handler in your application's
Web.config file. For more information, see HTTP Handlers and HTTP Modules Overview.

ASP.NET When ASP.NET receives the first request for any resource in an application, a class
receives the first named ApplicationManager creates an application domain. Application domains provide
request for the isolation between applications for global variables and allow each application to be
application. unloaded separately. Within an application domain, an instance of the class named
HostingEnvironment is created, which provides access to information about the
application such as the name of the folder where the application is stored.
The following diagram illustrates this relationship:
 ASP.NET also compiles the top-level items in the application if required, including
application code in the App_Code folder. For more information, see "Compilation Life
Cycle" later in this topic.

ASP.NET core After the application domain has been created and the HostingEnvironment object
objects are instantiated, ASP.NET creates and initializes core objects such as HttpContext,
created for each HttpRequest, and HttpResponse. The HttpContext class contains objects that are specific
request. to the current application request, such as the HttpRequest and HttpResponse objects.
The HttpRequest object contains information about the current request, including
cookies and browser information. The HttpResponse object contains the response that is
sent to the client, including all rendered output and cookies.

An After all core application objects have been initialized, the application is started by
HttpApplication creating an instance of the HttpApplication class. If the application has a Global.asax
object is file, ASP.NET instead creates an instance of the Global.asax class that is derived from
assigned to the the HttpApplication class and uses the derived class to represent the application.
request Note:
The first time an ASP.NET page or process is requested in an application, a new instance
of HttpApplication is created. However, to maximize performance, HttpApplication
instances might be reused for multiple requests.
When an instance of HttpApplication is created, any configured modules are also
created. For instance, if the application is configured to do so, ASP.NET creates a
SessionStateModule module. After all configured modules are created, the
HttpApplication class's Init method is called.
The following diagram illustrates this relationship:
The request is The following events are executed by the HttpApplication class while the request is
processed by the processed. The events are of particular interest to developers who want to extend the
HttpApplication HttpApplication class.
pipeline. 1. Validate the request, which examines the information sent by the browser and
determines whether it contains potentially malicious markup. For more
information, see ValidateRequest and Script Exploits Overview.
2. Perform URL mapping, if any URLs have been configured in the
UrlMappingsSection section of the Web.config file.
3. Raise the BeginRequest event.

4. Raise the AuthenticateRequest event.

5. Raise the PostAuthenticateRequest event.

6. Raise the AuthorizeRequest event.

7. Raise the PostAuthorizeRequest event.

8. Raise the ResolveRequestCache event.

9. Raise the PostResolveRequestCache event.

10. Based on the file name extension of the requested resource (mapped in the
application's configuration file), select a class that implements IHttpHandler to
 process the request. If the request is for an object (page) derived from the
Page class and the page needs to be compiled, ASP.NET compiles the page
before creating an instance of it.
11. Raise the PostMapRequestHandler event.
12. Raise the AcquireRequestState event.
13. Raise the PostAcquireRequestState event.
14. Raise the PreRequestHandlerExecute event.
15. Call the ProcessRequest method (or the asynchronous version
IHttpAsyncHandler..::.BeginProcessRequest) of the appropriate IHttpHandler
class for the request. For example, if the request is for a page, the current page
instance handles the request.
16. Raise the PostRequestHandlerExecute event.
17. Raise the ReleaseRequestState event.
18. Raise the PostReleaseRequestState event.
19. Perform response filtering if the Filter property is defined.
20. Raise the UpdateRequestCache event.
21. Raise the PostUpdateRequestCache event.
22. Raise the EndRequest event.
23. Raise the PreSendRequestHeaders event.
24. Raise the PreSendRequestContent event.
Life Cycle Events and the Global.asax file
During the application life cycle, the application raises events that you can handle and calls particular methods that
you can override. To handle application events or methods, you can create a file named Global.asax in the root
directory of your application.

If you create a Global.asax file, ASP.NET compiles it into a class derived from the HttpApplication class, and then
uses the derived class to represent the application.

An instance of HttpApplication processes only one request at a time. This simplifies application event handling
because you do not need to lock non-static members in the application class when you access them. This also
allows you to store request-specific data in non-static members of the application class. For example, you can
define a property in the Global.asax file and assign it a request-specific value.

ASP.NET automatically binds application events to handlers in the Global.asax file using the naming convention
Application_event, such as Application_BeginRequest. This is similar to the way that ASP.NET page methods
are automatically bound to events, such as the page's Page_Load event. For details, see ASP.NET Page Life Cycle
Overview.
The Application_Start and Application_End methods are special methods that do not represent HttpApplication
events. ASP.NET calls them once for the lifetime of the application domain, not for each HttpApplication instance.

The following table lists some of the events and methods that are used during the application life cycle. There are
many more events than those listed, but they are not commonly used.

Event or method Description

Application_Start Called when the first resource (such as a page) in an ASP.NET application is
requested. The Application_Start method is called only one time during the life
cycle of an application. You can use this method to perform startup tasks such as
loading data into the cache and initializing static values.
You should set only static data during application start. Do not set any instance data
because it will be available only to the first instance of the HttpApplication class that
is created.

Application_event Raised at the appropriate time in the application life cycle, as listed in the application
life cycle table earlier in this topic.
Application_Error can be raised at any phase in the application life cycle.
Application_EndRequest is the only event that is guaranteed to be raised in every
request, because a request can be short-circuited. For example, if two modules
handle the Application_BeginRequest event and the first one throws an
exception, the Application_BeginRequest event will not be called for the second
module. However, the Application_EndRequest method is always called to allow
the application to clean up resources.

Init Called once for every instance of the HttpApplication class after all modules have
been created.

Dispose Called before the application instance is destroyed. You can use this method to
manually release any unmanaged resources. For more information, see Cleaning Up
Unmanaged Resources.

Application_End Called once per lifetime of the application before the application is unloaded.
Compilation Life Cycle
When the first request is made to an application, ASP.NET compiles application items in a specific order. The first
items to be compiled are referred to as the top-level items. After the first request, the top-level items are
recompiled only if a dependency changes. The following table describes the order in which ASP.NET top-level items
are compiled.

Item Description

App_GlobalResources The application's global resources are compiled and a resource assembly
is built. Any assemblies in the application's Bin folder are linked to the
resource assembly.

App_WebResources Proxy types for Web services are created and compiled. The resulting Web
references assembly is linked to the resource assembly if it exists.

Profile properties defined in If profile properties are defined in the application's Web.config file, an
the Web.config file assembly is generated that contains a profile object.

App_Code Source code files are built and one or more assemblies are created. All
code assemblies and the profile assembly are linked to the resources and
Web references assemblies if any.

Global.asax The application object is compiled and linked to all of the previously
generated assemblies.
After the application's top level items have been compiled, ASP.NET compiles folders, pages, and other items as
needed. The following table describes the order in which ASP.NET folders and items are compiled.

Item Description

App_LocalResources If the folder containing the requested item contains an

App_LocalResources folder, the contents of the local
resources folder are compiled and linked to the global
resources assembly.

Individual Web pages (.aspx files), user Compiled as needed and linked to the local resources
controls (.ascx files), HTTP handlers (.ashx assembly and the top-level assemblies.
files), and HTTP modules (.asmx files)

Themes, master pages, other source files Skin files for individual themes, master pages, and other
source code files referenced by pages are compiled when
the referencing page is compiled.
Compiled assemblies are cached on the server and reused on subsequent requests and are preserved across
application restarts as long as the source code is unchanged.

Because the application is compiled on the first request, the initial request to an application can take significantly
longer than subsequent requests. You can precompile your application to reduce the time required for the first
request. For more information, see How to: Precompile ASP.NET Web Sites.

Application Restarts
Modifying the source code of your Web application will cause ASP.NET to recompile source files into assemblies.
When you modify the top-level items in your application, all other assemblies in the application that reference the
top-level assemblies are recompiled as well.

In addition, modifying, adding, or deleting certain types of files within the application's known folders will cause the
application to restart. The following actions will cause an application restart:

• Adding, modifying, or deleting assemblies from the application's Bin folder.

• Adding, modifying, or deleting localization resources from the App_GlobalResources or

App_LocalResources folders.

• Adding, modifying, or deleting the application's Global.asax file.

• Adding, modifying, or deleting source code files in the App_Code directory.

• Adding, modifying, or deleting Profile configuration.

• Adding, modifying, or deleting Web service references in the App_WebReferences directory.

• Adding, modifying, or deleting the application's Web.config file.

When an application restart is required, ASP.NET will serve all pending requests from the existing application
domain and the old assemblies before restarting the application domain and loading the new assemblies.

HTTP Modules
The ASP.NET application life cycle is extensible through IHttpModule classes. ASP.NET includes several classes that
implement IHttpModule, such as the SessionStateModule class. You can also create your own classes that
implement IHttpModule.

If you add modules to your application, the modules themselves can raise events. The application can subscribe to
in these events in the Global.asax file by using the convention modulename_eventname. For example, to handle
the Authenticate event raised by a FormsAuthenticationModule object, you can create a handler named
FormsAuthentication_Authenticate.
The SessionStateModule class is enabled by default in ASP.NET. All session events are automatically wired up as
Session_event, such as Session_Start. The Start event is raised each time a new session is created. For more
information, see ASP.NET Session State Overview.
ASP.NET Application Life Cycle Overview for IIS 7.0
This topic describes the application life cycle for ASP.NET applications that are running in IIS 7.0 in Integrated
mode and with the .NET Framework 3.0 or later. IIS 7.0 also supports Classic mode, which behaves like ASP.NET
running in IIS 6.0. For more information, see ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0.

The IIS 7.0 integrated pipeline is a unified request processing pipeline that supports both native-code and
managed-code modules. Managed-code modules that implement the IHttpModule interface have access to all
events in the request pipeline. For example, a managed-code module can be used for ASP.NET forms authentication
for both ASP.NET Web pages (.aspx files) and HTML pages (.htm or .html files). This is true even though HTML
pages are treated as static resources by IIS and ASP.NET. For more information about IIS 7.0 Integrated mode, see
ASP.NET Integration with IIS7.

This topic contains the following sections:

• Architectural Overview

• Life Cycle Stages

• Using the Global.asax File

• Managed-code Modules in IIS 7.0

Architectural Overview
A request in IIS 7.0 Integrated mode passes through stages that are like the stages of requests for ASP.NET
resources in IIS 6.0. However, in IIS 7.0, these stages include several additional application events, such as the
MapRequestHandler, LogRequest, and PostLogRequest events.

The main difference in processing stages between IIS 7.0 and IIS 6.0 is in how ASP.NET is integrated with the IIS
server. In IIS 6.0, there are two request processing pipelines. One pipeline is for native-code ISAPI filters and
extension components. The other pipeline is for managed-code application components such as ASP.NET. In IIS
7.0, the ASP.NET runtime is integrated with the Web server so that there is one unified request processing pipeline
for all requests. For ASP.NET developers, the benefits of the integrated pipeline are as follows:

• The integrated pipeline raises all the events that are exposed by the HttpApplication object, which enables

existing ASP.NET HTTP modules to work in IIS 7.0 Integrated mode.

• Both native-code and managed-code modules can be configured at the Web server, Web site, or Web

application level. This includes the built-in ASP.NET managed-code modules for session state, forms
authentication, profiles, and role management. Furthermore, managed-code modules can be enabled or
disabled for all requests, regardless of whether the request is for an ASP.NET resource like an .aspx file.

• Managed-code modules can be invoked at any stage in the pipeline. This includes before any server

processing occurs for the request, after all server processing has occurred, or anywhere in between.

• You can register and enable or disable modules through an application’s Web.config file.

The following illustration shows the configuration of an application's request pipeline. The example includes the
following:
 • The Anonymous native-code module and the Forms managed-code module (which corresponds to

FormsAuthenticationModule). These modules are configured, and they are invoked during the
Authentication stage of the request.

• The Basic native-code module and the Windows managed-code module (which corresponds to

WindowsAuthenticationModule). They are shown, but they are not configured for the application.

• The Execute handler stage, where the handler (a module scoped to a URL) is invoked to construct the

response. For .aspx files, the PageHandlerFactory handler is used to respond to the request. For static
files, the native-code StaticFileModule module responds to the request.

• The Trace native-code module. This is shown, but it is not configured for the application.

• The Custom module managed-code class. It is invoked during the Log request stage.

For information about known compatibility issues with ASP.NET applications that are being migrated from earlier
versions of IIS to IIS 7.0, see the "Known Differences Between Integrated Mode and Classic Mode" section of
Upgrading ASP.NET Applications to IIS 7.0: Differences between IIS 7.0 Integrated Mode and Classic mode.

Life Cycle Stages

The following table lists the stages of the ASP.NET application life cycle with Integrated mode in IIS 7.0.

Stage Description

A request is made The life cycle of an ASP.NET application starts with a request sent by a browser to
for an application the Web server.
resource. In Classic mode in IIS 7.0 and in IIS 6.0, the ASP.NET request pipeline is separate
from the Web server pipeline. Modules apply only to requests that are routed to the
ASP.NET ISAPI extension. If the file-name extension of the requested resource
type is not explicitly mapped to ASP.NET, ASP.NET functionality is not invoked for
the request because the request is not processed by the ASP.NET runtime.
 In integrated mode in IIS 7.0, a unified pipeline handles all requests. When the
integrated pipeline receives a request, the request passes through stages that are
common to all requests. These stages are represented by the RequestNotification
enumeration. All requests can be configured to take advantage of ASP.NET
functionality, because that functionality is encapsulated in managed-code modules
that have access to the request pipeline. For example, even though the .htm file-
name extension is not explicitly mapped to ASP.NET, a request for an HTML page
still invokes ASP.NET modules. This enables you to take advantage of ASP.NET
authentication and authorization for all resources.

The unified pipeline When the unified pipeline receives the first request for any resource in an
receives the first application, an instance of the ApplicationManager class is created, which is the
request for the application domain that the request is processed in. Application domains provide
application. isolation between applications for global variables and enable each application to be
unloaded separately. In the application domain, an instance of the
HostingEnvironment class is created, which provides access to information about
the application, such as the name of the folder where the application is stored.
During the first request, top-level items in the application are compiled if required,
which includes application code in the App_Code folder. You can include custom
modules and handlers in the App_Code folder as described in Managed-code
Modules in IIS 7.0 later in this topic.

Response objects are After the application domain has been created and the HostingEnvironment object
created for each has been instantiated, application objects such as HttpContext, HttpRequest, and
request. HttpResponse are created and initialized. The HttpContext class contains objects
that are specific to the current application request, such as the HttpRequest and
HttpResponse objects. The HttpRequest object contains information about the
current request, which includes cookies and browser information. The HttpResponse
object contains the response that is sent to the client, which includes all the
rendered output and cookies.
The following are some key differences between IIS 6.0 and IIS 7.0 running in
Integrated mode and with the .NET Framework 3.0 or later:
• The SubStatusCode property of the HttpResponse object is available for setting
codes that are useful for failed-request tracing. For more information, see
Troubleshooting Failed Requests Using Failed Request Tracing in IIS 7.0.
• The Headers property of the HttpResponse object provides access to response
headers for the response.
• Two properties of the HttpContext object, IsPostNotification and
CurrentNotification, are used when one event handler handles several
HttpApplication events.
• The Headers and ServerVariables property of the HttpRequest object are write-
enabled.

An HttpApplication After all application objects have been initialized, the application is started by
object is assigned to creating an instance of the HttpApplication class. If the application has a
the request Global.asax file, ASP.NET instead creates an instance of the Global.asax class that is
derived from the HttpApplication class. It then uses the derived class to represent
the application.
Note:
The first time that an ASP.NET page or process is requested in an application, a new
instance of the HttpApplication class is created. However, to maximize performance,
HttpApplication instances might be reused for multiple requests.
Which ASP.NET modules are loaded (such as the SessionStateModule) depends on
the managed-code modules that the application inherits from a parent application.
It also depends on which modules are configured in the configuration section of the
application's Web.config file. Modules are added or removed in the application's
Web.config modules element in the system.webServer section. For more
 information, see How to: Configure the <system.webServer> Section for IIS 7.0.

The request is The following tasks are performed by the HttpApplication class while the request is
processed by the being processed. The events are useful for page developers who want to run code
HttpApplication when key request pipeline events are raised. They are also useful if you are
pipeline. developing a custom module and you want the module to be invoked for all
requests to the pipeline. Custom modules implement the IHttpModule interface. In
Integrated mode in IIS 7.0, you must register event handlers in a module's Init
method.
1. Validate the request, which examines the information sent by the browser
and determines whether it contains potentially malicious markup. For more
information, see ValidateRequest and Script Exploits Overview.
2. Perform URL mapping, if any URLs have been configured in the
UrlMappingsSection section of the Web.config file.
3. Raise the BeginRequest event.

4. Raise the AuthenticateRequest event.

5. Raise the PostAuthenticateRequest event.

6. Raise the AuthorizeRequest event.

7. Raise the PostAuthorizeRequest event.

8. Raise the ResolveRequestCache event.

9. Raise the PostResolveRequestCache event.

10. Raise the MapRequestHandler event. An appropriate handler is selected

based on the file-name extension of the requested resource. The handler
can be a native-code module such as the IIS 7.0 StaticFileModule or a
managed-code module such as the PageHandlerFactory class (which
handles .aspx files).
11. Raise the PostMapRequestHandler event.
12. Raise the AcquireRequestState event.
13. Raise the PostAcquireRequestState event.
14. Raise the PreRequestHandlerExecute event.
15. Call the ProcessRequest method (or the asynchronous version
IHttpAsyncHandler..::.BeginProcessRequest) of the appropriate
IHttpHandler class for the request. For example, if the request is for a
page, the current page instance handles the request.
16. Raise the PostRequestHandlerExecute event.
17. Raise the ReleaseRequestState event.
18. Raise the PostReleaseRequestState event.
19. Perform response filtering if the Filter property is defined.
20. Raise the UpdateRequestCache event.
21. Raise the PostUpdateRequestCache event.
22. Raise the LogRequest event.
23. Raise the PostLogRequest event.
 24. Raise the EndRequest event.
25. Raise the PreSendRequestHeaders event.
26. Raise the PreSendRequestContent event.

Note:

The MapRequestHandler, LogRequest, and PostLogRequest events are

supported only if the application is running in Integrated mode in IIS 7.0
and with the .NET Framework 3.0 or later.
Using the Global.asax File
The Global.asax file is used in Integrated mode in IIS 7.0 much as it is used in ASP.NET in IIS 6.0. For more
information, see the "Life Cycle Events and Global.asax File" section in ASP.NET Application Life Cycle Overview for
IIS 5.0 and 6.0.

One difference is that you can add handlers for the MapRequestHandler, LogRequest, and PostLogRequest events.
These events are supported for applications that run in Integrated mode in IIS 7.0 and with the .NET Framework
3.0 or later.

You can provide application event handlers in the Global.asax file to add code that executes for all requests that are
handled by ASP.NET, such as requests for .aspx and .axd pages. However, handler code in the Global.asax file is not
called for requests for non-ASP.NET resources, such as static files. To run managed code that runs for all resources,
create a custom module that implements the IHttpModule interface. The custom module will run for all requests to
resources in the application, even if the resource handler is not an ASP.NET handler.

Managed-code Modules in IIS 7.0

The ASP.NET managed-code modules that can be configured and loaded in IIS 7.0 include the following:

• FormsAuthenticationModule

• ProfileModule

• RoleManagerModule

• SessionStateModule

To configure IIS 7.0 managed-code modules you can use one of the following methods:

• Use IIS Manager. For more information, see How to: Open IIS Manager.

• Use the IIS 7.0 command-line tool (Appcmd.exe). For more information, see IIS 7.0 Command-Line Tool.

• Edit the IIS 7.0 XML-based configuration store. For more information, see IIS 7.0: IIS 7.0 Configuration

Store.

When an ASP.NET managed-code module such as the FormsAuthenticationModule module is configured to load in
IIS 7.0, it has access to all events in the request pipeline. This means that all requests pass through the managed-
code module. For the FormsAuthenticationModule class, it means that static content can be protected by using
forms authentication, even though the content is not handled by an ASP.NET handler.
Developing Custom Managed-code Modules
The ASP.NET application life cycle can be extended with modules that implement the IHttpModule interface.
Modules that implement the IHttpModule interface are managed-code modules. The integrated pipeline of ASP.NET
and IIS 7.0 is also extensible through native-code modules, which are not discussed in this topic. For more
information about native-code modules and about how to configure modules generally, see IIS Module Overview.

You can define a managed-code module as a class file in the application's App_Code folder. You can also create the
module as a class library project, compile it, and add it to application's Bin folder. After you have created the
custom module, you must register it with IIS 7.0. You can use one of the methods described for managing IIS 7.0
managed-code modules. For example, you can edit an application's Web.config file to register the managed-code
module for just that application. For an example of registering a module, see Walkthrough: Creating and
Registering a Custom HTTP Module.

If a module is defined an application's App_Code or Bin folder and it is registered in the application's Web.config
file, the module is invoked only for that application. To register the module in the application’s Web.config file, you
work with the modules element in the system.webServer section. For more information, see How to: Configure
the <system.webServer> Section for IIS 7.0. Changes made by using IIS Manager or the Appcmd.exe tool will
make changes to the application's Web.config file.

Managed-code modules can also be registered in the modules element of the IIS 7.0 configuration store (the
ApplicationHost.config file). Modules registered in the ApplicationHost.config file have global scope because they
are registered for all Web applications hosted by IIS 7.0. Similarly, native-code modules that are defined in the
globalModules element of the ApplicationHost.config file have global scope. If a global module is not needed for a
Web application, you can disable it.

Example
The following example shows a custom module that handles the LogRequest and PostLogRequest events. Event
handlers are registered in the Init method of the module.

Visual Basic

Copy Code
Imports System
Imports System.Data
Imports System.Web
Imports System.Web.Security
Imports System.Web.UI
Imports Microsoft.VisualBasic

' Module that demonstrates one event handler for several events.
Namespace Samples

Public Class ModuleExample

Implements IHttpModule

Public Sub New()

' Constructor
 End Sub

Public Sub Init(ByVal app As HttpApplication) Implements

IHttpModule.Init
AddHandler app.LogRequest, AddressOf Me.App_Handler
AddHandler app.PostLogRequest, AddressOf Me.App_Handler
End Sub

Public Sub Dispose() Implements IHttpModule.Dispose

End Sub

' One for both the LogRequest and PostLogRequest events.

Public Sub App_Handler(ByVal source As Object, ByVal e As EventArgs)
Dim app As HttpApplication = CType(source, HttpApplication)
Dim context As HttpContext = app.Context

If (context.CurrentNotification = RequestNotification.LogRequest)
Then

If Not (context.IsPostNotification) Then

' Put code here that is invoked when the LogRequest event
is raised.

Else
' PostLogRequest
' Put code here that runs after the LogRequest event
completes.

End If
End If
End Sub
End Class

End Namespace

C#

Copy Code
using System;
using System.Data;
using System.Web;
using System.Web.Security;
using System.Web.UI;

// Module that demonstrates one event handler for several events.

namespace Samples
{
public class ModuleExample : IHttpModule
{
public ModuleExample()
{
// Constructor
}
public void Init(HttpApplication app)
{
app.LogRequest += new EventHandler(App_Handler);
app.PostLogRequest += new EventHandler(App_Handler);
}
public void Dispose()
{
}
// One handler for both the LogRequest and the PostLogRequest events.
public void App_Handler(object source, EventArgs e)
{
HttpApplication app = (HttpApplication)source;
HttpContext context = app.Context;

if (context.CurrentNotification == RequestNotification.LogRequest)
{
if (!context.IsPostNotification)
{
// Put code here that is invoked when the LogRequest
event is raised.
}
else
{
// PostLogRequest
// Put code here that runs after the LogRequest event
completes.
}
}
 }
}
}

The following example shows how to register the module in the application’s Web.config file. Add the
system.webServer configuration section inside the configuration section.

<system.webServer>
<modules>
<add name="ModuleExample" type="Samples.ModuleExample"/>
</modules>
</system.webServer>
For an additional example that shows how to create and register a custom module, see Walkthrough: Creating and
Registering a Custom HTTP Module.

ASP.NET Page Life Cycle Overview (.Net 2.0)

When an ASP.NET page runs, the page goes through a life cycle in which it performs a series of processing steps.
These include initialization, instantiating controls, restoring and maintaining state, running event handler code, and
rendering. It is important for you to understand the page life cycle so that you can write code at the appropriate
life-cycle stage for the effect you intend. Additionally, if you develop custom controls, you must be familiar with the
page life cycle in order to correctly initialize controls, populate control properties with view-state data, and run any
control behavior code. (The life cycle of a control is based on the page life cycle, but the page raises more events
for a control than are available for an ASP.NET page alone.)

General Page Life-cycle Stages

In general terms, the page goes through the stages outlined in the following table. In addition to the page life-cycle
stages, there are application stages that occur before and after a request but are not specific to a page. For more
information, see ASP.NET Application Life Cycle Overview.

Stage Description

Page request The page request occurs before the page life cycle begins. When the page is requested
by a user, ASP.NET determines whether the page needs to be parsed and compiled
(therefore beginning the life of a page), or whether a cached version of the page can be
sent in response without running the page.

Start In the start step, page properties such as Request and Response are set. At this stage,
the page also determines whether the request is a postback or a new request and sets
the IsPostBack property. Additionally, during the start step, the page's UICulture property
is set.

Page During page initialization, controls on the page are available and each control's UniqueID
initialization property is set. Any themes are also applied to the page. If the current request is a
postback, the postback data has not yet been loaded and control property values have
not been restored to the values from view state.

Load During load, if the current request is a postback, control properties are loaded with
information recovered from view state and control state.
Validation During validation, the Validate method of all validator controls is called, which sets the
IsValid property of individual validator controls and of the page.

Postback event If the request is a postback, any event handlers are called.
handling

Rendering Before rendering, view state is saved for the page and all controls. During the rendering
phase, the page calls the Render method for each control, providing a text writer that
writes its output to the OutputStream of the page's Response property.

Unload Unload is called after the page has been fully rendered, sent to the client, and is ready to
be discarded. At this point, page properties such as Response and Request are
unloaded and any cleanup is performed.

Life-cycle Events
Within each stage of the life cycle of a page, the page raises events that you can handle to run your own code. For
control events, you bind the event handler to the event, either declaratively using attributes such as onclick, or in
code.

Pages also support automatic event wire-up, meaning that ASP.NET looks for methods with particular names and
automatically runs those methods when certain events are raised. If the AutoEventWireup attribute of the
@ Page directive is set to true (or if it is not defined, since by default it is true), page events are automatically
bound to methods that use the naming convention of Page_event, such as Page_Load and Page_Init. For more
information on automatic event wire-up, see ASP.NET Web Server Control Event Model.

The following table lists the page life-cycle events that you will use most frequently. There are more events than
those listed; however, they are not used for most page processing scenarios. Instead, they are primarily used by
server controls on the ASP.NET Web page to initialize and render themselves. If you want to write your own
ASP.NET server controls, you need to understand more about these stages. For information about creating custom
controls, see Developing Custom ASP.NET Server Controls.

Page Event Typical Use

PreInit Use this event for the following:

• Check the IsPostBack property to determine whether this is the first time the
page is being processed.
• Create or re-create dynamic controls.

• Set a master page dynamically.

• Set the Theme property dynamically.

• Read or set profile property values.

•
 Note

If the request is a postback, the values of the controls have not yet been
restored from view state. If you set a control property at this stage, its value
might be overwritten in the next event.

Init Raised after all controls have been initialized and any skin settings have been
applied. Use this event to read or initialize control properties.

InitComplete Raised by the Page object. Use this event for processing tasks that require all
initialization be complete.

PreLoad Use this event if you need to perform processing on your page or control before the
Load event.
After the Page raises this event, it loads view state for itself and all controls, and
then processes any postback data included with the Request instance.

Load The Page calls the OnLoad event method on the Page, then recursively does the
same for each child control, which does the same for each of its child controls until
the page and all controls are loaded.
Use the OnLoad event method to set properties in controls and establish database
connections.

Control events Use these events to handle specific control events, such as a Button control's Click
event or a TextBox control's TextChanged event.

Note

In a postback request, if the page contains validator controls, check the

IsValid property of the Page and of individual validation controls before
performing any processing.

LoadComplete Use this event for tasks that require that all other controls on the page be loaded.

PreRender Before this event occurs:

• The Page object calls EnsureChildControls for each control and for the page.

• Each data bound control whose DataSourceID property is set calls its DataBind
method. For more information, see Data Binding Events for Data-Bound
Controls below.
The PreRender event occurs for each control on the page. Use the event to make
final changes to the contents of the page or its controls.
SaveStateComplete Before this event occurs, ViewState has been saved for the page and for all controls.
Any changes to the page or controls at this point will be ignored.
Use this event perform tasks that require view state to be saved, but that do not
make any changes to controls.

Render This is not an event; instead, at this stage of processing, the Page object calls this
method on each control. All ASP.NET Web server controls have a Render method
that writes out the control's markup that is sent to the browser.
If you create a custom control, you typically override this method to output the
control's markup. However, if your custom control incorporates only standard
ASP.NET Web server controls and no custom markup, you do not need to override
the Render method. For more information, see Developing Custom ASP.NET Server
Controls.
A user control (an .ascx file) automatically incorporates rendering, so you do not
need to explicitly render the control in code.

Unload This event occurs for each control and then for the page. In controls, use this event
to do final cleanup for specific controls, such as closing control-specific database
connections.
For the page itself, use this event to do final cleanup work, such as closing open files
and database connections, or finishing up logging or other request-specific tasks.

Note

During the unload stage, the page and its controls have been rendered, so
you cannot make further changes to the response stream. If you attempt to
call a method such as the Response.Write method, the page will throw an
exception.

Additional Page Life Cycle Considerations

Individual ASP.NET server controls have their own life cycle that is similar to the page life cycle. For example, a
control's Init and Load events occur during the corresponding page events.

Although both Init and Load recursively occur on each control, they happen in reverse order. The Init event (and
also the Unload event) for each child control occur before the corresponding event is raised for its container
(bottom-up). However the Load event for a container occurs before the Load events for its child controls (top-
down).

You can customize the appearance or content of a control by handling the events for the control, such as the Click
event for the Button control and the SelectedIndexChanged event for the ListBox control. Under some
circumstances, you might also handle a control's DataBinding or DataBound events. For more information, see the
class reference topics for individual controls and Developing Custom ASP.NET Server Controls.

When inheriting a class from the Page class, in addition to handling events raised by the page, you can override
methods from the page's base class. For example, you can override the page's InitializeCulture method to
dynamically set culture information. Note that when creating an event handler using the Page_event syntax, the
base implementation is implicitly called and therefore you do not need to call it in your method. For example, the
base page class's OnLoad method is always called, whether you create a Page_Load method or not. However, if
you override the page OnLoad method with the override keyword (Overrides in Visual Basic), you must explicitly
call the base method. For example, if you override the OnLoad method on the page, you must call base.Load
(MyBase.Load in Visual Basic) in order for the base implementation to be run.

Catch-up Events for Added Controls

If controls are created dynamically at run time or are authored declaratively within templates of data-bound
controls, their events are initially not synchronized with those of other controls on the page. For example, for a
control that is added at run time, the Init and Load events might occur much later in the page life cycle than the
same events for controls created declaratively. Therefore, from the time that they are instantiated, dynamically
added controls and controls in templates raise their events one after the other until they have caught up to the
event during which it was added to the Controls collection.

In general, you do not need to be concerned about this unless you have nested data-bound controls. If a child
control has been data bound, but its container control has not yet been data bound, the data in the child control
and the data in its container control can be out of sync. This is true particularly if the data in the child control
performs processing based on a data-bound value in the container control.

For example, suppose you have a GridView that displays a company record in each row along with a list of the
company officers in a ListBox control. To fill the list of officers, you would bind the ListBox control to a data
source control (such as SqlDataSource) that retrieves the company officer data using the CompanyID in a query.

If the ListBox control's data-binding properties, such as DataSourceID and DataMember, are set declaratively, the
ListBox control will try to bind to its data source during the containing row's DataBinding event. However, the
CompanyID field of the row does not contain a value until the GridView control's RowDataBound event occurs. In
this case, the child control (the ListBox control) is bound before the containing control (the GridView control) is
bound, so their data-binding stages are out of sync.

To avoid this condition, put the data source control for the ListBox control in the same template item as the
ListBox control itself, and do not set the data binding properties of the ListBox declaratively. Instead, set them
programmatically at run time during the RowDataBound event, so that the ListBox control does not bind to its
data until the CompanyID information is available.

For more information, see Binding to Data Using a Data Source Control.

Data Binding Events for Data-Bound Controls

To help you understand the relationship between the page life cycle and data binding events, the following table
lists data-related events in data-bound controls such as the GridView, DetailsView, and FormView controls.

Control Event Typical Use

DataBinding This event is raised by data-bound controls before the

PreRender event of the containing control (or of the Page
object) and marks the beginning of binding the control to the
data.
Use this event to manually open database connections, if
required. (The data source controls often make this
unnecessary.)

RowCreated (GridView only) or Use this event to manipulate content that is not dependent on
ItemCreated (DataList, DetailsView, data binding. For example, at run time, you might
SiteMapPath, DataGrid, FormView, and programmatically add formatting to a header or footer row in a
Repeater controls) GridView control.
RowDataBound (GridView only) or When this event occurs, data is available in the row or item, so
ItemDataBound (DataList, you can format data or set the FilterExpression property on
SiteMapPath, DataGrid, and Repeater child data source controls for displaying related data within the
controls) row or item.

DataBound This event marks the end of data-binding operations in a data-

bound control. In a GridView control, data binding is complete
for all rows and any child controls.
Use this event to format data bound content or to initiate data
binding in other controls that depend on values from the
current control's content. (For details, see "Catch-up Events for
Added Controls" earlier in this topic.)

Login Control Events

The Login control can use settings in the Web.config file to manage membership authentication automatically.
However, if your application requires you to customize how the control works, or if you want to understand how
Login control events relate to the page life cycle, you can use the events listed in the following table.

Control
Event Typical Use

LoggingIn This event is raised during a postback, after the page's LoadComplete event has
occurred. It marks the beginning of the login process.
Use this event for tasks that must occur prior to beginning the authentication process.

Authenticate This event is raised after the LoggingIn event.

Use this event to override or enhance the default authentication behavior of a Login
control.

LoggedIn This event is raised after the user name and password have been authenticated.
Use this event to redirect to another page or to dynamically set the text in the control.
This event does not occur if there is an error or if authentication fails.

LoginError This event is raised if authentication was not successful.

Use this event to set text in the control that explains the problem or to direct the user to a
different page.

ASP.NET Page Life Cycle Overview (.Net 3.5)

When an ASP.NET page runs, the page goes through a life cycle in which it performs a series of processing steps.
These include initialization, instantiating controls, restoring and maintaining state, running event handler code, and
rendering. It is important for you to understand the page life cycle so that you can write code at the appropriate
life-cycle stage for the effect you intend. Additionally, if you develop custom controls, you must be familiar with the
page life cycle in order to correctly initialize controls, populate control properties with view-state data, and run any
control behavior code. (The life cycle of a control is based on the page life cycle, but the page raises more events
for a control than are available for an ASP.NET page alone.)

General Page Life-cycle Stages

In general terms, the page goes through the stages outlined in the following table. In addition to the page life-cycle
stages, there are application stages that occur before and after a request but are not specific to a page. For more
information, see ASP.NET Application Life Cycle Overview for IIS 7.0.

Stage Description

Page request The page request occurs before the page life cycle begins. When the page is requested
by a user, ASP.NET determines whether the page needs to be parsed and compiled
(therefore beginning the life of a page), or whether a cached version of the page can be
sent in response without running the page.

Start In the start step, page properties such as Request and Response are set. At this stage,
the page also determines whether the request is a postback or a new request and sets
the IsPostBack property. Additionally, during the start step, the page's UICulture property
is set.

Page During page initialization, controls on the page are available and each control's UniqueID
initialization property is set. Any themes are also applied to the page. If the current request is a
postback, the postback data has not yet been loaded and control property values have
not been restored to the values from view state.

Load During load, if the current request is a postback, control properties are loaded with
information recovered from view state and control state.

Validation During validation, the Validate method of all validator controls is called, which sets the
IsValid property of individual validator controls and of the page.

Postback event If the request is a postback, any event handlers are called.
handling

Rendering Before rendering, view state is saved for the page and all controls. During the rendering
phase, the page calls the Render method for each control, providing a text writer that
writes its output to the OutputStream of the page's Response property.

Unload Unload is called after the page has been fully rendered, sent to the client, and is ready to
be discarded. At this point, page properties such as Response and Request are unloaded
and any cleanup is performed.
Life-cycle Events
Within each stage of the life cycle of a page, the page raises events that you can handle to run your own code. For
control events, you bind the event handler to the event, either declaratively using attributes such as onclick, or in
code.

Pages also support automatic event wire-up, meaning that ASP.NET looks for methods with particular names and
automatically runs those methods when certain events are raised. If the AutoEventWireup attribute of the
@ Page directive is set to true (or if it is not defined, since by default it is true), page events are automatically
bound to methods that use the naming convention of Page_event, such as Page_Load and Page_Init. For more
information on automatic event wire-up, see ASP.NET Web Server Control Event Model.
The following table lists the page life-cycle events that you will use most frequently. There are more events than
those listed; however, they are not used for most page processing scenarios. Instead, they are primarily used by
server controls on the ASP.NET Web page to initialize and render themselves. If you want to write your own
ASP.NET server controls, you need to understand more about these stages. For information about creating custom
controls, see Developing Custom ASP.NET Server Controls.

Page Event Typical Use

PreInit Use this event for the following:

• Check the IsPostBack property to determine whether this is the first time the
 page is being processed.
• Create or re-create dynamic controls.

• Set a master page dynamically.

• Set the Theme property dynamically.

• Read or set profile property values.

Note:

If the request is a postback, the values of the controls have not yet been
restored from view state. If you set a control property at this stage, its value
might be overwritten in the next event.

Init Raised after all controls have been initialized and any skin settings have been
applied. Use this event to read or initialize control properties.

InitComplete Raised by the Page object. Use this event for processing tasks that require all
initialization be complete.

PreLoad Use this event if you need to perform processing on your page or control before the
Load event.
Before the Page instance raises this event, it loads view state for itself and all
controls, and then processes any postback data included with the Request instance.

Load The Page calls the OnLoad event method on the Page, then recursively does the
same for each child control, which does the same for each of its child controls until
the page and all controls are loaded.
Use the OnLoad event method to set properties in controls and establish database
connections.

Control events Use these events to handle specific control events, such as a Button control's Click
event or a TextBox control's TextChanged event.
Note:
In a postback request, if the page contains validator controls, check the IsValid
property of the Page and of individual validation controls before performing any
processing.

LoadComplete Use this event for tasks that require that all other controls on the page be loaded.

PreRender Before this event occurs:

• The Page object calls EnsureChildControls for each control and for the page.

• Each data bound control whose DataSourceID property is set calls its DataBind
method. For more information, see Data Binding Events for Data-Bound
Controls later in this topic.
The PreRender event occurs for each control on the page. Use the event to make
final changes to the contents of the page or its controls.

SaveStateComplete Before this event occurs, ViewState has been saved for the page and for all controls.
Any changes to the page or controls at this point will be ignored.
Use this event perform tasks that require view state to be saved, but that do not
make any changes to controls.

Render This is not an event; instead, at this stage of processing, the Page object calls this
method on each control. All ASP.NET Web server controls have a Render method that
writes out the control's markup that is sent to the browser.
If you create a custom control, you typically override this method to output the
control's markup. However, if your custom control incorporates only standard
 ASP.NET Web server controls and no custom markup, you do not need to override
the Render method. For more information, see Developing Custom ASP.NET Server
Controls.
A user control (an .ascx file) automatically incorporates rendering, so you do not
need to explicitly render the control in code.

Unload This event occurs for each control and then for the page. In controls, use this event
to do final cleanup for specific controls, such as closing control-specific database
connections.
For the page itself, use this event to do final cleanup work, such as closing open files
and database connections, or finishing up logging or other request-specific tasks.
Note:
During the unload stage, the page and its controls have been rendered, so you
cannot make further changes to the response stream. If you attempt to call a
method such as the Response.Write method, the page will throw an exception.

Additional Page Life Cycle Considerations

Individual ASP.NET server controls have their own life cycle that is similar to the page life cycle. For example, a
control's Init and Load events occur during the corresponding page events.

Although both Init and Load recursively occur on each control, they happen in reverse order. The Init event (and
also the Unload event) for each child control occur before the corresponding event is raised for its container
(bottom-up). However the Load event for a container occurs before the Load events for its child controls (top-
down).

You can customize the appearance or content of a control by handling the events for the control, such as the Click
event for the Button control and the SelectedIndexChanged event for the ListBox control. Under some
circumstances, you might also handle a control's DataBinding or DataBound events. For more information, see the
class reference topics for individual controls and Developing Custom ASP.NET Server Controls.

When inheriting a class from the Page class, in addition to handling events raised by the page, you can override
methods from the page's base class. For example, you can override the page's InitializeCulture method to
dynamically set culture information. Note that when creating an event handler using the Page_event syntax, the
base implementation is implicitly called and therefore you do not need to call it in your method. For example, the
base page class's OnLoad method is always called, whether you create a Page_Load method or not. However, if
you override the page OnLoad method with the override keyword (Overrides in Visual Basic), you must explicitly
call the base method. For example, if you override the OnLoad method on the page, you must call base.Load
(MyBase.Load in Visual Basic) in order for the base implementation to be run.
Catch-up Events for Added Controls
If controls are created dynamically at run time or are authored declaratively within templates of data-bound
controls, their events are initially not synchronized with those of other controls on the page. For example, for a
control that is added at run time, the Init and Load events might occur much later in the page life cycle than the
same events for controls created declaratively. Therefore, from the time that they are instantiated, dynamically
added controls and controls in templates raise their events one after the other until they have caught up to the
event during which it was added to the Controls collection.

In general, you do not need to be concerned about this unless you have nested data-bound controls. If a child
control has been data bound, but its container control has not yet been data bound, the data in the child control
and the data in its container control can be out of sync. This is true particularly if the data in the child control
performs processing based on a data-bound value in the container control.
For example, suppose you have a GridView that displays a company record in each row along with a list of the
company officers in a ListBox control. To fill the list of officers, you would bind the ListBox control to a data source
control (such as SqlDataSource) that retrieves the company officer data using the CompanyID in a query.

If the ListBox control's data-binding properties, such as DataSourceID and DataMember, are set declaratively, the
ListBox control will try to bind to its data source during the containing row's DataBinding event. However, the
CompanyID field of the row does not contain a value until the GridView control's RowDataBound event occurs. In
this case, the child control (the ListBox control) is bound before the containing control (the GridView control) is
bound, so their data-binding stages are out of sync.

To avoid this condition, put the data source control for the ListBox control in the same template item as the ListBox
control itself, and do not set the data binding properties of the ListBox declaratively. Instead, set them
programmatically at run time during the RowDataBound event, so that the ListBox control does not bind to its data
until the CompanyID information is available.

For more information, see Binding to Data Using a Data Source Control.

Data Binding Events for Data-Bound Controls

To help you understand the relationship between the page life cycle and data binding events, the following table
lists data-related events in data-bound controls such as the GridView, DetailsView, and FormView controls.

Control Event Typical Use

DataBinding This event is raised by data-bound controls before the

PreRender event of the containing control (or of the Page
object) and marks the beginning of binding the control to the
data.
Use this event to manually open database connections, if
required. (The data source controls often make this
unnecessary.)

RowCreated (GridView only) or Use this event to manipulate content that is not dependent on
ItemCreated (DataList, DetailsView, data binding. For example, at run time, you might
SiteMapPath, DataGrid, FormView, programmatically add formatting to a header or footer row in a
Repeater, and ListView controls) GridView control.

RowDataBound (GridView only) or When this event occurs, data is available in the row or item, so
ItemDataBound (DataList, SiteMapPath, you can format data or set the FilterExpression property on
DataGrid, Repeater, and ListView child data source controls for displaying related data within the
controls) row or item.

DataBound This event marks the end of data-binding operations in a data-

bound control. In a GridView control, data binding is complete
for all rows and any child controls.
Use this event to format data bound content or to initiate data
binding in other controls that depend on values from the
current control's content. (For details, see "Catch-up Events for
Added Controls" earlier in this topic.)

Login Control Events

The Login control can use settings in the Web.config file to manage membership authentication automatically.
However, if your application requires you to customize how the control works, or if you want to understand how
Login control events relate to the page life cycle, you can use the events listed in the following table.

Control Typical Use

Event

LoggingIn This event is raised during a postback, after the page's LoadComplete event has occurred.
It marks the beginning of the login process.
Use this event for tasks that must occur prior to beginning the authentication process.

Authenticate This event is raised after the LoggingIn event.

Use this event to override or enhance the default authentication behavior of a Login
control.

LoggedIn This event is raised after the user name and password have been authenticated.
Use this event to redirect to another page or to dynamically set the text in the control.
This event does not occur if there is an error or if authentication fails.

LoginError This event is raised if authentication was not successful.

Use this event to set text in the control that explains the problem or to direct the user to a
different page.