GitHub repository now available

Introduction

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.

Background

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 ASP.net MVC controllers.

New PerformanceTest.aspx added to main demo project

New ASP.net 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:

http://localhost/mydemohandler.ashx?help

Calling the Handler from the browser URL

Using this handles is very simple:

Create a new Generic Handler

Clear everything inside the handler class

Inherit from my Handler class

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).

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:

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! https://www.codeproject.com/script/Forums/Images/smiley_smile.gif " />
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