Custom and extensionless URLs

✖
Copy to clipboard

You can configure the system to use custom URL extensions and extensionless URLs.

Custom URL extensions allow you to change the default .aspx extension to .html, .asp, .php, or any other value.

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

you can also configure extensionless URLs:

http://www.example.com/news

To use custom URL extensions, take the following steps:

  1. Adjust your web.config or IIS to handle custom extensions
  2. Configure custom URL extensions in the Kentico settings

Configuring IIS to allow custom URL extensions

Note: This procedure only works for IIS 7 sites that use an Application Pool with Managed Pipeline Mode set to Integrated.

  1. Edit your application’s web.config file.

  2. Find the <modules> element inside the system.webServer section directly under the web.config root (i.e. not under a specific <location> element).

  3. Set the runAllManagedModulesForAllRequests attribute to true for the opening <modules> tag:

    


 <system.webServer>
   ...
   <modules runAllManagedModulesForAllRequests="true">
     <remove name="WebDAVModule"/>
     <remove name="XHtmlModule"/>
     <remove name="CMSApplicationModule"/>
     <remove name="UrlRoutingModule-4.0"/>
     ...
   </modules>
 ...
 </system.webServer>

With this modification in your web.config, configure the extensions in the Kentico administration interface. You can also perform additional configuration as described below.

It is recommended to configure a custom Page-not-found (404) error page when using custom URL extensions, otherwise a blank page may be displayed in some browsers if a user attempts to access a non‑existing resource.

  1. In the Kentico administration interface, open the Settings application.
  2. Select the Content category.
  3. Enter the URL of the appropriate document or aspx page into the Page not found URL setting, for example: ~/CMSMessages/PageNotFound.aspx.

Please read Creating custom error handling pages to learn more.

Alternatively, you can add a <httpErrors> element into the system.webServer section of your web.config file according to the following:




<httpErrors existingResponse="Auto" errorMode="Custom">
    <clear/>
    <error statusCode="404" responseMode="ExecuteURL" path="/<Virtual_Directory>/CMSMessages/PageNotFound.aspx" />
</httpErrors>

Replace the <Virtual_Directory> string in the value of the path attribute of the <error> element with the name of the virtual directory where you run Kentico.

You can also add the following key to the AppSettings section of the web.config file, which ensures that URLs remain the same even after postback.




<add key="CMSUseExtensionOnPostback" value="false" />

If you are using trailing slashes (enabled through the Use URLs with trailing slash setting in Settings -> URLs and SEO), you can use the following extra key to have only extensionless URLs ending with the trailing slash. URLs ending with an extension are rendered without the slash when the key is used.




<add key="CMSUseTrailingSlashOnlyForExtensionLess" value="true" />

Using the cmspages/handler404.aspx page (obsolete)

For the purposes of backward compatibility, you can also set error pages by configuring your IIS manually. This approach is required for sites that use an application pool in Classic Managed Pipeline Mode.

  1. Open Start -> Control Panel -> Administrative Tools -> Internet Information Services (IIS) Manager.

  2. Select your website from the tree and open the Error pages section.

  3. Right-click the 404 error and select Edit Feature Settings.

    If you receive a Lock violation message when configuring the following step, proceed to Troubleshooting custom and extensionless URL configuration.

  4. Enter the following values:

    • Path: enter the URL of the cmspages/handler404.aspx page according to your application’s URL.

      • Example: if you run your web project in virtual directory /kentico, you need to enter /kentico/cmspages/handler404.aspx

    • Path type: Execute URL

  5. Click OK.

  6. Right-click the 404 error again and select Edit.

  7. Select Execute a URL on this site and enter the same URL that you entered in step 4. Click OK.

  8. Go back to step 3 and repeat the same procedure for the 405 error.

  9. Click OK in all dialogs to save the changes. It’s not necessary to restart the application.

Setting up extensions in IIS manually (obsolete)

The following approach is also possible, but not recommended and considered obsolete. For example, to use the .html extension, go through the following steps:

  1. Run Internet Information Services (IIS) Manager.
  2. Select your website.
  3. Open Handler mappings.
  4. Click to Add managed handler… .
  5. Enter the following values:
    • Request path: *.html
    • Type: System.Web.DefaultHttpHandler
    • Name: HTML
  6. Click OK.

Setting custom URLs

Once you have performed the required low-level configuration, set the URL extensions in the Kentico administration interface:

  1. Open the Settings application.
  2. Select the URLs and SEO category.
  3. Type the required extension into the Friendly URL extensions setting, for example: .html
  4. Click Save.

Now when you go to the live website, the system renders all URLs in menus and listings with the specified extension. You may need to manually update static links that were created with the default .aspx extension.

Setting extensionless URLs

To configure the system to use URLs without an extension, save an empty value into the Friendly URL extensions setting.

Using multiple extensions

You can enter multiple extensions into the Friendly URL extensions setting. Use the following rules:

  • The first extension is used as the default
  • Enter other extensions, separated by semicolons. Pages can be accessed through URLs ending with all entered extensions.
  • To allow extensionless URLs in combination with other extensions, enter a semicolon without an extension

Examples:

  • ;.aspx - extensionsless URLs by default, also allows aspx
  • .html;.htm;;.asp - html extension by default, also allows htm, extensionless and asp

If you enable the Redirect documents to main extension setting in Settings -> URLs and SEO, the system redirects URLs with non-default extensions to the corresponding URL with the default extension. This can be useful for SEO purposes. For example, if you want to change your site’s URL extension, and use the new extension when the pages are accessed from a search engine that has your website indexed with the old extension.

Document-level extension settings

In addition to the global settings, you can set URL extensions for individual pages. The default extension that appears in the browser address bar when opening pages is always taken from the global settings.

  1. Open the Pages application.
  2. Select the document in the content tree.
  3. Switch to the Properties -> URLs tab.
  4. Select the Use custom URL extensions check box.
  5. Type the required extensions using the same rules as described above.
  6. Click Save.

Even if the Use custom URL extensions option is disabled, files (cms.file documents) can be accessed under their physical extensions.