Friendly URL

Product version:

EPiServer CMS 4.62

Document version:


Document creation date:


Document last saved:



EPiServer CMS support for search engine-friendly URLs has been enhanced and adapted to better support both globalized and monolingual Web sites. This document describes configuration issues concerning the friendly URL functionality.

Table of Contents


Security Issues

Issues when Upgrading to EPiServer CMS 4.61


Handling Post Backs

Page Name in Web Address (URL Segment)


Templates Requiring Customization

Tweaking Friendly URLs  



The EPiServer CMS support for search engine-friendly URLs has been enhanced and adapted to better support both globalized and monolingual Web sites. The improved functionality makes it possible to configure URLs for pages so that they are based on the structure of the Web site, e.g. or The URLs will follow the site's main navigation and breadcrumbs.

Friendly URLs can be configured for the following settings:

  1. Monolingual Web sites with URLs based on manually entered version of page names, e.g.
  2. Globalized Web site with URLs including prefix for the language, e.g. The prefix can be manually changed so that it is possible to change the URL to

Security Issues

Note! When using friendly URLs you may bypass restrictions set up in Internet Information Server (IIS).

You have a friendly URL “” which maps to the actual URL “”.

IIS will only see the friendly URL and then pass the request to the ASP.NET runtime. If you have restrictions (for example IP address restrictions) configured in IIS for the folder “templates”, these restrictions will never be enforced since IIS is unaware that ASP.NET has re-routed the request to a file in the “templates” folder.

If you need to have this kind of restriction enforced by IIS, you can work around this problem by creating virtual directories in IIS with the same name as the friendly URLs and setting the restrictions on these virtual directories as well.

Issues when Upgrading to EPiServer CMS 4.61

The following issues apply when upgrading EPiServer sites before EPiServer 4.60 to 4.62. These issues do not apply when upgrading from EPiServer 4.60 and 4.61 to 4.62.

The friendly URL functionality will not function correctly until the text marked in bold below has been added to web.config.


<add name="FriendlyUrl" type="EPiServer.Util.FriendlyUrlModule, EPiServer" />

<add name="ExternalUrl" type="EPiServer.Util.ExternalUrlModule, EPiServer" />


Note: For performance issues, it is important that the Friendly URL module is placed before the External URL module.

Add the following code to the header section of all the templates used in the site, normally located in /templates/units/header.ascx.

<%@ Register TagPrefix="EPiServer" Namespace="EPiServer.WebControls" Assembly="EPiServer" %>


<episerver:FriendlyUrlRegistration runat="Server" /> 

Friendly URL Requires Enabled JavaScripts

Post back handling will only work when JavaScript is enabled in the Web browser as Friendly URL uses JavaScript to rewrite the action tag in the form.

ASP.NET Development Server

The built-in Web server in .NET 2.0 (ASP.NET development server) does not support friendly URL in the default configuration. In order for this to work, you must have an extension that is mapped to ASP.NET for the URL. For example: 

<add key="EPsFriendlyUrlExtension" value=".aspx" />

Friendly URL and .NET 1.1

The Web control FriendlyUrlRegistration adds a <base href="..."... /> tag to the HTML so that all server-controlled links (example  ~/ ) work for the page.

Bookmarks (anchors) in HTML are limited for friendly URLs in .NET 1.1 in that all coded bookmarks must have a complete URL.

For example, <a href=’#top’ /> must be rewritten to <a href="/EPiServerSample/#top">. This is done most easily with <a href=’<%=EPiServer.Util.FriendlyUrlModule.CurrentUrl %>/#top’ />


The friendly URL functionality is built on each page having a URL Segment property. This generates the friendly URL for a page, together with its parents, up to the start page.

A Normal Friendly URL Request

  1. A Web browser asks for a friendly URL.
    For example, /Inspiration/.
  2. A URL rewrite is done by FriendlyUrlModule to the physical address of the page.
    For example, /templates/Page.aspx?id=71.

A Page Accessed with the Old Links

  1. A Web browser accesses the site with an old link.
    For example, /templates/Page.aspx?id=71.
  2. In the OnInit method in PageBase, a permanent redirect is done to the friendly URL.
    For example, /Inspiration/.
  3. A URL rewrite is done by FriendlyUrlModule to the physical address of the page.
    For example, /templates/Page.aspx?id=71

Customize Handling of Direct Access to Pages

If you want pages that are accessed with the old syntax of the links to be handled in a different way, override the ValidateFriendlyUrl method on your page.

Handling Post Backs

In order for post backs to work for URLs that end in "/", a final "Post.aspx" is added with a JavaScript that is created by the Web control FriendlyUrlRegistration. If EPsFriendlyUrlExtension is set, map the extension to ASP.NET in Internet Information Services (IIS) for everything to work correctly.

.NET 1.1 Sites

When a page is created, the Web control FriendlyUrlRegistration must be placed on the page. This control adds a JavaScript to the page, which changes the action attribute of the first form post to the page that will handle the post back.

In .NET 1.1 sites, a <base href="..."... /> tag is also added so that all server-controlled links are rendered correctly for the Web page.

.NET 2.0 Sites

When a page is created in a .NET 2.0 site, the client path is set to the post back path and a JavaScript is added to change the post back to go to the friendly URL. The <base href="..."... /> tag is not added to the page.

Friendly URL in Content

All links in EPiServer CMS are stored on the old form and replaced when the content is rendered. This is done internally for the properties of XHTML string and ‘Long String’ by adding a sub Web control of the type LongStringFriendlyUrlRender. This replaces:

  • links with a friendly URL link in <a> and <area> tags;
  • anchors with a relative reference to the current page with an anchor relative to the Web site's root, e.g. #top is replaced with /EPiServerSample/test/#top.

Page Name in Web Address (URL Segment)

The URL segment is stored on the page and can be edited in Edit mode under the Advanced Information tab. The "Page name in Web address" field sets the URL segment for that page. All pages have a URL segment that creates the Friendly URL together with the page's parent.

For example, in the following structure the visitor will be able to access page 2 with the friendly URL /start_page/page1/page2.

<start page>         with URL segment start_page
      <page 1>               with URL segment page1
            <page 2>               with URL segment page2

Friendly URL and Globalization

Each language branch has its own URL segment that is placed at the beginning of the friendly URL when globalization is enabled, e.g. /en/start_page.

When pages that support globalization, but do not have a starting language branch, are accessed, a normal fallback is done according to the fallback settings for that page.

Automatic Creation of URL Segments

When a page is created or changed, a page validation event is triggered and executes the event handler OnValidateURLSegment. This creates a new empty URL segment for pages, by calling the public virtual method EPiServer.Global.CreatePageURLSegment.

To replace the functionality for automatic creation of URL segments, override the function CreatePageURLSegment in your Global.asax.cs file.

Rebuilding URL Segments

Use the tool available in Admin mode to rebuild URL segments for your Web site. The tool, which is found under Rebuild Web Addresses in Admin mode, rebuilds all URL segments that do not have a value (or for pages with the "Rebuild all pages name in Web addresses" check box selected) by invoking the method Global.CreatePageURLSegment or its overridden functionality for all pages.


This tool will rebuild the URLs to the pages, which in turn makes links based on the old URL segments invalid. This means that if the page is bookmarked or indexed by a search engine with the old URL segment, it will stop working.


PageData.LinkURL has been changed so that links are generated at runtime if EnableAutomaticURL is enabled. This will generate a friendly URL, if friendly URL is turned on. LinkURL generates a friendly URL by accessing DetermineAutomaticURL with the page's language selection. To generate a link to the page for another language selection, use DetermineAutomaticURL with the branch language to link to.

PageData.StaticLinkURL is still the static link URL with the normal syntax.

URL Query String

In EPiServer.PageBase the query parameters id and epslanguage are removed from the URL, because it is already in the URL.

Templates Requiring Customization

The following templates require customization in order to work with the friendly URL functionality in EPiServer 4.61.


<a href="#" onclick="javascript:readPage();"

<a href="javascript:void(0);" onclick="readPage();"

News Groups (Only for .NET 2.0)





<td background="../images/bar_background.gif"

<td background="<%=Configuration.RootDir%>images/bar_background.gif"



Response.Write(Configuration.RootDir + "templates/NewsGroupIntro.aspx");

File Listing

<a href="#" onclick="<%#Container.ToggleOpenScript%>;"

<a href="javascript:<%#Container.ToggleOpenScript%>;"

Tweaking Friendly URLs

One cool thing you can do with Friendly URLs is to change the default extension of pages in EPiServer. The standard look of URLs in EPiServer 4.60 and later is that it will have no extension at all, so the format would in this case be something similar to

It is possible to change the format of this URL, making it look like a Web site coded in, for example, Cold Fusion.

     1.   Register the extension .cfm in the IIS Manager. Make sure that you copy the settings for the .aspx extension when adding the new extension in IIS. 

     2.   Add the following line to the web.config file to make EPiServer use this new extension as the default extension.

          <add key="EPsFriendlyUrlExtension" value=".cfm" />

     3.   When saving the web.config file all pages will have this look.


Friendly URL writes log messages to the loggers EPiServer.PageBase and EPiServer.Util.FriendlyUrlModule on the debug level. To configure log4net to generate log messages you must add these loggers to your EPiServerLog.config file.

For example, add the following to the EPiServerLog.config file:

<logger name="EPiServer.PageBase"><level value="DEBUG" /></logger>

<logger name="EPiServer.Util.FriendlyUrlModule"><level value="DEBUG" /></logger>

You will receive the following log messages:

  • 17.1.2 FriendlyUrlModule rewrites path from='/EPiServerSample/Inspiration/Statistics/' to='/EPiServerSample/templates/Page.aspx?id=81'
    This is the most common message; it makes a redirect from a friendly URL to the actual address for this request.
  • 17.1.1 FriendlyUrlModule makes a permanent redirect from='/no/Kurs2/Courses_and_Workshops/Lar_god_nettskriving/Post.aspx' to='/no/Kurs2/Courses_and_Workshops/Lar_god_nettskriving/'
    When a posting is done, a permanent redirect to the friendly URL is done.
  • 1.1.4 PageBase makes a permanent redirect to friendly URL from='/templates/RssProvider.aspx?id=3512' to='/en/Common/3512/'
    Access is made directly to the page and a permanent redirect is done to the friendly URL for the page.