Rewriting application URLs

If you have URL rewriting (via the URL rewrite module for IIS) configured for your application, you need to ensure your rewrite rules do not interfere with internal Kentico functionality. For example, a global rewrite rule appending a trailing slash after every URL (including requests for physical files, such as stylesheets and JavaScript code) is not supported by Kentico and causes certain system features to malfunction.

This also applies when configuring rewrite rules for the separate MVC application on sites built using the MVC development model. Since the MVC application also handles various system requests, incorrectly defined rules could disrupt certain system functionality or lead to runtime errors.

Before deploying custom rewrite rules on live instances, we recommend you:

Create conditions that exclude physical files and system URLs (e.g., preview mode links) from being rewritten.

Rewrite rule conditions




  <conditions>  
      <!-- Prevents requests to internal Kentico functionality (e.g., preview mode URLs) from being rewritten -->
      <add input="{URL}" pattern="/cmsctx(?:/.*)?$" negate="true"/>
      <add input="{URL}" pattern="/kentico(?:/.*)?$" negate="true" /> 
      <!-- Ensures the rule is not applied when requesting content items (such as physical .css and .js files) -->
      <add input="{request_filename}" matchType="IsFile" negate="true" />
      ...
  </conditions>

Test all rules, ensuring their compatibility with your site and the system.

For more information about configuring rewrite rules, refer to URL Rewrite Module Configuration Reference in the official Microsoft documentation.

For example, the following rewrite rule appends a trailing slash to all URLs, with the exception of routes and files required by Kentico:

Append trailing slash rewrite rule




<!-- This sample configures URL rewriting at the root level of an IIS website -->
<system.webServer>
...
    <rewrite>
        <rules>
            <rule name="Append trailing slash" stopProcessing="true">
                <match url="(.*[^/])$" />
                <action type="Redirect" url="{R:1}/" />
                <conditions>
                    <!-- Prevents requests to internal Kentico functionality (e.g., preview mode URLs) from being rewritten -->
                    <add input="{URL}" pattern="/cmsctx(?:/.*)?$" negate="true"/>
                    <add input="{URL}" pattern="/kentico(?:/.*)?$" negate="true" /> 
                    <!-- Ensures the rule is not applied when requesting content items (such as physical .css and .js files) -->
                    <add input="{request_filename}" matchType="IsFile" negate="true" /> 
                    <!-- Ensures the rule is applied when requesting directories -->
                    <add input="{request_filename}" matchType="IsDirectory" /> 
                </conditions>
            </rule>
        </rules>
    </rewrite>
...
</system.webServer>