Sitecore WebAPI – Hooking into the route setup

Setting up routes in MVC and WebAPI is pretty straightforward in Sitecore provided that its done in the correct pipeline. When I first started attempting to add routes, I quickly discovered that doing this via the Global ASAX wasn’t reliable. The reason for this is that the routes are setup in the initialise pipeline.

Fortunately Sitecore has this process mapped out in the the config file so all I needed to do is swap out the DefaultRouteMapper that comes out of the box. Lets look at the entry in Sitecore:

<setting name="Sitecore.Services.RouteMapper" value="NAMESPACE.CustomRouteMapper, ASSEMBLY_NAME" />

Note that I’ve already swapped out the details of where to find the class. This configuration file that has this setting is in App_Config/Include and is called Sitecore.Services.Client.config.

Next lets check out the DefaultMapper itself. Now what’s interesting here is that it has a constructor that takes in some additional information. Unfortunately, if you copy this setup you’ll be in for trouble as Sitecore loads your mapper type via a factory and it expects a default constructor. Only the built in Sitecore mapper has special treatment.

Also – if your mapper throws an error on load, Sitecore will also load its own mapper. So if you’re not seeing what you expect, be liberal with your log entries to make sure everything is ok!

Here’s a sample setup. Notice that I have to implement IMapRoutes and that I manually load the route base (or web api prefix). I’ve left a lot of exception handling and testing out so you get to see the bare bones of it. You can see I’m still calling the original mapper so that I get the Item Service and Entity Service routes setup too. Feel free to experiment with your own requirements:

public class CustomRouteMapper : IMapRoutes
        public DefaultRouteMapper DefaultRouteMapper { get; set; }

        public CustomRouteMapper()

        private void Initialise()
            // This would let me change the setting name if I wished and still have a default
            String routeBase = Settings.GetSetting(
            // Note we are passing in the route mapper route base from the config file
            this.DefaultRouteMapper = new DefaultRouteMapper(routeBase);
            // Perform any other initialisation here...

        public void MapRoutes(HttpConfiguration config)
            // Do your own routes here!
        public void MapRoutes(RouteCollection routes)

I have my own production version of this class that lets me add additional routes to the system, with their own prefixes loaded from new settings. Though there is a gotcha that you can’t have a fully static route defined. It must have {controller} present else, as of update-2, it will not resolve.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s