Routing

The EPiServer Commerce routing system extends the EPiServer CMS Routing system to expose catalog content like products, variations and categories using individual URL:s. The actual data sent to the client browser is then compiled by a matching render template. See Commerce rendering templates for more information about rendering. Note that categories also have their own URL and can have their own rendering template, for instance to display a product listing.

The catalog content URL:s come in two different forms:

Hierarchical URL: In the form domain/language/catalog/category/product following the structure of the catalog, for example mysite.com/en/wine/accessories/corkscrew
Simple address / SEO URL: A single segment uniquely identifying a content and the language, for example mysite.com/professional-corkscrew-en.aspx

The SEO URL field has been part of the catalog information since previous versions of EPiServer Commerce, but with the new routing it works the same way as the EPiServer CMS "Simple address" concept, hence you may see both terms used.

Registering routes

To enable routing to catalog content, you need to register the catalog partial router. The recommended way is to do it in an EPiServer.Framework.IInitializableModule using the CatalogRouteHelper.

using System.Web.Routing;
using EPiServer.Framework;
using EPiServer.Commerce.Routing;
using EPiServer.Framework.Initialization;

namespace CodeSamples.EPiServer.Commerce.Catalog
{
    [ModuleDependency(typeof(global::EPiServer.Commerce.Initialization.InitializationModule))]
    public class RegisterRoutingModuleSample : IInitializableModule
    {
        public void Initialize(InitializationEngine context)
        {
            MapRoutes(RouteTable.Routes);
        }

        private static void MapRoutes(RouteCollection routes)
        {
            CatalogRouteHelper.MapDefaultHierarchialRouter(routes, true);
        }

        public void Uninitialize(InitializationEngine context) { /*uninitialize*/}

        public void Preload(string[] parameters) { }
    }
}

Outgoing routes

Outgoing routes are used when rendering links in the template, for example using the Html.ContentLink helper (ASP.NET MVC), the EPiServer.Web.Routing.UrlResolver class or links added to an Xhtml property by an editor. The commerce routes also register an outgoing route, which one depends on the flag passed to CatalogRouteHelper in the initialization:

CatalogRouteHelper.MapDefaultHierarchialRouter(routes, false) will use hierarchical links.
CatalogRouteHelper.MapDefaultHierarchialRouter(routes, true) will use the SEO URL in links.

Working with hierarchical URL:s

Hierarchical URL:s are constructed using the Name in URL property of each content instance in the hierarchy leading to the requested content. The first segment will be the catalog, followed by any categories and subcategories down to the target category, product, variation etc. To determine the language, either a language segment (e.g. "en/") is prepended, or the configured site host mapping is used (see the article Globalization scenarios in the EPiServer CMS SDK for more information about site host mapping).

The value of the Name in URL property is automatically generated from the Name when a new content is created. Because only certain characters are valid in a URL and because the Name in URL needs to be unique among content on the same level in the hierarchy it may not be exactly the same as the Name. Name in URL can of course be edited to take any valid value and does not have to be similar to the Name.

Working with SEO URL:s

SEO URL:s are stored in the SEO URL property and should be unique across all catalogs and languages, which is why only one segment is needed to identify the requested content. It also means that the URL is unaffected by moving the product in the catalog tree, or changing the Name in address of a content somewhere above in the hierarchy.

The value of the SEO URL property is automatically generated from the Name when a new content is created. For additional language versions, the language code is appended to make the SEO URL unique. Because only certain characters are valid in a URL and because the SEO URL needs to be unique across all catalogs, it may not be the same as the Name. By default a .aspx extension is used, but the SEO URL can of course be edited to take any valid value and does not have to be similar to the Name or include any extension.

Registering routes

Outgoing routes

Working with hierarchical URL:s

Working with SEO URL:s

See also