How to register custom ASP.NET MVC routes in Sitecore

  • Description

    Sitecore allows custom ASP.NET MVC routes to be used on a Sitecore site.

    However, improper adding of such routes may lead to different problems with using Sitecore Client, such as broken dialogs, non-functioning buttons, etc.

    For example, this may be the result of defining custom routes in the Global.asax file, causing conflicts with a number of default routes defined by Sitecore and used for Sitecore Client functionality.

    This article provides guidance for adding custom routes so they do not conflict with the routes used by Sitecore Client.

    You can also find more information about ASP.NET Routing in the following article:
    https://msdn.microsoft.com/en-us/library/cc668201.aspx

  • Follow the steps below to define custom ASP.NET MVC routes in a way that does not conflict with the default Sitecore routes.

    1. Create a custom processor for the initialize pipeline and define custom route in the Process method similar to the following:
      public class RegisterCustomRoute
      {
        public virtual void Process(PipelineArgs args)
        {
          RouteTable.Routes.MapRoute("CustomRoute", "some/route/{controller}/{action}/{id}");
        }
      }
    2. Add this processor to the initialize pipeline right before the Sitecore InitializeRoutes processor. You can do this with the help of the configuration patch file in the following way:
      <?xml version="1.0" encoding="utf-8"?>
      <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
           <sitecore>
                <pipelines>
                     <initialize>
                          <processor type="MyNamespace.RegisterCustomRoute, MyAssembly" patch:before="processor[@type='Sitecore.Mvc.Pipelines.Loader.InitializeRoutes, Sitecore.Mvc']" />
                     </initialize>
                </pipelines>
           </sitecore>
      </configuration>
      Important: ensure your custom configuration patch file is applied as the last patch to Sitecore configuration.
      You can do this by placing the patch file into a subfolder of the /App_Config/Include directory. The name of the subfolder must be the last one alphabetically related to other subfolders (such as Z_CustomConfigs).

    Corresponding examples can be downloaded from here:

    1. CustomRoute.cs
    2. CustomRouteConfiguration.config

Applies to:

CMS 7.0+

August 14, 2015
December 16, 2016

Keywords: 

  • CMS,
  • MVC