URL Rewrites in Umbraco

Since the release of Umbraco v9 and the change of the underlying web framework that is decoupled from the webserver, the way that you configure rewrites has changed as well.

Instead of the URL Rewriting extension in IIS you can use the URL Rewriting Middleware in ASP.NET Core, which needs to be added to your project startup code first.

If you are running Umbraco v9+ on IIS you can still add a web.config file to configure IIS features such as URL rewrites.

When to use the URL Rewriting Middleware

Make sure to check the official URL Rewriting Middleware in ASP.NET Core documentation for more information about when you should or should not use the URL Rewriting Middleware.

Using the URL Rewriting Middleware

To use rewrites with Umbraco v9+ you have to register the middleware in your Program.cs by using the UseRewriter extension method and then configure the rewrite options.

Example

• Create an IISUrlRewrite.xml file in the root of your project (next to your Program.cs file) containing:

<?xml version="1.0" encoding="utf-8" ?>
<rewrite>
  <rules>
    <rule name="Redirect umbraco.io to preferred domain" stopProcessing="true">
      <match url=".*" />
      <conditions>
        <add input="{HTTP_HOST}" pattern="\.umbraco\.io$" />
        <add input="{REQUEST_URI}" pattern="^/App_Plugins/" negate="true" />
        <add input="{REQUEST_URI}" pattern="^/umbraco" negate="true" />
      </conditions>
      <action type="Redirect" url="https://example.com/{R:0}" />
    </rule>
  </rules>
</rewrite>

• In the Program.cs file you can add the URL Rewriting Middleware before the call to app.UseUmbraco() and use AddIISUrlRewrite to add the rewrite rules from the XML file:

using Microsoft.AspNetCore.Rewrite;

var rewriteOptions = new RewriteOptions()
    .AddIISUrlRewrite(builder.Environment.ContentRootFileProvider, "IISUrlRewrite.xml");

app.UseRewriter(rewriteOptions);

// This line is needed for the rewrites to take effect.
app.UseStaticFiles();

On Linux, make sure to place the app.UseStaticFiles() after the app.UseUmbraco() statements for the redirect to work as intended.

• In your csproj file add the XML file to a new item group and set CopyToOutputDirectory to Always:

<ItemGroup>
  <Content Include="IISUrlRewrite.xml">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </Content>
</ItemGroup>

On Umbraco Cloud the item group needs to be set to <CopyToPublishDirectory>Always</CopyToPublishDirectory> for the file to be published to your deployed site.

Rewrite rule shortcuts

RewriteOptions has a number of "shortcut" methods to implement commonly used rewrites including:

• AddRedirectToNonWww()

• AddRedirectToWww()

• AddRedirectToNonWwwPermanent()

• AddRedirectToWwwPermanent()

• AddRedirectToHttps()

For more details and other examples, take a look at the URL Rewriting Middleware in ASP.NET Core and RewriteOptions Class documentation.

Examples of rewrite rules

• A great site showing 10 very handy IIS Rewrite rules: URL rewriting tips and tricks

• Another site showing some handy examples of IIS Rewrite rules: Some useful IIS rewrite rules

• If you needed to a lot of static rewrites using rewrite maps: Rule with rewrite map rule template

For example, to always remove a trailing slash from the URL (make sure Umbraco doesn't add a trailing slash to all generated URLs by setting AddTrailingSlash to false in your RequestHandler settings):

<rule name="Remove trailing slash" stopProcessing="true">
  <match url="(.*)/+$" />
  <conditions>
    <add input="{REQUEST_URI}" pattern="^/umbraco" negate="true" />
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
    <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
  </conditions>
  <action type="Redirect" url="/{R:1}" />
</rule>

Another example would be to enforce HTTPS only on your site:

<rule name="Redirect to HTTPS" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTPS}" pattern="^OFF$" />
    <add input="{HTTP_HOST}" pattern="^localhost(:[0-9]+)?$" negate="true" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:0}" />
</rule>

Another example would be to redirect from non-www to www (except for the Umbraco Cloud project hostname):

<rule name="Redirect to www prefix" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="^www\." negate="true" />
    <add input="{HTTP_HOST}" pattern="^localhost(:[0-9]+)?$" negate="true" />
    <add input="{HTTP_HOST}" pattern="\.umbraco\.io$" negate="true" />
  </conditions>
  <action type="Redirect" url="https://www.{HTTP_HOST}/{R:0}" />
</rule>

If you use Umbraco Cloud check the Rewrite Rules article.