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
Configured Commerce - Introduction to Long-Term Support (LTS) Releases

First off, for those who have not had a chance to meet me yet, my name is John McCarroll, and I am the Technical Product Manager for the Optimizely...

John McCarroll | Sep 29, 2023

Auto-translate with OpenAI in Optimizely CMS

You can now auto-translate content using your favorite online AI service, inside the old trustworthy Episerver.Labs.LanguageManager!

Tomas Hensrud Gulla | Sep 29, 2023 | Syndicated blog

Vulnerability in CMS 12 shell module configuration

Introduction A potential security vulnerability has been identified in Optimizely CMS 12, triggered by a certain shell module configuration. To be...

Magnus Rahl | Sep 28, 2023

AI-Assistant: The 'Change Tone' Shortcut

The AI-Assistant for Optimizely is constantly evolving, adjusting, and transforming to meet your digital needs, providing a cutting-edge advantage...

Luc Gosso (MVP) | Sep 27, 2023 | Syndicated blog