Introduction to HTTP Handlers
An ASP.NET HTTP handler is the process (frequently referred to as the "endpoint") that runs in response to a request made to an ASP.NET Web application. The most common handler is an ASP.NET page handler that processes .aspx files. When users request an .aspx file, the request is processed by the page via the page handler.
The ASP.NET page handler is only one type of handler. ASP.NET comes with several other built-in handlers such as the Web service handler for .asmx files.
You can create custom HTTP handlers when you want special handling that you can identify using file name extensions in your application. For example, the following scenarios would be good uses of custom HTTP handlers:
RSS feeds To create an RSS feed for a site, you can create a handler that emits RSS-formatted XML. You can then bind the .rss extension (for example) in your application to the custom handler. When users send a request to your site that ends in .rss, ASP.NET will call your handler to process the request.
Image server If you want your Web application to serve images in a variety of sizes, you can write a custom handler to resize images and then send them back to the user as the handler's response.
HTTP handlers have access to the application context, including the requesting user's identity (if known), application state, and session information. When an HTTP handler is requested, ASP.NET calls the ProcessRequest method on the appropriate handler. The handler's ProcessRequest method creates a response, which is sent back to the requesting browser. As with any page request, the response goes through any HTTP modules that have subscribed to events that occur after the handler has run. For more information about the processing of Web server requests, see ASP.NET Application Life Cycle Overview.
An HTTP handler can be either synchronous or asynchronous. A synchronous handler does not return until it finishes processing the HTTP request for which it is called. An asynchronous handler runs a process independently of sending a response to the user. Asynchronous handlers are useful when you need to start an application process that might be lengthy and the user does not need to wait until it finishes before getting a response from the server.
Built-in HTTP Handlers in ASP.NET
ASP.NET maps HTTP requests to HTTP handlers based on a file name extension. Each HTTP handler enables processing of individual HTTP URLs or groups of URL extensions within an application. ASP.NET includes several built-in HTTP handlers, as listed in the following table.
| Handler | Description |
|---|---|
ASP.NET Page Handler (*.aspx) |
The default HTTP handler for all ASP.NET pages. |
Web service handler (*.asmx) |
The default HTTP handler for Web service pages created using ASP.NET. |
ASP.NET user control handler (*.ascx) |
The default HTTP handler for all ASP.NET user control pages. |
Trace handler (trace.axd) |
A handler that displays current page trace information. For details, see How to: View ASP.NET Trace Information with the Trace Viewer. |
Creating a Custom HTTP Handler
To create a custom HTTP handler, you create a class that implements the IHttpHandler interface to create a synchronous handler or the IHttpAsyncHandler to create an asynchronous handler. Both handler interfaces require you to implement the IsReusable property and the ProcessRequest method. The IsReusable property specifies whether the IHttpHandlerFactory object (the object that actually calls the appropriate handler) can place your handlers in a pool and reuse them to increase performance, or whether it must create new instances every time the handler is needed. The ProcessRequest method is responsible for actually processing the individual HTTP requests.
Creating a File Name Extension
When you create a class file as your HTTP handler, you can have your handler respond to any file name extension that is not already mapped in IIS and in ASP.NET. For example, if you are creating an HTTP handler for generating an RSS feed, you can map your handler to the extension .rss. In order for ASP.NET to know which handler to use for your custom file name extension, the extension of the handler's class file must be mapped in IIS to ASP.NET, and in your application to your custom handler.
By default, ASP.NET maps the file name extension .ashx for custom HTTP handlers, in the same way that it maps the .aspx extension to the ASP.NET page handler. Therefore, if you create an HTTP handler class with the file name extension .ashx, the handler is automatically registered with IIS and ASP.NET.
If you want to create a custom file name extension for your handler, you must explicitly register the extension with IIS and ASP.NET. The advantage of not using the .ashx file name extension is that your handler is then reusable for different extension mappings. For example, in one application your custom handler might respond to requests that end in .rss, and in another application it might respond to requests that end in .feed. As another example, your handler might be mapped to both file name extensions in the same application, but might create different responses based on the extension.
Asynchronous HTTP Handlers
Asynchronous HTTP handlers allow you to start an external process, such as a method call to a remote server, and then continue the processing of the handler without waiting for the external process to finish. During the processing of an asynchronous HTTP handler, ASP.NET places the thread that would ordinarily be used for the external process back into the thread pool until the handler receives a callback from the external process. This can prevent thread blocking and greatly improve performance, because only a limited number of threads can be executed at once. If a number of users request synchronous HTTP handlers that rely on external processes, the operating system can quickly run out of threads because many threads are blocked and waiting for an external process.
When you create an asynchronous handler, in addition to implementing the IHttpAsyncHandler interface, you must implement the BeginProcessRequest to initiate an asynchronous call for processing individual HTTP requests. You must also implement the EndProcessRequest method to run cleanup code when the process ends.
Custom IHttpHandlerFactory Classes
The IHttpHandlerFactory class receives requests and is responsible for forwarding a request to an appropriate HTTP handler. You can create a custom HTTP handler factory by creating a class that implements the IHttpHandlerFactory interface. Creating a custom handler factory can allow finer control over the processing of an HTTP request by creating different handlers based on run-time conditions. For example, with a custom HTTP handler factory, you can instantiate one HTTP handler for a file type if the HTTP request method is PUT, and another if the method is GET.
See Also
Tasks
How to: Create Synchronous HTTP Handlers
How to: Create an Asynchronous HTTP Handler
How to: Create HTTP Handler Factories