asp.net application life cycle overview for iis 5.0 and 6 · asp.net application life cycle...
TRANSCRIPT
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 application resource from the
Web server.
The life cycle of an ASP.NET application starts with a request sent by a browser to the Web server (for ASP.NET applications, typically IIS). ASP.NET is an ISAPI extension under the Web server. When a Web server receives a request, it examines the file-name 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 receives the first request for the application.
When ASP.NET receives the first request for any resource in an application, a class named
ApplicationManager creates an application domain. Application domains provide isolation between applications for global variables and allow each application to be 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 objects are created for each request.
After the application domain has been created and the HostingEnvironment object instantiated, ASP.NET creates and initializes core objects such as HttpContext, HttpRequest, and HttpResponse. 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, including cookies and
browser information. The HttpResponse object contains the response that is sent to the client, including all rendered output and cookies.
An HttpApplication object is assigned to the request
After all core application objects have been initialized, the application is started by creating an instance of the HttpApplication class. If the application has a Global.asax file, ASP.NET instead creates an instance of the Global.asax class that is derived from the HttpApplication class and uses the derived class to represent the application.
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 processed by the HttpApplication pipeline.
The following events are executed by the HttpApplication class while the request is processed. The events are of particular interest to developers who want to extend the HttpApplication class.
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 the Web.config file
If profile properties are defined in the application's Web.config file, an 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
controls (.ascx files), HTTP handlers (.ashx files), and HTTP modules (.asmx files)
Compiled as needed and linked to the local resources assembly
and the top-level assemblies.
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 for an application resource.
The life cycle of an ASP.NET application starts with a request sent by a browser to the Web server. 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 receives the first request for the application.
When the unified pipeline receives the first request for any resource in an application, an instance of the ApplicationManager class is created, which is the application domain that the request is processed in. Application domains provide 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 created for each
request.
After the application domain has been created and the HostingEnvironment object has been instantiated, application objects such as HttpContext, HttpRequest, and
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 object is assigned to the request
After all application objects have been initialized, the application is started by creating an instance of the HttpApplication class. If the application has a 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 processed by the HttpApplication pipeline.
The following tasks are performed by the HttpApplication class while the request is being processed. The events are useful for page developers who want to run code when key request pipeline events are raised. They are also useful if you are 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
initialization
During page initialization, controls on the page are available and each control's UniqueID
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 handling
If the request is a postback, any event handlers are called.
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 ItemCreated (DataList, DetailsView, SiteMapPath, DataGrid, FormView, and Repeater controls)
Use this event to manipulate content that is not dependent on data binding. For example, at run time, you might programmatically add formatting to a header or footer row in a GridView control.
RowDataBound (GridView only) or ItemDataBound (DataList, SiteMapPath, DataGrid, and Repeater controls)
When this event occurs, data is available in the row or item, so you can format data or set the FilterExpression property on child data source controls for displaying related data within the 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 initialization
During page initialization, controls on the page are available and each control's UniqueID 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 handling
If the request is a postback, any event handlers are called.
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 ItemCreated (DataList, DetailsView, SiteMapPath, DataGrid, FormView, Repeater, and
ListView controls)
Use this event to manipulate content that is not dependent on data binding. For example, at run time, you might programmatically add formatting to a header or footer row in a
GridView control.
RowDataBound (GridView only) or ItemDataBound (DataList, SiteMapPath, DataGrid, Repeater, and ListView controls)
When this event occurs, data is available in the row or item, so you can format data or set the FilterExpression property on child data source controls for displaying related data within the 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.