---
title: Routing
slug: cms-11/dev-docs/DRcR-routing
docTags: 
createdAt: 2026-07-22T19:45:22.664Z
---

The Uniform Resource Locator (URL), a web address, is a character string reference to a resource. In most web browsers, the URL is inside an address bar at the top of a web page. URLs carry information from the browser to the server required to enact a desired action. Routing rewrites a URL to make it more user-friendly.

A rewritten URL, known as *Friendly* or *Search Engine Friendly*  (SEF) URL, provides shorter, more relevant-looking web page links. By default, the routing system in Optimizely Content Management System (CMS) uses `System.Web.Routing`, with specific segments added for language, node, and a partial route. Routing is automatically handled based on content type. The language segment will set the language of the page, and the node segment will set the page reference from the URL.

The technique adds a degree of separation between the files used to generate a web page and the presented URL. The partial route lets you set the routed data to something other than `PageData`, for example, catalog content in an Optimizely Customized Commerce solution. Such a partial route is usually registered in an [initialization module](docId\:XJ30Tl-UFL1PWVIQHlxtr).

### Default routes

CMS registers several routes by default.

- Shell modules have routes registered to support routing to gadgets.
- CMS also registers several routes by default.
  - CMS registers routes in `GlobalBase` during initialization; you can override the `RegisterRoutes` method in `Global.asax.cs` to customize the registered routes or add additional routes.
  - The class `EPiServer.Global` also exposes the `RoutesRegistrating` and `RoutesRegistered` events, where you can perform custom registrations.
  - The namespace `EPiServer.Web.Routing` contains some extension methods for the class `RouteCollection`. You can use those extension methods to register a site route or a partial router. See [Partial routing](docId\:ISxt3RwGBKKj16bwPRKpj).
- Among the default routes, there is one set up for each:
  - routing a **simple address**.
  - routing for **sites** (can be several sites in a multi-site environment).
  - routing **pages/content** from the root (that is, pages or content not under any start page).
- The “ordinary” MVC route “/” also is registered to support partial requests through `Html.RenderAction`. However, you cannot directly browse to those routes.

CMS registers the routes in the order above. The order is important because the first route checks whether the URL matches its route and routes the page through that route if it does. If the URL does not match the first route, the next route gets its chance.

### MVC and Web Forms

You can route a URL through the MVC and Web Forms routing framework. The routing first locates the content routed to from the URL. After it locates the content, the framework queries the `EPiServer.Web.TemplateResolver` instance for the template used to render the request. The template can be an MVC controller or a Web Form. Depending on whether the template is a Web Form or an MVC controller, a suitable `httpHandler` is set to handle the request. If no content matches the URL or if no template matches the routed content, a 404 (not found) is returned.

## Extend routing

You can extend routing in several levels. Events are exposed during incoming routing and the creation of outgoing URLs to customize routing. You also can modify the default URL pattern for content routing to handle a part of the URL. You can also add your routes.

### Events

The `EPiServer.Web.Routing.IContentRouteEvents` interface exposes the events `RoutingContent` and `RoutedContent`, which are raised during incoming routing. It raises `RoutingContent` events before executing the default routing implementation, and the content that matches the request is set in an event handler. It raises `RoutedContent` events after executing the default routing, and the routed content is replaced in an event handler. During outgoing URL generation, the `CreatingVirtualPath` and `CreatedVirtualPath` events are raised where event handlers can modify the generated URLs.

### Modify content routes

CMS bases the built-in content routing on a registered URL pattern, where an implementation handles each pattern of an `EPiServer.Web.Routing.Segments.ISegment` interface. You can implement custom ISegment types and register them as part of the content routing.

By default, CMS registers content routing with a pattern of **///**.

- **** – In the URL, an optional part might state the language.
- **** – Used to specify the CMS page or content in the URL, it will follow the site structure and contain page names after the start page on the site, down to the requested page. For example, in the structure *start > news > firstNews*, the URL part handled by **** part would be */news/firstNews*.
- **** – If something is remaining in the URL after the page or content routing, any registered `EPiServer.Web.Routing.IPartialRouter` that matches the type of located page gets a chance to route the remainder of the URL.
- **** – The remaining part is checked for a valid action for an MVC controller. If the requested action is *myAction* (MVC), the whole URL is `http://mySite/news/firstNews/myAction`.

The `MapContentRoute` extension method takes the route's name, the URL pattern, and default values as arguments. Each part in the URL pattern for content routing, for example, **** or **,** is handled by an implementation of `EPiServer.Web.Routing.Segments.ISegment`. You can extend content routing with `ISegment` implementations.

The following example shows how to add a route:

```csharp
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Routing;

using EPiServer.Web.Routing;

namespace CodeSamples {
  /// <summary>
  /// Code sample class containing cref examples on how to register a route
  /// </summary>
  public static class RegisterCustomRouteExample {
    /// <summary>
    /// Register a route which makes 'shop/' in the beginning of the url valid.
    /// This method should only be called when the site starts, for example in 'Application_Start' (Global.asax).
    /// </summary>
    public static void RegisterShopRoute() {
      // Register a route, which will make all url:s with 'shop/' before page names route to the page last in the list of page names
      // For example, http://mySite/shop/News/ListOfNews/FirstNews/ will route to the 'FirstNews' page. 

      RouteTable.Routes.MapContentRoute(name: "customRoute",
        url: "shop/{node}/{partial}/{action}",
        defaults: new {
          action = "index"
        },
        contentRootResolver: (s) => s.StartPage);
    }
  }
}
```

### Implement a custom route

You can also add custom route implementations. The order of the routes is important because the first route handling a request prevents the following routes from routing the request. So, when registering custom routes, decide whether it should be registered before or after the default routes.

### URL length limitation

ASP.NET has multiple checks that validate the length of the URL and the path in Windows. Under normal circumstances, the default settings are enough, but to support long URLs, add the following configuration:

```xml
<httpRuntime maxUrlLength="1024" relaxedUrlToFileSystemMapping="true"/>
```