Yugeen Klimenko
Jun 30, 2011
(3 votes)

How EPiServer URL Rewriting works.

It is known that EPiServer transforms the urls in both directions – internal and external. For example when you type in your browser “http:// YourEpiSite / Default” this address is transformed into its internal form  inside EPiServer –   http:// YourEpiSite / Default.aspx?id=3&epslanguage=se . Anyway you will continue to observe the http:// YourEpiSite / Default  in the address field.

From the other side if EpiServer  comes upon a reference somewhere in your .aspx page template –  like …<a href=’http:// YourEpiSite / en / Default.aspx?id=3’ \>, – then this address would be transformed into its external form:

http:// YourEpiSite / Default .

Two main principles are at the heart of those transformatiions: modifying the HttpContext address and filtering the HttpResponse via streaming. Let us look on these techologies.

To Internal Direction.

One can change the URL addressed via HttpContext. That is if you address  the http://…./Default.aspx page but you provide your  Application_BeginRequest handler with the following code :

HttpContext context = HttpContext.Current;

context.RewritePath (“~/WebForm.aspx), -

then the WebForm.aspx content would be displayed in browser while the http://…./Default.aspx being displayed in the browser address field.

This technique is used in EPiServer URL Rewriting infrastructure. It relies upon two main items :

1) UrlRewriteModule, i.e. http module implementing the IHttpModule interface;

2) FriendlyUrlRewriteProvider – the “working horse" class which really performs converting the URL in both directions itself.

This is the correspondent class diagram :


The core of the process consists in that UrlRewriteModule being the ASP.NET HttpModule performs its Init function in which it sets the HttpApplication.BeginRequest to its own BeginRequestEventHandler. As a result when the request takes place code in BeginRequestEventHandler makes a call to the HttpUrlRewriteToInternal method. The latter one prepares the query parameters namely page id and language identificator. These parameters are passed to the HttpContext.RewritePath method. This is the “magic” place itself where the redirection takes place.

The sequence diagram is



To External Direction.

If you want to put neccessary corrections into the whole http response content  (f.e. to turn every letter in uppercase or trim the spces between the words) you should:

1) declare new class inherited from Stream, f.e.:

public class TrimStream: Stream

2) implement the Write method in it:

public override void Write (byte[] buffer …)


… trim all the spaces ….


3) set it to the http response filter (you can do it in Application_PostRequestHandlerExecute method in Global.asax):

Response.Filter = new TrimStream (Response.Filter);


EPiServer uses the same principle.

For example, you have <a href=’http://YourEpiSite/en/Default.aspx?id=3’ \> in your .aspx page. When displayed in browser url would be transformed into its external form - http://YourEpiSite/Default. This is made via streaming – in the HtmlRewriteStream class object.

The sequence diagram is given below.


1) In UrlRewriteModuleBase.Init PostRequestHandlerExecuteEventHandler is attached:

… Init (HttpApplication application)


application.PostRequestHandlerExecute += new EventHandler(this.PostRequestHandlerExecuteEventHandler);

2) When PostRequest takes place the HtmlRewriteStream object is created in UrlRewriteModule.HtmlAddRewriteToExternalFilter method:

UrlRewriteModule.HtmlAddRewriteToExternalFilter (HttpApplication application)


Stream stream = htmlRewriter.GetRewriteFilter;

application.Context.Response.Filter = stream;


where HtmlRewriteToExternal.GetRewriteFilter() returns the object of HtmlRewriteStream class.

3)  Finally HtmlRewriteStream.Close is triggered and HtmlRewritePipe.RewriteToEnd method is called.


Then HtmlRewritePipe parses the html content looking for the special elements – i.e. those which can contain urls as their attributes values – f.e. a, area, script. etc…, – and transforms urls into their external forms. Transformation itself is made the following way:

1) obtain the PageReference object from the current url via

PermanentLinkUtility.GetPageReference( string url)

2) obtain PageData object from the PageReference object:

PageData pageData = DataFactory.Instance.GetPage(PageReference pageReference, …)

Due to PageData hierarchical structure we can call the Parent.SegmentURLs recursively and combine them into the whole external address: http:\\EpiSite\Level1\Level2\…..


You can exclude the part of your HTML markup from this kind of processing by putting it inside the container with EPiNoRewrite=”True” and id=”idNoRewrite” attributes:

<div EPiNoRewrite=”True” id=”idNoRewrite”>

<a href=’http://YourEpiSite/en/Default.aspx?id=3’ />


Jun 30, 2011


Hans Arne Vartdal
Hans Arne Vartdal Aug 18, 2011 01:27 PM

Regarding the markup for excluding links from rewriting:

The EPiNoRewrite atribute will cause the markup to be invalid. It would be nice if EPiServer could remove the attribute "after use", leaving the link intact but also the html valid.

Please login to comment.
Latest blogs
Content Delivery API – The Case of the Duplicate API Refresh Token

Creating a custom refresh provider to resolve the issues with duplicate tokens in the DXC The post Content Delivery API – The Case of the Duplicate...

David Lewis | Sep 29, 2022 | Syndicated blog

New Optimizely certifications - register for beta testing before November 1st

In January 2023, Optimizely is making updates to the current versions of our certification exams to make sure that each exam covers the necessary...

Jamilia Buzurukova | Sep 28, 2022

Optimizely community meetup - Sept 29 (virtual + Melbourne)

Super excited to be presenting this Thursday the 29th of September at the Optimizely community meetup. For the full details and RSVP's see the...

Ynze | Sep 27, 2022 | Syndicated blog

Preview multiple Visitor Groups directly while browsing your Optimizely site

Visitor groups are great - it's an easy way to add personalization towards market segments to your site. But it does come with it's own set of...

Allan Thraen | Sep 26, 2022 | Syndicated blog

The Report Center is finally back in Optimizely CMS 12

With Episerver.CMS.UI 12.12.0 the Report Center is finally re-introduced in the core product.

Tomas Hensrud Gulla | Sep 26, 2022 | Syndicated blog

Dynamic Route in ASP.NET Core When MapDynamicControllerRoute Does Not Work

Background Creating one of the add-on for Optimizely I had to deal with challenge to register dynamically route for the API controller. Dynamic rou...

valdis | Sep 25, 2022 | Syndicated blog