1 of 2

Custom Routing

There are a couple of ways of controlling the routing behavior in Umbraco: customizing how the inbound request pipeline finds content & creating custom MVC routes that integrate within the Umbraco pip

Customizing the inbound pipeline

Below lists the ways in which you can customize the inbound request pipeline, this is done by using native Umbraco plugin classes, notifications, or defining your own routes.

IContentFinder

All Umbraco content is looked up based on the URL in the current request using an IContentFinder. IContentFinder's you can create and implement on your own which will allow you to map any URL to a Umbraco content item.

See: IContentFinder documentation

Last Chance IContentFinder

A IContentLastChanceFinder is a special implementation of an IContentFinder for use with handling 404's. You can implement one of these plugins to decide which Umbraco content page you would like to show when the URL hasn't matched a Umbraco content node.

When creating packages or using class libraries, the SetContentLastChanceFinder is a part of the Umbraco.Cms.Web.Website NuGet package.

To set your own 404 finder create a IContentLastChanceFinder and set it as the ContentLastChanceFinder. A ContentLastChanceFinder will always return a 404 status code. Example:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Extensions;

namespace My.Website
{
    public class UpdateContentFindersComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            //set the last chance content finder
            builder.SetContentLastChanceFinder<My404ContentFinder>();
        }
    }
}

For more detailed information see: IContentFinder documentation

Custom MVC routes

You can specify your own custom MVC routes to work within the Umbraco pipeline. It requires your controller to inherit from UmbracoPageController and either implement IVirtualPageController or use .ForUmbracoPage when registering your route, for more information and a complete example of both approaches see Custom routing documentation

An example of registering a UmbracoPageController using .ForUmbracoPage:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Web.Common.ApplicationBuilder;
using Umbraco.Extensions;

namespace CustomRoutes
{
    public class MyCustomRouteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.Services.Configure<UmbracoPipelineOptions>(options =>
            {
                options.AddFilter(new UmbracoPipelineFilter(nameof(MyController))
                {
                    Endpoints = app => app.UseEndpoints(endpoints =>
                    {
                        endpoints.MapControllerRoute(
                            "My custom controller",
                            "/custom/{action}",
                            new {Controller = "My", Action = "Index"})
                            .ForUmbracoPage(FindContent);
                    })
                });
            });
        }

        private IPublishedContent FindContent(ActionExecutingContext actionExecutingContext)
        {
            var umbracoContextAccessor = actionExecutingContext.HttpContext.RequestServices
                .GetRequiredService<IUmbracoContextAccessor>();
            var umbracoContext = umbracoContextAccessor.GetRequiredUmbracoContext();

            return umbracoContext.Content.GetById(1064);
        }
    }
}

This is an approach for mapping a custom route to a custom MVC controller. For creating routes for existing content pages you can use a custom MVC controller to handle the request by naming convention: see Custom Controllers - Route Hijacking.

RoutingRequestNotification

You can subscribe to the RoutingRequestNotification which is published right after the point when the PublishedRequestBuilder is prepared - (but before it is ready to be processed). Here you can modify anything in the request before it is processed, eg. content, template, etc:

using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace CustomRoutes
{
    public class PublishedRequestHandler : INotificationHandler<RoutingRequestNotification>
    {
        public void Handle(RoutingRequestNotification notification)
        {
            var requestBuilder = notification.RequestBuilder;
            // Do something with the IPublishedRequestBuilder here
        }
    }
}

For more information on how to register and use notification handlers see Notifications documentation

Find out how to add your own hub(s) with SignalR to the existing setup)

Adding a hub with SignalR and Umbraco

Umbraco ships with signalR installed, find out how to add your own hub(s) to the existing setup

Umbraco ships with signalR installed. This article shows how to add your own hub(s) to the existing setup.

Create a hub and its interface

We are going to go for the most basic implementation possible, a status ping. So first create a new interface with the following code:

public interface ITestHubEvents
{
    // Define the events the clients can listen to
    public Task Pong();
}

And then the actual hub:

using Microsoft.AspNetCore.SignalR;

public class TestHub : Hub<ITestHubEvents>
{
    // when a client sends us a ping
    public async Task Ping()
    {
        // we trigger the pong event on all clients
        await Clients.All.Pong();
    }
}

Define a custom route

Next up, is defining a custom route. For this, we are going to use a IAreaRoutes and the base umbrace backend path so we dont have to reserve another path in the settings.

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Web.Common.ApplicationBuilder;
using Umbraco.Extensions;

public class TestHubRoutes : IAreaRoutes
{
    private readonly IRuntimeState _runtimeState;
    private readonly string _umbracoPathSegment;

    public TestHubRoutes(
        IOptions<GlobalSettings> globalSettings,
        IHostingEnvironment hostingEnvironment,
        IRuntimeState runtimeState)
    {
        _runtimeState = runtimeState;
        _umbracoPathSegment = globalSettings.Value.GetUmbracoMvcArea(hostingEnvironment);
    }

    public void CreateRoutes(IEndpointRouteBuilder endpoints)
    {
        switch (_runtimeState.Level)
        {
            case Umbraco.Cms.Core.RuntimeLevel.Run:
                endpoints.MapHub<TestHub>(GetTestHubRoute());
                break;
        }

    }

    public string GetTestHubRoute()
    {
        return $"/{_umbracoPathSegment}/{nameof(TestHub)}";
    }
}

Add the routing to the Umbraco Composer

Last step in the setup is registering our custom route:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Web.Common.ApplicationBuilder;
using Umbraco.Extensions;

public class TestHubComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        // first we are going to add signalR to the serviceCollection if no hubs have been added yet
        // this is just in case Umbraco ever decides to use a different technology
        if (!builder.Services.Any(x => x.ServiceType == typeof(IHubContext<>)))
        {
            builder.Services.AddSignalR();
        }
        
        // next is adding the routes we defined earlier
        builder.Services.AddUnique<TestHubRoutes>();
        builder.Services.Configure<UmbracoPipelineOptions>(options =>
        {
            options.AddFilter(new UmbracoPipelineFilter(
                "test",
                 endpoints: applicationBuilder =>
                {
                    applicationBuilder.UseEndpoints(e =>
                    {
                        var hubRoutes = applicationBuilder.ApplicationServices.GetRequiredService<TestHubRoutes>();
                        hubRoutes.CreateRoutes(e);
                    });
                }
            ));
        });
    }
}

Add the route in appsettings.json file

When setting up SignalR routes, add the route to ReservedPaths in the appsettings.json file like:

"Umbraco": {
    "CMS": {
        "Global": {
            "ReservedPaths": "~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,~/umbraco/testhub/,"
        }
    }
}

You need to provide the default reserved paths, else you'll run into an issue as mentioned on GitHub.

Test the setup

And lastly we can test the setup with some JavaScript in our view:

<!-- We reference the signalR js file that comes with Umbraco -->
<script type="text/javascript" src="/umbraco/lib/signalr/signalr.min.js"></script>
<script>
    var connection = new signalR.HubConnectionBuilder()
        .withUrl("/umbraco/testhub") // this is the url that we created in the routing `TestHubRoutes.GetTestHubRoute()`
        .withAutomaticReconnect()
        .configureLogging(signalR.LogLevel.Warning)
        .build();
    
    // register our callbacks when the hub sends us an event
        connection.on("Pong", function () {
            console.log("Pong");
        });

    // start the connection
    connection.start().then(function () {
        console.info("signalR connection established");

        // connection is established => call a function on the hub
        connection.invoke("Ping").catch(function (err) {
            return console.error("Could not invoke method [Ping] on signalR connection", err.toString());
        });
    }).catch(function (err) {
        return console.error("could not establish a signalR connection", err.toString());
    });
</script>

When you insert this in a view, you should see a signalR connection established console message followed by Pong.

Adding a hub with SignalR and Umbraco

Umbraco ships with signalR installed, find out how to add your own hub(s) to the existing setup

Umbraco ships with signalR installed. This article shows how to add your own hub(s) to the existing setup.

Create a hub and its interface

We are going to go for the most basic implementation possible, a status ping. So first create a new interface with the following code:

public interface ITestHubEvents
{
    // Define the events the clients can listen to
    public Task Pong();
}

And then the actual hub:

using Microsoft.AspNetCore.SignalR;

public class TestHub : Hub<ITestHubEvents>
{
    // when a client sends us a ping
    public async Task Ping()
    {
        // we trigger the pong event on all clients
        await Clients.All.Pong();
    }
}

Define a custom route

Next up, is defining a custom route. For this, we are going to use a IAreaRoutes and the base umbrace backend path so we dont have to reserve another path in the settings.

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Web.Common.ApplicationBuilder;
using Umbraco.Extensions;

public class TestHubRoutes : IAreaRoutes
{
    private readonly IRuntimeState _runtimeState;
    private readonly string _umbracoPathSegment;

    public TestHubRoutes(
        IOptions<GlobalSettings> globalSettings,
        IHostingEnvironment hostingEnvironment,
        IRuntimeState runtimeState)
    {
        _runtimeState = runtimeState;
        _umbracoPathSegment = globalSettings.Value.GetUmbracoMvcArea(hostingEnvironment);
    }

    public void CreateRoutes(IEndpointRouteBuilder endpoints)
    {
        switch (_runtimeState.Level)
        {
            case Umbraco.Cms.Core.RuntimeLevel.Run:
                endpoints.MapHub<TestHub>(GetTestHubRoute());
                break;
        }

    }

    public string GetTestHubRoute()
    {
        return $"/{_umbracoPathSegment}/{nameof(TestHub)}";
    }
}

Add the routing to the Umbraco Composer

Last step in the setup is registering our custom route:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Web.Common.ApplicationBuilder;
using Umbraco.Extensions;

public class TestHubComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        // first we are going to add signalR to the serviceCollection if no hubs have been added yet
        // this is just in case Umbraco ever decides to use a different technology
        if (!builder.Services.Any(x => x.ServiceType == typeof(IHubContext<>)))
        {
            builder.Services.AddSignalR();
        }
        
        // next is adding the routes we defined earlier
        builder.Services.AddUnique<TestHubRoutes>();
        builder.Services.Configure<UmbracoPipelineOptions>(options =>
        {
            options.AddFilter(new UmbracoPipelineFilter(
                "test",
                 endpoints: applicationBuilder =>
                {
                    applicationBuilder.UseEndpoints(e =>
                    {
                        var hubRoutes = applicationBuilder.ApplicationServices.GetRequiredService<TestHubRoutes>();
                        hubRoutes.CreateRoutes(e);
                    });
                }
            ));
        });
    }
}

Add the route in appsettings.json file

When setting up SignalR routes, add the route to ReservedPaths in the appsettings.json file like:

"Umbraco": {
    "CMS": {
        "Global": {
            "ReservedPaths": "~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,~/umbraco/testhub/,"
        }
    }
}

You need to provide the default reserved paths, else you'll run into an issue as mentioned on GitHub.

Test the setup

And lastly we can test the setup with some JavaScript in our view:

<!-- We reference the signalR js file that comes with Umbraco -->
<script type="text/javascript" src="/umbraco/lib/signalr/signalr.min.js"></script>
<script>
    var connection = new signalR.HubConnectionBuilder()
        .withUrl("/umbraco/testhub") // this is the url that we created in the routing `TestHubRoutes.GetTestHubRoute()`
        .withAutomaticReconnect()
        .configureLogging(signalR.LogLevel.Warning)
        .build();
    
    // register our callbacks when the hub sends us an event
        connection.on("Pong", function () {
            console.log("Pong");
        });

    // start the connection
    connection.start().then(function () {
        console.info("signalR connection established");

        // connection is established => call a function on the hub
        connection.invoke("Ping").catch(function (err) {
            return console.error("Could not invoke method [Ping] on signalR connection", err.toString());
        });
    }).catch(function (err) {
        return console.error("could not establish a signalR connection", err.toString());
    });
</script>

When you insert this in a view, you should see a signalR connection established console message followed by Pong.

Custom Routing

Customizing the inbound pipeline

Below lists the ways in which you can customize the inbound request pipeline, this is done by using native Umbraco plugin classes, notifications, or defining your own routes.

IContentFinder

See: IContentFinder documentation

Last Chance IContentFinder

When creating packages or using class libraries, the SetContentLastChanceFinder is a part of the Umbraco.Cms.Web.Website NuGet package.

To set your own 404 finder create a IContentLastChanceFinder and set it as the ContentLastChanceFinder. A ContentLastChanceFinder will always return a 404 status code. Example:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Extensions;

namespace My.Website
{
    public class UpdateContentFindersComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            //set the last chance content finder
            builder.SetContentLastChanceFinder<My404ContentFinder>();
        }
    }
}

For more detailed information see: IContentFinder documentation

Custom MVC routes

An example of registering a UmbracoPageController using .ForUmbracoPage:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.DependencyInjection;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Web.Common.ApplicationBuilder;
using Umbraco.Extensions;

namespace CustomRoutes
{
    public class MyCustomRouteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.Services.Configure<UmbracoPipelineOptions>(options =>
            {
                options.AddFilter(new UmbracoPipelineFilter(nameof(MyController))
                {
                    Endpoints = app => app.UseEndpoints(endpoints =>
                    {
                        endpoints.MapControllerRoute(
                            "My custom controller",
                            "/custom/{action}",
                            new {Controller = "My", Action = "Index"})
                            .ForUmbracoPage(FindContent);
                    })
                });
            });
        }

        private IPublishedContent FindContent(ActionExecutingContext actionExecutingContext)
        {
            var umbracoContextAccessor = actionExecutingContext.HttpContext.RequestServices
                .GetRequiredService<IUmbracoContextAccessor>();
            var umbracoContext = umbracoContextAccessor.GetRequiredUmbracoContext();

            return umbracoContext.Content.GetById(1064);
        }
    }
}

RoutingRequestNotification

using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace CustomRoutes
{
    public class PublishedRequestHandler : INotificationHandler<RoutingRequestNotification>
    {
        public void Handle(RoutingRequestNotification notification)
        {
            var requestBuilder = notification.RequestBuilder;
            // Do something with the IPublishedRequestBuilder here
        }
    }
}

For more information on how to register and use notification handlers see Notifications documentation

Find out how to add your own hub(s) with SignalR to the existing setup)

Custom Routing

Customizing the inbound pipeline

IContentFinder

Last Chance IContentFinder

Custom MVC routes

RoutingRequestNotification

Related articles

Adding a hub with SignalR and Umbraco

Create a hub and its interface

Define a custom route

Add the routing to the Umbraco Composer

Add the route in appsettings.json file

Test the setup

Adding a hub with SignalR and Umbraco

Create a hub and its interface

Define a custom route

Add the routing to the Umbraco Composer

Add the route in appsettings.json file

Test the setup

Custom Routing

Customizing the inbound pipeline

IContentFinder

Last Chance IContentFinder

Custom MVC routes

RoutingRequestNotification

Related articles