Middleware

Last Updated: 2018-10-08

The first component in the Asp.NET Core pipeline is Middleware. Middleware can either handle a request completely, or process the incoming request and pass it on to the next component in the pipeline.

As Piranha CMS is built around standard Asp.NET components most of its middleware is used for routing and passes the request on to eventually be handled by the web application.

Registering The Middleware

Middleware is added in the Configure method in your Startup. To add all of the available middleware for Piranha CMS you call the extension method:

app.UsePiranha();

If only want to use parts of Piranha CMS you can register them manually.

Default Pipeline

When registering all of the middleware by calling app.UsePiranha() the middleware are added in the following order:

  1. Site Middleware
  2. Alias Middleware
  3. Page Middleware
  4. Post Middleware
  5. Archive Middleware
  6. Startpage Middleware
  7. Sitemap Middleware

Available Middleware

Below is a description of the different middleware components, how you register them manually, and what they do. Please note that if you plan on registering middleware manually you should not call app.UsePiranha() as this will register all middleware.

Site Middleware

app.UsePiranhaSites()

Adds the middleware that resolves the current site requested by the incoming request. This middleware is mandatory and needed by all other middleware that handles incoming requests.

Alias Middleware

app.UsePiranhaAliases()

This adds the middleware that rewrites incoming requests depending on the current aliases configured in the manager.

Page Middleware

app.UsePiranhaPages()

This adds the middleware that tries to resolve an incoming request to the slugs available for the current site. It listens to URL's of the following syntax:

GET /<pageSlug>

The middleware will rewrite requests to the specified Page Type Route or to /page if no route is specified, with the arguments id & startpage. To handle this request your controller action should look like this:

[Route("page")]
public IActionResult Page(Guid id, bool startpage) {
...
}

Post Middleware

app.UsePiranhaPosts()

This adds the middleware that tries to resolve an incoming request to the slugs available for the current site. It listens to URL's of the following syntax:

GET /<blogPageSlug>/<postSlug>

The middleware will rewrite requests to the specified Post Type Route or to /post if no route is specified, with the argument id. To handle this request your controller action should look like this:

[Route("post")]
public IActionResult Post(Guid id) {
...
}

Archive Middleware

app.UsePiranhaArchives()

This adds the middleware that resolves incoming requests for archive pages and rewrites the request to the specified Page Type Route or to /archive if no route is specified. It listens to URL's of the following syntax:

Standard Request

GET /<blogPageSlug>/<year?>/<month?>(/page/<pageNum>)?

Filtered By Category

GET /<blogPageSlug>/category/<categorySlug>/<year?>/<month?>(/page/<pageNum>)?

Filtered By Tag

GET /<blogPageSlug>/tag/<tagSlug>/<year?>/<month?>(/page/<pageNum>)?

All parameters are optional except blogPageSlug, but the optional paging must be placed last. Everything after the page number is ignored. This means that the following URL's would be valid:

/myblog
/myblog/category/fishing
/myblog/tag/salmon
/myblog/page/2
/myblog/category/fishing/page/2
/myblog/tag/salmon/page/2
/myblog/2018
/myblog/category/fishing/2018
/myblog/tag/salmon/2018
/myblog/2018/page/2
/myblog/category/fishing/2018/page/2
/myblog/tag/salmon/2018/page/2
/myblog/2018/1
/myblog/category/fishing/2018/1
/myblog/tag/salmon/2018/1
/myblog/2018/1/page/2
/myblog/category/fishing/2018/1/page/2
/myblog/tag/salmon/2018/1/page/2

The middleware will rewrite requests to the specified route with the following arguments:

[Route("archive")]
public IActionResult Archive(Guid id, int? year = null, int? month = null,
int? page = null, Guid? category = null, Guid? tag = null)
{
...
}

Startpage Middleware

app.UsePiranhaStartPage()

Adds the middleware that resolves requests to the site root. It listens to URL's of the following syntax:

GET /

The request is rewritten the same way as for pages.

Sitemap Middleware

app.UsePiranhaSitemap()

Adds the middleware that responds to incoming requests for /sitemap.xml and returns a sitemap document.

GET /sitemap.xml