The life of an ASP.NET Request introduced HTTPHandlers (among other things) and you found out that everything eventually gets sent to an HTTPHandler (even the Page object) is an HTTPHandler. This article will look at HTTPHandlers in-depth an the creation and use of them, it will also take a look into HTTPHandler files (ASHX files).

Their Purpose in Life

All an HTTPHandler does really is take an HTTPContext object and work out what to do with it. Although that is a very simple analogy of them. The best way to describe it would be with an example -

Usually you associate an HTTPHandler with either a new file type (eg. ".AGASP") or with a .ASHX file. In the pipeline, the Handler is called last and when it is called, the appropriate HTTPHandler is executed. The handler can print information out or analyze information. The HTTPApplication object will call the HTTPHandler to process the request and generate a response.

So, for example, I can associate an HTTPHandler with the .stime extension and get it print out the server time when called.

They differ from HTTPModules because they only have one method, one property and no events -

Public Interface IHTTPHandler Public ReadOnly Property IsReuseable as Boolean Public Sub ProcessRequest(context as HttpContext) End Interface

 

Creating an HTTPHandler is much the same as an HTTPModule -

Imports System Imports System.Web Public Class SampleHandler : Implements IHttpHandler Public Sub ProcessRequest(ByVal context As HttpContext) Implements IHttpHandler.ProcessRequest context.Response.ContentType = "text/xml" context.Response.Write("<time>") context.Response.Write("<GMT>") context.Response.Write(DateTime.Now.Subtract(New TimeSpan(12, 0, 0)).ToString()) context.Response.Write("</GMT>") context.Response.Write("</time>") End Sub Public ReadOnly Property IsReuseable() As Boolean Implements IHttpHandler.IsReusable Get Return True End Get End Property End Class

In web.config -

<httpHandlers> <add verb="*" path="*.gmt" type="HttpModHan.SampleHandler, HttpModHan" /> </httpHandlers>

The verb part is just what you want it to respond to (eg. POST, GET etc.). Path is the specific file or file extension you want it to respond to and Type is still the same - ClassName, Assembly.

IIS Configuration

There is still one last step before it is ready - setting up IIS.

The reason we have to set up IIS is because we specified in web.config to response to *.gmt files and in order for it to do that, the ASP.NET worker process must be sent all requests for *.gmt files and the only way to do that is through IIS.

(Click the images for a larger version)

First in the web or virtual directory properties. Go to the Configuration.

Next, click to add a new mapping.

On this dialog, set the Executable to the aspnet_isapi.dll file in the .NET folder (you can just copy this from another .NET extension).
Then set the Extension to whatever you set in web.config (here it's .gmt)
I unchecked Check that file exists so I wouldn't have to create any new files.

Now that that's complete, load up Mozilla and go to something like - http://localhost/something.gmt. If you also unchecked Check that file exists then you won't have to create any new files in order to browse there.

Now, if all of that web.config stuff was just a bit too much then you don't have to live with it. If you check the IIS mappings tab you will see that there is a file extension - .ashx this extension is the extension for a HTTPHandler File. This takes out all of that lovely web.config stuff and IIS config that you have to do.

For example here is time.ashx -

<%@ WebHandler Class="HttpModHan.SampleHandler" %> Imports System Imports System.Web Namespace HttpHanMod Public Class SampleHandler : Implements IHttpHandler Public Sub ProcessRequest(ByVal context As HttpContext) Implements IHttpHandler.ProcessRequest Dim thetime As DateTime = DateTime.Now.Subtract(New TimeSpan(12, 0, 0)) Dim gmtplus As Double = CInt(context.Request.QueryString("gmtplus")) thetime = thetime.AddHours(gmtplus) context.Response.ContentType = "text/xml" context.Response.Write("<time>") context.Response.Write("<GMT>") context.Response.Write(thetime.ToString()) context.Response.Write("</GMT>") context.Response.Write("</time>") End Sub Public ReadOnly Property IsReuseable() As Boolean Implements IHttpHandler.IsReusable Get Return True End Get End Property End Class End Namespace

Live Demo

You may also notice that if you add ?gmtplus=xxx (where xxx is hours past GMT) it adds it to the answer.

If you check the documentation for ASHX files, you will find nothing on them.

Summary

This article has shown you how to create and use HTTPHandlers, both in Assemblies and in ASHX files. Be sure that there will be more articles on HTTPHandlers (hence the "Getting Started" in the title), but in the mean time check out the Related Articles for more information on this whole ASP.NET Pipeline.