Virtual Developer Workshop: Containerized Development with Docker


The ability to create HTTP handlers is not new to ASP.NET. However, ASP.NET 4.5 makes it easy for you to create asynchronous HTTP handlers with the new async/await keywords and Tasks. This article illustrates how an asynchronous HTTP handler can be created and consumed in an ASP.NET 4.5 web application.

Creating HTTP Handlers in ASP.NET

Traditionally HTTP handlers are classes that implement the IHttpHandler interface. You can also create an asynchronous HTTP handler by implementing the IHttpAsyncHandler interface. Asynchronous HTTP handlers are advantageous in situations where asynchronous processing can improve the overall performance of the application. The IHttpAsyncHandler interface requires you to write methods of the form BeginProcessRequest() and EndProcessRequest() methods. In ASP.NET 4.5 you can use the new async/await keywords and Tasks to achieve the same effect with simplified design.  Under ASP.NET 4.5 you can create a class that inherits from the HttpTaskAsyncHandler class and then override certain methods (as discussed later in this article).

Detailed discussion of async/await keywords and Tasks is beyond the scope of this article. You may read Working with Asynchronous Operations in ASP.NET 4.5 Web Forms for the basic understanding of these concepts.

Sample Asynchronous HTTP Handler

To understand how asynchronous HTTP handlers are created in ASP.NET 4.5, let's develop a simple example. Suppose that you have an ASP.NET web site with one or more web forms. On each of the web forms you wish to display advertisements. The advertisements are not statically placed on the web forms. They reside in a SQL Server database and at runtime you need to fetch them so as to render them onto the pages. Additionally, you also need to track the impressions each advertisement is receiving.

The following figure shows the Entity Framework for the sample database tables Ads and AdStats.

The Entity Framework

The Entity Framework

As you can see the Ads table has only two columns, viz. Id and Markup. The Markup column contains the HTML markup of the advertisement. The AdStats table stores information about ad impressions such as UserIP, UserAgent and TargetUrl.

To display an advertisement on web forms and to track the ad statistics you will create an asynchronous HTTP handler. In this specific scenario, creating an asynchronous HTTP handler rather than a synchronous one is beneficial because the ads are independent of the web form content and can be processed asynchronously. To create the asynchronous HTTP handler add a new Generic Handler (*.ashx) to the web application.

Add a new Generic Handler

Add a new Generic Handler

Change the default definition of the Generic Handler class as shown below:

<%@ WebHandler Language="C#" Class="MyHandler" %>

using System;
using System.Web;
using System.Threading.Tasks;
using System.Linq;

public class MyHandler : HttpTaskAsyncHandler

As shown above the MyHandler class inherits from the HttpTaskAsyncHandler base class. The HttpTaskAsyncHandler class is provided by ASP.NET 4.5 and you need to override its ProcessRequestAsync() method. The following code shows a sample implementation of the overridden method:

public override async Task ProcessRequestAsync(HttpContext context)
    string userIP = context.Request["REMOTE_ADDR"];
    string targetUrl = context.Request.QueryString["url"];
    string userAgent = context.Request.Browser.Browser;

    string adMarkup = await GetAdAsync();
    context.Response.Write("document.write('" + adMarkup + "');");
    string result = await SetStatsAsync(targetUrl, userIP, userAgent);

 As you can see the ProcessRequestAsync() method is an asynchronous method. Inside ProcessRequestAsync(), details about the web form requesting an advertisement are captured. These details include the user's IP address, the URL of the target web form and the requesting browser. The code then gets the details of advertisement from the database by calling the GetAdAsync() method. It also saves the ad statistics to the database by calling the SetStatsAsync() method.

The GetAdAsync() and SetStatsAsync() methods are quite similar in nature and are shown below.

private async Task<string> GetAdAsync()
    var func = Task<string>.Factory.StartNew(() => GetAdFromDb());
    await func;
    return func.Result;
private async Task<string> SetStatsAsync(string targeturl, string userip, string useragent)
    var func = Task<string>.Factory.StartNew(() => SaveStatsToDb(targeturl,userip,useragent)); 
    await func;
    return func.Result;

Both of these methods start a new Task and run the actual database access code on it using two helper methods: GetAdFromDb() and SaveStatsToDb(). These helper methods are shown below.

private string GetAdFromDb()
    DatabaseEntities db=new DatabaseEntities();
    var data = (from item in db.Ads
                select item).SingleOrDefault();
    return data.Markup;
private string SaveStatsToDb(string targeturl, string userip, string useragent)
    DatabaseEntities db = new DatabaseEntities();
    AdStat stat = new AdStat();
    stat.AdId = 1;
    stat.TargetUrl = targeturl;
    stat.UserIP = userip;
    stat.UserAgent = useragent;
    return "Data saved successfully!";

The GetAdFromDb() method simply retrieves the first record from the Ads table. In a real world situation you will have some ad selection logic here. It then returns the ad Markup to the caller. Notice that the GetAdFromDb() method introduces a delay of 5 seconds by calling the Sleep() method. This is done purely for the purpose of testing and you can remove this line once the application is complete. The SaveStatsToDb() method stores the target URL, user's IP and user agent (browser) to the AdStats table.

Using the Sample HTTP Handler in a Web Form

Now that your asynchronous HTTP handler is ready, let's see how it can be used in a web form. Add a web form to the web application and place a <script> tag in it as shown below.

<script type="text/javascript" src="http://localhost:49183/AsyncHTTPModuleHandler/MyHandler.ashx?url=<%= Request.Path%>">

As you can see the <script> tag points to the MyHandler.ashx, the asynchronous HTTP handler you developed in the previous section. It also passes the Request.Path of the current web form in a querystring parameter. This way you are making a call to the asynchronous HTTP handler where the <script> tag is placed.

Before running the web form, add some advertisement data in the Ads table and then run the web form. The following figure shows a sample run of the web form.

Sample run of a web form

Sample run of a web form

As you can see from the above figure the text "Hello World!" is part of the web form whereas the text "This is an advertisement!" is the part of an advertisement and is stored in the database. Also notice that when you run this web form "Hello World!" is displayed immediately and the advertisement is displayed after 5 seconds due to the delay introduced in the code. After running the web form check the database to verify the ad statistics are stored as expected.


ASP.NET 4.5 allows you to create asynchronous HTTP handlers easily. An asynchronous HTTP handler is a class that inherits from the HttpTaskAsyncHandler base class. This article illustrated how an asynchronous HTTP handler can be created and consumed in a web forms application.

Related Articles



  • Html format

    Posted by parwej on 02/09/2013 06:01pm

    Thanks for your article. I was looking same thing but I am facing issue with html string. When I tried to return the html string then getting javascript error on the page and not able to render the same string. Do you have any idea? http://stackoverflow.com/questions/14426501/httptaskasynchandler-and-html-string

  • why do we need await at multiple places

    Posted by RK on 12/20/2012 04:20pm

    Nice article, question on using Await at several places, seems to be redundant.

  • Nice article

    Posted by RK on 12/20/2012 04:19pm

    Nice article to demo the Async Http handler with simple instruct ions. Kudos to Bipin. One question thought, I felt that "await" in this context (string adMarkup = await GetAdAsync();) is redundant as there is async operation ( await func;) done inside the GetAdAsyn() method.

  • Question on the script tag

    Posted by Alex on 11/28/2012 04:56pm

    Thanks for the informative article. I don't quite follow the part about setting the src attribute of a script tag to the url of the Handler. It doesn't appear to render anything in the web form when I run the sample code from your download. I have tried constructing my own version as well with the same results. Am I missing something obvious?

  • You must have javascript enabled in order to post comments.

Leave a Comment
  • Your email address will not be published. All fields are required.

Most Popular Programming Stories

More for Developers

RSS Feeds

Thanks for your registration, follow us on our social networks to keep up-to-date