Episerver Commerce routing internals, part 1

Routing is important for any sites, and it’s even more important for a Commerce site – it can help driven sales. People nowadays search for everything, and ranking higher in the search results yield much better chance of your products being purchased. There are two routing systems in Episerver Commerce (as always!). The old one is based on SEO URI, has been there since Commerce R1, and the new one, HierarchicalCatalogPartialRouter, which is a partial router, was introduced in Commerce 7.5.

The SEO Uri approach

This approach is based on the SEO Uri, so the link to your product will be in form of http:///yourproduct.aspx. Note that .aspx is the default, but you are free to choose another extension, or even no extension at all. The SEO Uri can be edited in both Commerce Manager and Catalog UI

Those information are stored in CatalogItemSeo for both Nodes and Entries, which each row represents the information of one node or one entry in one language. Note that only the Uri is unique and is used by the system, it’s up to your site implementation to utilize other information such as Title, Description – just follow best SEO practices.

The SEO Uri regeneration
The Uri is unique per language, and if you don’t set it explicitly, the catalog system will automatically
generate them based on the entry/node’s name while still ensure the uniqueness. The default implementation will work like this:

• If the SEO Uri is empty, generate it from the name by replacing any invalid characters, possibly add the language code, and append the .aspx extension.
• If the Uri being saved is unique, save it
• If it is not unique, generate again by adding a random string to the end. (it’s the 8 first characters of a newly created GUID)

This behavior can be overridden by inheriting from Mediachase.Commerce.Catalog.Data.UniqueSeoGenerator, and then register your implementation as the default instance. UniqueSeoGenerator is a simple class and all of its methods and properties are virtual, to override the Uri generation, you can override three following:


protected virtual string UriExtension { get; }
public virtual string GenerateSeoUri(string name, string languageCode, bool includeRandomToken)
protected virtual string GetRandomToken()


Usually, you will have the Uri set by some other external systems, or manually, but there are still cases when the Uri:s are automatically generated. There are several tips to make the Uri generation more effective:

• Change the default UriExtension. It was kept “.aspx” for the backward compatibility, but I don’t think that kind of extension is popular anymore.
• Make sure your entries, especially your variations, to have unique names. This will generate better Seo URIs – no matter how you override GetRandomToken – having some artificial random string append to your Uri can’t be a good thing.
• When you made your Uri public, stick with it. Nothing worse than a hoping customer sees an 404 error for a product they planned to buy, because the Uri has been changed. Episerver Commerce has no mechanism to detect such changes to redirect customers to the new Uri, so don’t change your Uri:s until absolutely necessary.

How it works

SEO Uri:s are handled by SeoUriRouter, which is an implementation of ISimpleAddressRouteHandler. ISimpleAddressRouteHandler has only one method:

SimpleAddressRouteValues GetRouteValues(string urlSegment, ContentReference routeRoot, SegmentContext segmentContext);


SeoUriRouter implements this, and it will only handle the urlSegment without any slash (/) in between – so /this-can-be-a-seo-uri/ is processed, but /this/cannot/be/a/seo/uri/ is not. It then try to get the content from the seo uri, and if you are wondering, there are methods in ICatalogSystem to do that – GetCatalogEntryByUriDto(string seoUri, string language) and GetCatalogNodeDto(string seoUri, string language). If a matching content to be found, then a SimpleAddressRouteValues value will be returned, indicating this router has processed successfully the urlSegment.
Simple enough, right? However, the design of SeoUriRouter has some limitations: It’s registered by default, and with the routing system, the first router to be able to “catch” the uri wins, so it’s be a challenge if you want to replace the behavior. We’ll look for more detail in the next section.

Shameless plug: This is an excerpt from the book I’m writing, Pro Episerver Commerce, which can be purchased here.