Click here to Skip to main content
15,920,603 members
Articles / Web Development / ASP.NET

ASP.NET Advanced Generic Handler ASHX

Rate me:
Please Sign up or sign in to vote.
4.74/5 (49 votes)
9 Jun 2013CPOL5 min read 327.4K   10.2K   138   60
Take your Generic Handlers to the next level...

GitHub repository now available

I will also be updating the project progress on CP but now you can also fork it on GitHub


In ASP.NET, we have something that is usually overlooked that is called Generic Handlers. I see a lot o f people using pages to process AJAX requests when we can use this much less expensive endpoint. This is an completely worked out Generic Handler that truly knows how to handle your http (AJAX and not) requests. 


For a long time I used plain Generic Handlers (ASHX files) to handle my AJAX requests but it felt stupid and painful. I mean, the functionality was there but the whole process of handling the requests wasn't straight forward. So I made a list of the things I would like to have and now it's already a lot more than that.

  • NEW v2.5! 
    • Fully supports collections as requests arguments 
      • Nested collections are fully supported
      • Native and Complex item types supported
    • Improved support for complex types as method arguments
    • Improved HTTP verbs filter 
    • New HTTP verbs filter attributes (DELETE and PUT) 
    • Improved controller Help (more to come soon) 
    • Improved performance (still working to further improve this) 
      • Performance improvements are always a work in progress. From the simple tests I've done this controller already performs at the same level as the MVC controllers.
    • New PerformanceTest.aspx added to main demo project
    • New MVC project created for performance comparison with MVC controllers
      • This project isn't added to the solution. Add if you want to use it.
    • Small refactoring and improvements all around
  • NEW v2.0!
    • OnMethodInvoke and AfterMethodInvoke virtual methods
      • These allow the possibility to intersect the execution before and after the method call  
    • public void SetResponseContentType(ResponseContentTypes value)
      • Easy way to set the response content type from the enum
    • Specify supported HTTP verbs by handler and by method
      • Now we can specify if a method only supports certain HTTP verbs by simply decorating the method with the related Attribute
    • Default methods for main HTTP verbs (GET, POST, PUT and DELETE)
      • If no method is passed the handler will call the method related with the Request HTTP verb. 
      • These methods can me overrided to implement your logic.
    • Response serialization improvements  (JSON and XML)
      • You can now use the returntype parameter on the Request to specify how you want your response data without having to modify your code. 
      • The default is JSON but you can also pass XML or HTML.
      • The default serialization can be disabled on method scope.
    • Performance optimization 
  • v1.1
    • Support for complex objects as method argument
      • Now you can put your custom classes on the handler methods arguments.
      • Automatically hydrates the class and all its nested types!!
  • v1.0
    • Standard way to parse the query string
    • Transparently handle multiple methods within the same handler
    • Support methods with multiple typed arguments, not just strings
    • Support Methods that receive lists as an argument
    • Support passing less arguments than the method is expecting (like optional parameters)
    • Transparently reply either POSTs or GETs
    • Support default object serialization to JSON but still let me override it on each method
    • Return application/json by default but still let me override it on each method
    • Support jQuery $.ajax request
    • Support request by query string (URL right on the browser)
    • A way to visualize the methods the handler supports (like webservices do)
    • Extensible 

Using the code  

I'm working to improve this documentation.
Until then, all you need to know is on the Default.aspx of the demo project.

List the Handler methods 

I've provided a very basic way of listing the methods the Handler exposes. This is specially useful to test if the handler is working correctly (like on webservices). Do do so just append ?help at the end of the handler URL:


Calling the Handler from the browser URL

Using this handles is very simple:

  1. Create a new Generic Handler
  2. Clear everything inside the handler class
  3. Inherit from my Handler class
  4. DONE! Now you only need to add your methods.

Let's create a very simple example that receives a name and returns a string (see on the project).

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using App.Utilities.Web.Handlers;

namespace CodeProject.GenericHandler
	public class MyFirstHandler : BaseHandler
		// I don't bother specifying the return type, it'll be serialized anyway
		public object GreetMe(string name) 
			return string.Format("Hello {0}!", name);

To call this method through a URL use:


AJAX Request using jQuery

If you want to use jQuery AJAX method you just need to know the object the handler is expecting to get. On the data property of the $.ajax request you must pass something like:

{ method: 'The method you want to call', args: { the arguments to pass } }
Be aware that everything is case sensitive!
	url: 'MyFirstHandler.ashx',
	type: 'GET',
	data: { method: 'GreetMe', args: { name: 'AlexCode'} },
	success: function (data) {

Writing a method that returns HTML

Like I said on my intention points above, I need to have some methods that return whatever I want like HTML, XML, images, files, etc... The default behavior of the handler is to return JSON so, by method, we need to explicitly say that we want to handle things our way. For that just use these lines anywhere within the method:

SkipContentTypeEvaluation = true;	
SkipDefaultSerialization = true;

// you can specify the response content type as follows
context.Response.ContentType = "text/html";
Lets see an example on how we could write a method on the handler that returns HTML:
public object GiveMeSomeHTML(string text)
	StringBuilder sb = new StringBuilder();
	sb.Append("<head><title>My Handler!</title></head>");
This is a HTML page returned from the Handler
The text passed was: " + text + "

	context.Response.ContentType = "text/html";
	SkipContentTypeEvaluation = true;
	SkipDefaultSerialization = true;

	return sb.ToString();

Optional Parameters and nullable types

All parameters in the methods are optional. If they're not passed their default value is assigned. Also all parameters can be nullable. In this case the default value will be null.

Support for complex types

Say you have a JSON object and a class server side that maps it. Hydrating this class server side is a pain. Usually we pass each property as an argument of the method on the Handler, instantiate a new instance of the class and set the properties one by on... a pain right? NO MORE! This handler now supports automatic class instance creation and property set. Something I like to call Object Hydratation! Smile | <img src= " /> And there's more! If this class have properties that also expose other custom classes they will be hydrated too!! Just make sure all classes have a public default constructorr

// Now you can have method like this
public object SendPersonData(Person person)
return person.Name;

// your ajax call object would be something like
data: { 
     method: 'SendPersonData', 
          person: { Name: 'Alex' } 

Please have a look at the attached code sample for more examples. 

Points of Interest

I can say that this handler already saved me a good amount of development and maintenance hours. Currently all my AJAX requests point to a method on an handler like this.


  • v2.5 - The so awaited support for collections is here! Full details above!
  • v2.0 - New features and performance enhancements
  • v1.1 - Added support for complex arguments  
  • v1.0 - The first wide open version  
  • This is a work in progress, I keep improving it regularly.

I have no doubt that you'll try to use this in scenarios I haven't predicted. Please send me your requests and desires, I'll do my best to implement them. 


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Switzerland Switzerland
Senior IT Consultant working in Switzerland as Senior Software Engineer.

Find more at on my blog.

Comments and Discussions

gitcue1-May-12 2:36
gitcue1-May-12 2:36 
AlexCode3-May-12 4:26
professionalAlexCode3-May-12 4:26 
QuestionHandler vs WCF Pin
Nitin S26-Mar-12 19:41
professionalNitin S26-Mar-12 19:41 
AnswerRe: Handler vs WCF PinPopular
AlexCode27-Mar-12 0:05
professionalAlexCode27-Mar-12 0:05 
GeneralRe: Handler vs WCF Pin
Nitin S27-Mar-12 2:03
professionalNitin S27-Mar-12 2:03 
GeneralRe: Handler vs WCF PinPopular
Andre Sanches (alvs)3-Apr-12 5:15
Andre Sanches (alvs)3-Apr-12 5:15 
GeneralRe: Handler vs WCF Pin
AlexCode3-Apr-12 9:10
professionalAlexCode3-Apr-12 9:10 
GeneralRe: Handler vs WCF Pin
Andre Sanches (alvs)3-Apr-12 17:41
Andre Sanches (alvs)3-Apr-12 17:41 
Yes I understand and a year back I would definitely use your approach, in fact I have used something very similar to handle simple tasks like auto complete textboxes, I just thought I should mention new technologies for people who stumble across your article now like I did.

I have to disagree with your opinion on Web API though, there's a lot of awesome stuff you seem to be missing out on - it is actually very much capable of seamlessly parsing json objects into POCO classes and also returning json from these classes with little to no effort from the developer. There's a lecture Scott Guthrie gave on these new technologies that is really worth watching, you can download it from his blog @[^]

I'm looking forward to see v1.2 of your code - I'm currently working on a proprietary client-server communication interface that should allow for serializing generic lists with custom types (dictionaries of custom types are a NIGHTMARE to work with using reflection, you'll see Smile | :) )

Good luck!

Edit: oh and be sure to check out Phil Haack and Scott Hanselman' blogs, they also have very interesting posts on Web API
Andre Sanches

"UNIX is friendly, it's just picky about its friends"

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.