Rewriting application URLs

✖
Copy to clipboard

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 Xperience 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 Xperience and causes certain system features to malfunction.

This also applies when configuring rewrite rules for your separate MVC live site application. 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 Xperience 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 the system:

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 Xperience 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>