Custom Middleware
Customizing the ASP.NET middleware pipeline in Umbraco
Middleware is responsible for processing/customizing an incoming request before generating an outgoing response. Shortly defined the middleware is a step to check the requests before giving a response back.
Umbraco automatically configures all required middleware in the WithMiddleware()
method in a specific order based on the Microsoft documentation.
You can use Umbraco pipeline filters in case you want to add your own middleware before, in-between or after the default Umbraco middleware. Filters are added by configuring the UmbracoPipelineOptions
and require an instance of IUmbracoPipelineFilter
that contains the following callbacks:
PrePipeline
- executed before any Umbraco-specific middleware is added, an example can be URL rewrites.PreRouting
- executed after the static files middleware and before the routing middleware is added (usingUseRouting()
). It can also be used to change the incoming URL.PostRouting
- executed after the routing middleware is added and can be used to configure Cross-origin resource sharing (CORS).PostPipeline
- executed after all Umbraco-specific middleware is added.Endpoints
- executed right before the Umbraco-specific endpoints are added usingWithEndpoints()
.
The addition of the PostRouting
callback is to allow correctly configuring the Cross-Origin Resource Sharing (CORS) middleware without having to use the WithCustomMiddleware()
method.
IUmbracoPipelineFilter
is an interface in Umbraco that allows the creation of custom filters which then modifies the behavior of the request pipeline. It can be used to change different aspects of how Umbraco handles incoming requests, such as changing content or adding security checks.WithCustomMiddleware()
is a method that can be used in Umbraco for adding custom middleware. This includes some specific customizable instructions that run in the request processing pipeline.
Using WithCustomMiddleware()
instead of WithMiddelware()
should only be used as a last resort. This is because Umbraco can break if you forget to add middleware or add them in the wrong order.
Configuring the Cross-Origin Resource Sharing (CORS) middleware
Create a composer with the following:
You should be able to request /echo
from any origin, but get an error when trying to fetch /echo2
from a foreign origin. This can be tested by pasting the following JavaScript code in browser console when not on the local origin/Umbraco website (such as umbraco.com):
This should return the following:
An additional bonus is that this doesn't require any changes in your Program.cs
file. It also allows packages to enable Cross-Origin Resource Sharing (CORS) and configure their own policies.
Users that currently use WithCustomMiddleware()
will need to add calls to RunPreRouting()
and RunPostRouting()
. This is similar to Umbraco adding additional middleware in future versions.
Last updated