This article describes how to set pure extension-less URLs without support for .aspx extension. In other words, how to set your KCMS and/or IIS in a way that documents are available without any extension only, not via default .aspx extension as well.
As you may know from our Developer’s guide
, Kentico CMS allows you to configure the system for using custom URL extensions and extension-less URLs. Custom URL extensions let you have the extensions rendered with a different extension other than the default .aspx,
like .html, .php, .xxx
or any other.
So for example, instead of the default http://www.example.com/news.aspx
, you can have URLs ending with .html: http://www.example.com/news.html.
Besides changing the allowed extensions, you may also want to use URLs without any extensions,
for example, http://www.example.com/news
. However, even then, every single page is also accessible via the default .aspx
extension, since it is handled on IIS level. In other words, even though you configured extension-less URLs properly and you only want your pages to be accessible without any extension
, the user can still request a page with .aspx
extension and the URL will contain this extension. This KB article provides a solution on how to bypass it and allow only pure extension-less URLs.
Before we describe two possible solutions, let’s briefly summarize what configuration steps must be taken in order to allow custom extensions/extension-less functionality. There’s no magic within. When using IIS7 or newer, you just need to add and modify a few keys in your web.config
file. In particular, your system.Webserver
section (located at the bottom of the default web.config file) should look like this:
(Red boxes show what was added).
After making these changes, the project is ready and you just need to set allowed extensions in the Site Manager -> Settings -> URLs and SEO
section, using the Friendly URL extensions
property. Particular extensions must be separated by semicolons, e.g. .html;.php;.xxx
. Like we said, .aspx
is handled by default, so if you want to use standard extension-less only (no custom extension is handled), you can set “Friendly URL extensions“ property to „;;.aspx;
“ or keep it blank.
Please note, I have described the most commonly-used configuration only, however you may find other configuration options when reading the whole “Installation and deployment/Additional configuration tasks/Custom URL extensions and extensionless URLs“
chapter in our Developer’s guide).
Ok. Now let’s deal with how to disable the default .aspx
extension, as we want our pages to be only accessible without any extensions. So, when someone tries to open www.example.com/news.aspx
, instead of www.example.com/news
, it should not work. This approach applies to Kentico CMS 5.x
is to disable this “aspx handling” on your IIS level, using the “Handler mapping” option. More info about this IIS-related functionality can be found online
I want to focus on how to handle this via simple API code, for instance:
// Determine, whether current URL contains .aspx extension or not
bool bRedirect = (ValidationHelper.GetString(URLHelper.GetCurrentUrlExtension(), "") ==".aspx") ? true : false;
// if .aspx extension is included
// Remove it and redirect to pure extension-less URL
string sUrl = URLHelper.GetAbsoluteUrl(URLHelper.CurrentURL);
sUrl = sUrl.Replace(".aspx", "");
The important question is where to place the code? Let me make a short side note - if you are a little familiar with ASP.NET applications, you may be thinking about the global.asax
file, or the /App_Code/Application/CMSAppBase.cs
file, which substitutes global.asax functionality from previous KCMS versions and contains code for responding to application-level events raised by ASP.NET, or by HttpModules
. You might be thinking about the CMSBeginRequest method. However, none of these are suitable for our situation
, as the file above handles all requests, even for GetResource.ashx, getfile, getmetafile
scripts and possibly other requests. So even though this would work, performance would be very poor. Anyway, I mentioned this file as it may be useful in some other scenarios, so it is good to know about it.
Place the code above in the code-behind (OnPreRender
event) of CMSPages/PortalTemplate.aspx
page, which serves as physical master page for all Portal engine pages and is used for every page.
For ASPX templates you can use this code in the code-behind of your physical master page file, for instance project folder/CMSTemplates/CorporateSiteAspx/Root.master.
– since version 6.0
, you can achieve the same result with less of work. KCMS 6.0 brings a new setting called the “Redirect document to main extension”. If enabled, URLs will be redirected to a corresponding URL with the current main extension if their extension is different. The main extension is the first one specified in the Friendly URL extension
field. So, in KCMS 6.0 you can achieve the same goal using this setting together with the „Allow permanent (301) redirection“ property.