As of version 4.0 ASP.NET natively supports routing via the now built-in System.Web.Routing namespace. Routing features are automatically integrated into the HtttpRuntime via a few custom interfaces. New Web Forms Routing Support In ASP.NET 4.0 there are a host of improvements including routing support baked into Web Forms via a RouteData property available on the Page class and RouteCollection.MapPageRoute() route handler that makes it easy
to route
to Web forms.
To map ASP.NET Page routes is as simple as setting up the routes with MapPageRoute:protected void Application_Start(object sender, EventArgs e)
{
RegisterRoutes(RouteTable.Routes);
}
void RegisterRoutes(RouteCollection routes)
{
routes.MapPageRoute("StockQuote", "StockQuote/{symbol}", "StockQuote.aspx");
routes.MapPageRoute("StockQuotes", "StockQuotes/{symbolList}", "StockQuotes.aspx");
}
and then accessing the route data in the page you can then use the new Page class RouteData property
to retrieve the dynamic route data information:public partial class StockQuote1 : System.Web.UI.Page
{
protected StockQuote Quote = null;
protected void Page_Load(object sender, EventArgs e)
{
string symbol = RouteData.Values["symbol"] as string;
StockServer server = new StockServer();
Quote = server.GetStockQuote(symbol);
// display stock data in Page View
}
}
Simple, quick and doesn’t require much explanation. If you’re using WebForms most of your routing needs should be served just fine by this simple mechanism. Kudos
to the ASP.NET team for putting this in the box and making it easy!
How Routing Works
To handle Routing in ASP.NET involves these steps:
Registering Routes
Creating a custom RouteHandler
to retrieve an HttpHandler
Attaching RouteData
to your HttpHandler
Picking up Route Information in your Request code
Registering routes makes ASP.NET aware of the Routes you want
to handle via the static RouteTable.Routes collection. You basically add routes
to this collection
to let ASP.NET know which URL patterns it should watch for. You typically hook up routes off a RegisterRoutes method that fires in Application_Start as I did in the example above
to ensure routes are added only once when the application first starts up. When you
create a route, you pass in a RouteHandler instance which ASP.NET caches and reuses as routes are matched.
Once registered ASP.NET monitors the routes and if a match is found just prior
to the HttpHandler instantiation, ASP.NET uses the RouteHandler registered for the route and calls GetHandler() on it
to retrieve an HttpHandler instance. The RouteHandler.GetHandler() method is responsible for creating an instance of an HttpHandler that is
to handle the request and – if necessary –
to assign any additional custom data
to the handler.
At minimum you probably want
to pass the RouteData
to the handler so the handler can identify the request based on the route data available.
To do this you typically add a RouteData property
to your handler and then assign the property from the RouteHandlers request context. This is essentially
how Page.RouteData comes into being and this approach should work well for any custom handler implementation that requires RouteData.
It’s a shame that ASP.NET doesn’t have a top level intrinsic object that’s accessible off the HttpContext object
to provide route data more generically, but since RouteData is directly tied
to HttpHandlers and not all handlers support it it might cause some confusion of when it’s actually available. Bottom line is that if you want
to hold on
to RouteData you have
to assign it
to a custom property of the handler or else pass it
to the handler via Context.Items[] object that can be retrieved on an as needed basis.
It’s important
to understand that routing is hooked up via RouteHandlers that are responsible for loading HttpHandler instances. RouteHandlers are invoked for every request that matches a route and through this RouteHandler instance the Handler gains access
to the current RouteData. Because of this logic it’s important
to understand that Routing is really tied
to HttpHandlers and not available prior
to handler instantiation, which is pretty late in the HttpRuntime’s request pipeline. IOW, Routing works with Handlers but not with earlier in the pipeline within Modules.
Specifically ASP.NET calls RouteHandler.GetHandler() from the PostResolveRequestCache HttpRuntime pipeline event. Here’s the call stack at the beginning of the GetHandler() call:
which fires just before handler resolution.
Non-Page Routing – You need
to build custom RouteHandlers
If you need
to route
to a custom Http Handler or other non-Page (and non-MVC) endpoint in the HttpRuntime, there is no generic mapping support available. You need
to create a custom RouteHandler that can manage creating an instance of an HttpHandler that is fired in response
to a routed request. Depending on what you are doing this process can be simple or fairly involved as your code is responsible based on the route data provided which handler
to instantiate, and more importantly
how to pass the route data on
to the Handler.
Luckily creating a RouteHandler is easy by implementing the IRouteHandler interface which has only a single GetHttpHandler(RequestContext context) method. In this method you can pick up the requestContext.RouteData, instantiate the HttpHandler of choice, and assign the RouteData
to it. Then pass back the handler and you’re done.Here’s a simple example of GetHttpHandler() method that
dynamically creates a handler based on a passed in Handler type./// <summary>
/// Retrieves an Http Handler based on the type specified in the constructor
/// </summary>
/// <param name="requestContext"></param>
/// <returns></returns>
IHttpHandler IRouteHandler.GetHttpHandler(RequestContext requestContext)
{
IHttpHandler handler = Activator.CreateInstance(CallbackHandlerType) as IHttpHandler;
// If we're dealing with a Callback Handler
// pass the RouteData for this route
to the Handler
if (handler is CallbackHandler)
((CallbackHandler)handler).RouteData = requestContext.RouteData;
return handler;
}
Note that this code checks for a specific type of handler and if it matches assigns the RouteData
to this handler. This is optional but quite a common scenario if you want
to work with RouteData.
If the handler you need
to instantiate isn’t under your control but you still need
to pass RouteData
to Handler code, an alternative is
to pass the RouteData via the HttpContext.Items collection:IHttpHandler IRouteHandler.GetHttpHandler(RequestContext requestContext)
{
IHttpHandler handler = Activator.CreateInstance(CallbackHandlerType) as IHttpHandler;
requestContext.HttpContext.Items["RouteData"] = requestContext.RouteData;
return handler;
}
The code in the handler implementation can then pick up the RouteData from the context collection as needed:RouteData routeData = HttpContext.Current.Items["RouteData"] as RouteData
This isn’t as clean as having an explicit RouteData property, but it does have the advantage that the route data is visible anywhere in the Handler’s code chain. It’s definitely preferable
to create a custom property on your handler, but the Context work-around works in a pinch when you don’t’ own the handler code and have dynamic code executing as part of the handler execution.
An Example of a Custom RouteHandler: Attribute Based Route Implementation
In this post I’m going
to discuss a custom routine implementation I built for my CallbackHandler class in the West Wind Web & Ajax Toolkit. CallbackHandler can be very easily used for creating AJAX, REST and POX requests following RPC style method mapping. You can pass parameters via URL query string, POST data or raw data structures, and you can retrieve results as JSON, XML or raw string/binary data. It’s a quick and easy way
to build service interfaces with no fuss.
As a quick review here’s
how CallbackHandler works:
You
create an Http Handler that derives from CallbackHandler
You implement methods that have a [CallbackMethod] Attribute
and that’s it. Here’s an example of an CallbackHandler implementation in an ashx.cs based handler:// RestService.ashx.cs
public class RestService : CallbackHandler
{
[CallbackMethod]
public StockQuote GetStockQuote(string symbol)
{
StockServer server = new StockServer();
return server.GetStockQuote(symbol);
}
[CallbackMethod]
public StockQuote[] GetStockQuotes(string symbolList)
{
StockServer server = new StockServer();
string[] symbols = symbolList.Split(new char[2] { ',',';' },StringSplitOptions.RemoveEmptyEntries);
return server.GetStockQuotes(symbols);
}
}
CallbackHandler makes it super easy
to create a method on the server, pass data
to it via POST, QueryString or raw JSON/XML data, and then retrieve the results easily back in various formats. This works wonderful and I’ve used these tools in many projects for myself and with clients. But one thing missing has been the ability
to create clean URLs.
Typical URLs looked like this:
http://www.west-wind.com/WestwindWebToolkit/samples/Rest/StockService.ashx?Method=GetStockQuote&symbol=msfthttp://www.west-wind.com/WestwindWebToolkit/samples/Rest/StockService.ashx?Method=GetStockQuotes&symbolList=msft,intc,gld,slw,mwe&format=xml
which works and is clear enough, but also clearly very ugly. It would be much nicer if URLs could look like this:
http://www.west-wind.com//WestwindWebtoolkit/Samples/StockQuote/msfthttp://www.west-wind.com/WestwindWebtoolkit/Samples/StockQuotes/msft,intc,gld,slw?format=xml
(the Virtual Root in this sample is WestWindWebToolkit/Samples and StockQuote/{symbol} is the route)(If you use FireFox try using the JSONView plug-in make it easier
to view JSON content)
So, taking a clue from the WCF REST tools that use RouteUrls I set out
to create a way
to specify RouteUrls for each of the endpoints. The change made basically allows changing the above to:
[CallbackMethod(RouteUrl="RestService/StockQuote/{symbol}")]
public StockQuote GetStockQuote(string symbol)
{
StockServer server = new StockServer();
return server.GetStockQuote(symbol);
}
[CallbackMethod(RouteUrl = "RestService/StockQuotes/{symbolList}")]
public StockQuote[] GetStockQuotes(string symbolList)
{
StockServer server = new StockServer();
string[] symbols = symbolList.Split(new char[2] { ',',';' },StringSplitOptions.RemoveEmptyEntries);
return server.GetStockQuotes(symbols);
}
where a RouteUrl is specified as part of the Callback attribute. And with the changes made with RouteUrls I can now get URLs like the second set shown earlier.
So
how does that work? Let’s find out…
How to Create Custom Routes
As mentioned earlier Routing is made up of several steps:
Creating a custom RouteHandler
to create HttpHandler instances
Mapping the actual Routes
to the RouteHandler
Retrieving the RouteData and actually doing something useful with it in the HttpHandler
In the CallbackHandler routing example above this works out
to something like this:
Create a custom RouteHandler that includes a property
to track the method
to call
Set up the routes using Reflection against the class Looking for any RouteUrls in the CallbackMethod attribute
Add a RouteData property
to the CallbackHandler so we can access the RouteData in the code of the handler
Creating a Custom Route Handler
To make the above work I created a custom RouteHandler class that includes the actual IRouteHandler implementation as well as a generic and static method
to automatically register all routes marked with the [CallbackMethod(RouteUrl="…")] attribute.
Here’s the code:/// <summary>
/// Route handler that can
create instances of CallbackHandler derived
/// callback classes. The route handler tracks the method name and
/// creates an instance of the service in a predictable manner
/// </summary>
/// <typeparam name="TCallbackHandler">CallbackHandler type</typeparam>
public class CallbackHandlerRouteHandler : IRouteHandler
{
/// <summary>
/// Method name that is
to be called on this route.
/// Set by the automatically generated RegisterRoutes
/// invokation.
/// </summary>
public string MethodName { get; set; }
/// <summary>
/// The type of the handler we're going
to instantiate.
/// Needed so we can semi-generically instantiate the
/// handler and call the method on it.
/// </summary>
public Type CallbackHandlerType { get; set; }
/// <summary>
/// Constructor
to pass in the two required components we
/// need
to create an instance of our handler.
/// </summary>
/// <param name="methodName"></param>
/// <param name="callbackHandlerType"></param>
public CallbackHandlerRouteHandler(string methodName, Type callbackHandlerType)
{
MethodName = methodName;
CallbackHandlerType = callbackHandlerType;
}
/// <summary>
/// Retrieves an Http Handler based on the type specified in the constructor
/// </summary>
/// <param name="requestContext"></param>
/// <returns></returns>
IHttpHandler IRouteHandler.GetHttpHandler(RequestContext requestContext)
{
IHttpHandler handler = Activator.CreateInstance(CallbackHandlerType) as IHttpHandler;
// If we're dealing with a Callback Handler
// pass the RouteData for this route
to the Handler
if (handler is CallbackHandler)
((CallbackHandler)handler).RouteData = requestContext.RouteData;
return handler;
}
/// <summary>
/// Generic method
to register all routes from a CallbackHandler
/// that have RouteUrls defined on the [CallbackMethod] attribute
/// </summary>
/// <typeparam name="TCallbackHandler">CallbackHandler Type</typeparam>
/// <param name="routes"></param>
public static void RegisterRoutes<TCallbackHandler>(RouteCollection routes)
{
// find all methods
var methods = typeof(TCallbackHandler).GetMethods(BindingFlags.Instance | BindingFlags.Public);
foreach (var method in methods)
{
var attrs = method.GetCustomAttributes(typeof(CallbackMethodAttribute), false);
if (attrs.Length < 1)
continue;
CallbackMethodAttribute attr = attrs[0] as CallbackMethodAttribute;
if (string.IsNullOrEmpty(attr.RouteUrl))
continue;
// Add the route
routes.Add(method.Name,
new Route(attr.RouteUrl, new CallbackHandlerRouteHandler(method.Name, typeof(TCallbackHandler))));
}
}
}
The RouteHandler implements IRouteHandler, and its responsibility via the GetHandler method is
to create an HttpHandler based on the route data.
When ASP.NET calls GetHandler it passes a requestContext parameter which includes a requestContext.RouteData property. This parameter holds the current request’s route data as well as an instance of the current RouteHandler. If you look at GetHttpHandler() you can see that the code creates an instance of the handler we are interested in and then sets the RouteData property on the handler. This is
how you can pass the current request’s RouteData
to the handler.
The RouteData object also has a RouteData.RouteHandler property that is also available
to the Handler later, which is useful in order
to get additional information about the current route. In our case here the RouteHandler includes a MethodName property that identifies the method
to execute in the handler since that value no longer comes from the URL so we need
to figure out the method name some other way. The method name is mapped explicitly when the RouteHandler is created and here the static method that auto-registers all CallbackMethods with RouteUrls sets the method name when it creates the routes while reflecting over the methods (more on this in a minute). The important point here is that you can attach additional properties
to the RouteHandler and you can then later access the RouteHandler and its properties later in the Handler
to pick up these custom values. This is a crucial feature in that the RouteHandler serves in passing additional context
to the handler so it knows what actions
to perform.
The automatic route registration is handled by the static RegisterRoutes<TCallbackHandler> method. This method is generic and totally reusable for any CallbackHandler type handler.
To register a CallbackHandler and any RouteUrls it has defined you simple use code like this in Application_Start (or other application startup code):protected void Application_Start(object sender, EventArgs e)
{
// Register Routes for RestService
CallbackHandlerRouteHandler.RegisterRoutes<RestService>(RouteTable.Routes);
}
If you have multiple CallbackHandler style services you can make multiple calls
to RegisterRoutes for each of the service types. RegisterRoutes internally uses reflection
to run through all the methods of the Handler, looking for CallbackMethod attributes and whether a RouteUrl is specified. If it is a new instance of a CallbackHandlerRouteHandler is created and the name of the method and the type are set.
routes.Add(method.Name, new Route(attr.RouteUrl, new CallbackHandlerRouteHandler(method.Name, typeof(TCallbackHandler) )) );
While the routing with CallbackHandlerRouteHandler is set up automatically for all methods that use the RouteUrl attribute, you can also use code
to hook up those routes manually and skip using the attribute. The code for this is straightforward and just requires that you manually map each individual route
to each method you want a routed:
protected void Application_Start(objectsender, EventArgs e){ RegisterRoutes(RouteTable.Routes);}void RegisterRoutes(RouteCollection routes)
{ routes.Add("StockQuote Route",new Route("StockQuote/{symbol}", new CallbackHandlerRouteHandler("GetStockQuote",typeof(RestService) ) ) ); routes.Add("StockQuotes Route",new Route("StockQuotes/{symbolList}", new CallbackHandlerRouteHandler("GetStockQuotes",typeof(RestService) ) ) );}I think it’s clearly easier
to have CallbackHandlerRouteHandler.RegisterRoutes() do this automatically for you based on RouteUrl attributes, but some people have a real aversion
to attaching logic via attributes. Just realize that the option
to manually
create your routes is available as well.
Using the RouteData in the Handler
A RouteHandler’s responsibility is
to create an HttpHandler and as mentioned earlier, natively IHttpHandler doesn’t have any support for RouteData. In order
to utilize RouteData in your handler code you have
to pass the RouteData
to the handler.
In my CallbackHandlerRouteHandler when it creates the HttpHandler instance it creates the instance and then assigns the custom RouteData property on the handler:IHttpHandler handler = Activator.CreateInstance(CallbackHandlerType) as IHttpHandler;
if (handler is CallbackHandler)
((CallbackHandler)handler).RouteData = requestContext.RouteData;
return handler;
Again this only works if you actually add a RouteData property
to your handler explicitly as I did in my CallbackHandler implementation:/// <summary>
/// Optionally store RouteData on this handler
/// so we can access it internally
/// </summary>
public RouteData RouteData {get; set; }
and the RouteHandler needs
to set it when it creates the handler instance.
Once you have the route data in your handler you can access Route Keys and Values and also the RouteHandler. Since my RouteHandler has a custom property for the MethodName
to retrieve it from within the handler I can do something like this now
to retrieve the MethodName (this example is actually not in the handler but target is an instance pass
to the processor): // check for Route Data method name
if (target is CallbackHandler)
{
var routeData = ((CallbackHandler)target).RouteData;
if (routeData != null)
methodToCall = ((CallbackHandlerRouteHandler)routeData.RouteHandler).MethodName;
}
When I need
to access the dynamic values in the route ( symbol in StockQuote/{symbol}) I can retrieve it easily with the Values collection (RouteData.Values["symbol"]). In my CallbackHandler processing logic I’m basically looking for matching parameter names
to Route parameters:
// look for parameters in the routeif(routeData != null){ string parmString = routeData.Values[parameter.Name] as string; adjustedParms[parmCounter] = ReflectionUtils.StringToTypedValue(parmString, parameter.ParameterType);}
And with that we’ve come full circle. We’ve created a custom RouteHandler() that passes the RouteData
to the handler it creates. We’ve registered our routes
to use the RouteHandler, and we’ve utilized the route data in our handler.
For completeness sake here’s the routine that executes a method call based on the parameters passed in and one of the options is
to retrieve the inbound parameters off RouteData (as well as from POST data or QueryString parameters):internal object ExecuteMethod(string method, object target, string[] parameters, CallbackMethodParameterType paramType, ref CallbackMethodAttribute callbackMethodAttribute)
{
HttpRequest Request = HttpContext.Current.Request;
object Result = null;
// Stores parsed parameters (from string JSON or QUeryString Values)
object[] adjustedParms = null;
Type PageType = target.GetType();
MethodInfo MI = PageType.GetMethod(method, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
if (MI == null)
throw new InvalidOperationException("Invalid Server Method.");
object[] methods = MI.GetCustomAttributes(typeof(CallbackMethodAttribute), false);
if (methods.Length < 1)
throw new InvalidOperationException("Server method is not accessible due
to missing CallbackMethod attribute");
if (callbackMethodAttribute != null)
callbackMethodAttribute = methods[0] as CallbackMethodAttribute;
ParameterInfo[] parms = MI.GetParameters();
JSONSerializer serializer = new JSONSerializer();
RouteData routeData = null;
if (target is CallbackHandler)
routeData = ((CallbackHandler)target).RouteData;
int parmCounter = 0;
adjustedParms = new object[parms.Length];
foreach (ParameterInfo parameter in parms)
{
// Retrieve parameters out of QueryString or POST buffer
if (parameters == null)
{
// look for parameters in the route
if (routeData != null)
{
string parmString = routeData.Values[parameter.Name] as string;
adjustedParms[parmCounter] = ReflectionUtils.StringToTypedValue(parmString, parameter.ParameterType);
}
// GET parameter are parsed as plain string values - no JSON encoding
else if (HttpContext.Current.Request.HttpMethod == "GET")
{
// Look up the parameter by name
string parmString = Request.QueryString[parameter.Name];
adjustedParms[parmCounter] = ReflectionUtils.StringToTypedValue(parmString, parameter.ParameterType);
}
// POST parameters are treated as methodParameters that are JSON encoded
else
if (paramType == CallbackMethodParameterType.Json)
//string newVariable = methodParameters.GetValue(parmCounter) as string;
adjustedParms[parmCounter] = serializer.Deserialize(Request.Params["parm" + (parmCounter + 1).ToString()], parameter.ParameterType);
else
adjustedParms[parmCounter] = SerializationUtils.DeSerializeObject(
Request.Params["parm" + (parmCounter + 1).ToString()],
parameter.ParameterType);
}
else
if (paramType == CallbackMethodParameterType.Json)
adjustedParms[parmCounter] = serializer.Deserialize(parameters[parmCounter], parameter.ParameterType);
else
adjustedParms[parmCounter] = SerializationUtils.DeSerializeObject(parameters[parmCounter], parameter.ParameterType);
parmCounter++;
}
Result = MI.Invoke(target, adjustedParms);
return Result;
}
The code basically uses Reflection
to loop through all the parameters available on the method and tries
to assign the parameters from RouteData, QueryString or POST variables. The parameters are converted into their appropriate types and then used
to eventually make a Reflection based method call.
What’s sweet is that the RouteData retrieval is just another option for dealing with the inbound data in this scenario and it adds exactly two lines of code plus the code
to retrieve the MethodName I showed previously – a seriously low impact addition that adds a lot of extra value
to this endpoint callback processing implementation.
Debugging your Routes
If you
create a lot of routes it’s easy
to run into Route conflicts where multiple routes have the same path and overlap with each other. This can be difficult
to debug especially if you are using automatically generated routes like the routes created by CallbackHandlerRouteHandler.RegisterRoutes.
Luckily there’s a tool that can help you out with this nicely. Phill Haack created a RouteDebugging tool you can download and add
to your project. The easiest way
to do this is
to grab and add this
to your project is
to use NuGet (Add Library Package from your Project’s Reference Nodes):
which adds a RouteDebug assembly
to your project.
Once installed you can easily debug your routes with this simple line of code which needs
to be installed at application startup:protected void Application_Start(object sender, EventArgs e)
{
CallbackHandlerRouteHandler.RegisterRoutes<StockService>(RouteTable.Routes);
// Debug your routes
RouteDebug.RouteDebugger.RewriteRoutesForTesting(RouteTable.Routes);
}
Any routed URL then displays something like this:
The screen shows you your current route data and all the routes that are mapped along with a flag that displays which route was actually matched. This is useful – if you have any overlap of routes you will be able
to see which routes are triggered – the first one in the sequence wins.
This tool has saved my ass on a few occasions – and with NuGet now it’s easy
to add it
to your project in a few seconds and then remove it when you’re done.
Routing Around
Custom routing seems slightly complicated on first blush due
to its disconnected components of RouteHandler, route registration and mapping of custom handlers. But once you understand the relationship between a RouteHandler, the RouteData and
how to pass it
to a handler, utilizing of Routing becomes a lot easier as you can easily pass context from the registration
to the RouteHandler and through
to the HttpHandler. The most important thing
to understand when building custom routing solutions is
to figure out
how to map URLs in such a way that the handler can figure out all the pieces it needs
to process the request. This can be via URL routing parameters and as I did in my example by passing additional context information as part of the RouteHandler instance that provides the proper execution context. In my case this ‘context’ was the method name, but it could be an actual static value like an enum identifying an operation or category in an application. Basically user supplied data comes in through the url and static application internal data can be passed via RouteHandler property values.
Routing can make your application URLs easier
to read by non-techie types regardless of whether you’re building Service type or REST applications, or full on Web interfaces. Routing in ASP.NET 4.0 makes it possible
to create just about any extensionless URLs you can dream up and custom RouteHanmdler
References
Sample ProjectIncludes the sample CallbackHandler service discussed here along with compiled versionsof the Westwind.Web and Westwind.Utilities assemblies. (requires .NET 4.0/VS 2010)
West Wind Web Toolkit includes full implementation of CallbackHandler and the Routing Handler
West Wind Web Toolkit Source CodeContains the full source code
to the Westwind.Web and Westwind.Utilities assemblies usedin these samples. Includes the source described in the post.(Latest build in the Subversion Repository)
CallbackHandler Source(Relevant code
to this article tree in Westwind.Web assembly)
JSONView FireFoxPluginA simple FireFox Plugin
to easily view JSON data natively in FireFox.For IE you can use a registry hack
to display JSON as raw text.© Rick Strahl, West Wind Technologies, 2005-2011Posted in ASP.NET AJAX HTTP
