Kentico CMS 7.0 Developer's Guide

URL rewriting

URL rewriting

Previous topic Next topic Mail us feedback on this topic!  

URL rewriting

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

Kentico CMS uses a system of friendly URL addresses, which allows you to use URLs like:

instead of something like:


These friendly or "smart" URLs provide several benefits:

They are easy to remember and easy to write into the browser address bar.

They are friendly towards search engines (for more information about this topic, please see the Search engine optimization chapter).

They represent a path that shows users where they are located on the website.

Users can easily send the URL of a document to their friends and they will see the same page with the specific document.


Every document has its own unique URL. If the website's content is available in multiple languages, individual language versions of documents are recognized based on a combination of their alias path and a URL with a culture‑specific format, or through completely custom URL paths (if specified).


URL processing


The steps below explain how the system handles a request for the following URL:


1. After receiving the incoming request, the system looks up the website based on the domain name in the URL (either via the main site domain name or its domain aliases). If none of the currently running websites match the domain name, the ~/cmsmessages/invalidwebsite.aspx page is displayed instead. If the requested domain name contains a port number that is not found, the corresponding domain name without a port number is checked.


2. The request in this example specifies a standard URL path, so it is passed on to the URL rewriting engine. The most prioritized way to identify standard documents is their Document URL path, so the engine first attempts to find a document with a URL path set to /products/kentico-cms.


3. If there is no document with a matching URL path, the rewriting engine then tries to look up a document with an Alias path equal to /products/kentico-cms (the alias path is generated according to the document's position in the content tree).


4. If a document cannot be found under the given URL or alias path, the system tries to find a document with a Document alias set to /products/kentico-cms.


5. In case all of the steps described above fail to find a matching document for the requested URL, the system does not process the request. The web server returns a 404 HTTP status code and displays the Page not found error page configured for the website.


6. When the requested document is identified, the URL rewriting engine checks the type of its page template and handles it accordingly:


If the page is managed by the Portal engine, the ~/cmspages/portaltemplate.aspx system page is called, which renders the final output according to the web parts placed on the given template and the content of the particular document.

For ASPX page templates, the appropriate template (web form) used to display the document is loaded using a specific internal URL, for example: /products.aspx?aliaspath=/products/kentico-cms

In the case of MVC templates, the system passes on the request to the MVC controller and action specified for the given template, which then renders the page using an appropriate MVC view.


The flow of the entire process for all types of URL requests is shown in the following diagram:







Processing of MVC and Routing URL patterns


If the URL of an incoming request matches the MVC or Routing pattern defined for a page, the pattern always has priority over other types of URL processing (even if it is set through a document alias).


The rewriting engine evaluates MVC and Routing patterns in the same step of the process, so precedence between the two is not defined. You should always avoid collisions between MVC and Routing patterns.


Excluding URLs from the rewriting engine


If your website uses custom physical pages (.aspx, .html or any other file types) stored inside the web project directory, you can avoid unnecessary processing by excluding their URLs from the Kentico CMS rewriting engine. When a visitor requests an excluded URL, the system skips all URL rewriting actions and attempts to access the specified page directly. This leads to better performance when loading the given pages and also allows you to prepare your own custom URL rewriting logic.


To disable rewriting for specific pages, go to Site Manager -> Settings -> URLs and SEO and enter the matching URL paths into the Excluded URLs setting.


Use URL paths without the website's domain name or virtual directory.

The paths must always start with a forward slash (/), without the virtual path designator (~).

Entering a value excludes all URLs that start with the given path, including sub-directories and all possible extensions.

You can enter multiple URLs separated by semicolons (;).


Sample values:


/Custom.aspx - excludes the ~/Custom.aspx page stored directly under the website's root.

/Custom - excludes all pages whose URL path starts with /Custom, for example: ~/Custom.aspx, ~/Custom2.aspx, ~/Custom/Page.htm

/Custom;/Static - excludes all pages whose URL path starts with /Custom or /Static.







Be careful not to exclude the URLs used by the regular documents in the website's content tree. With URL rewriting disabled for a URL, the system always tries to load a matching physical page, which leads to a page not found error in most cases.