URL Rewrites in Umbraco
With the release of Umbraco 9 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 9 on IIS you can still add a
web.config
file to configure IIS features such as URL rewrites.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.
To use rewrites with Umbraco 9 you have to register the middleware in your
Startup.cs
by using the UseRewriter
extension method and then configure the rewrite options.- Create an
IISUrlRewrite.xml
file in the root of your project (next to yourStartup.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
Startup.cs
file you can add the URL Rewriting Middleware just before the call toapp.UseUmbraco()
and useAddIISUrlRewrite
) to add the rewrite rules from the XML file:
using Microsoft.AspNetCore.Rewrite;
app.UseRewriter(new RewriteOptions().AddIISUrlRewrite(env.ContentRootFileProvider, "IISUrlRewrite.xml"));
- In your csproj file add the XML file to a new item group and set
CopyToOutputDirectory
toAlways
:
<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.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>
Adding the www redirect rule requires a
<add input="{HTTP_HOST}" pattern=".*azurewebsites.net*" negate="true" ignoreCase="true" />
condition to be added in order for Umbraco Cloud to function correctly.This step is required for the deployment service and the content transfer between environments to continue to function.
Last modified 22d ago