Using Custom Routes in Umbraco

So if you come from a .Net MVC background and you’re building an Umbraco project, one of the first things you’re going to want to do is add your own custom routes. You create your custom controller and add your custom route into the RouteConfig.cs file and hit F5. Then you get an error saying that the route you just added can’t be found and you start to doubt everything you thought you knew (again).

This is because Umbraco hijacks the routing process of your once-familiar MVC project and puts its own routing engine in place! To add custom routing back in to your Umbraco project you have to do a bit of tinkering under the bonnet (like the bonnet of a car, not a bonnet you wear on your head).

I recently used my own controller and custom route on a project when I wanted to make AJAX calls from the site back to the server. I followed the instructions in the Umbraco documentation which got me 95% of the way, but there were a couple of gotchas. So here’s how you do it, gotchas included!

Step 1 – Set up your controller. This is the bit you already know and love – no change here. For my project the actions I added to my controller were JsonResult actions, as I was using Ajax, but you can use any controller actions. Here’s the basic code from my controller:

public class AjaxController : Controller
    public JsonResult OpinionPollPost(OpinionPollModel model)
      RegisterVote(model, Response);

      var modelToReturn = GeneratePoll(model.Id, Request, model.Token);

      return Json(modelToReturn);

Step 2. Add the controller path to umbracoReservedPaths appSettings key in your web.config file. Any path added to this list will be ignored by Umbraco’s routing engine. My controller was called AjaxController, so I added “~/ajax/” to the umbracoReservedPaths list:

<add key=”umbracoReservedPaths” value=”~/umbraco,~/install/,~/ajax/” />

Step 3. Change your global.asax.cs to inherit from UmbracoApplication. Open up your global.asax.cs file and change this line:

public class MvcApplication : System.Web.HttpApplication

to this:

public class MvcApplication : UmbracoApplication

Step 4. Change your global.asax to inherit from your application. This was the big gotcha that caught me out and I had to do quite a bit of searching to find it! Open up your Global.asax file (right click on it and “View Markup”) and change this line:

<%@ Application Codebehind=”Global.asax.cs” Inherits=”Umbraco.Web.UmbracoApplication” Language=”C#” %>

to this:

<%@ Application Codebehind=”Global.asax.cs” Inherits=”MyProject.MvcApplication” Language=”C#” %>

where “MyProject” in this example is the base namespace of your project.

Step 5. Remove the default custom route from RouteConfig.cs – this is another gotcha! If you don’t remove this route, MVC will try and route every request and your website will show en empty page which may be a nice clean design, but not very functional!

Step 6. Register your custom route in the RegisterRoutes method of your RouteConfig.cs. You have to do this for each route you want use:

  name: “Ajax”,
  url: “Ajax/OpinionPollPost”,
  defaults: new { controller = “Ajax”, action = “OpinionPollPost” }

Step 7. Finally you need to add an OnApplicationStarted override method to global.asax.cs. This will allow you to add your application to read the RegisterRoutes method in your RouteConfig.cs file when it starts, and add the custom route you just set up into your application:

protected override void OnApplicationStarted(object sender, EventArgs e)
    base.OnApplicationStarted(sender, e);

Now you just need to build and run your application, and you will be able to access your custom routes and controllers and make even more awesome Umbraco websites!

Tagged with: , ,