Using StatusCodePages middleware in ASP.NET Core Application

In ASP.NET Web and MVC applications, we have a customErrors.Mode property in the web.config file to specify custom error pages for exceptions happening in the application.

In an ASP.NET Core web application we can make use of the UseStatusPages middleware to return a custom error page or a error message to the output stream. The middleware can be used to return a custom error message or page when there is an invlid response code between 400 and 600. Normally, the 4xx error is used for client errors where as 5xx is used for server errors.

To explain the various options available in the middleware, I am going to use a ASP.NET Core web application created using Visual Studio Code and .NET CLI tools to run the application. You can also do the same using Visual Studio IDE too.

Let's create a empty MVC project and run the application using the dotnet run command. It will self host the application and exposes port# 5000 for accessing the site. Open the site in the default browser by typing in http://localhost:5000/ and if you try to access a page which doesn't exists in the project, the browser will show an empty page or a page with a message saying that Page not found. Given below is the screenshot of the page I got in Chrome. If you open up the developer tools by pressing F12, you can see that the response from the server has 404 as status code.

This is not at all user friendly and we need to let the user know what has happened about the issue in a meaningful way. This is when UseStatusCodePages middleware comes to your rescue and let's see how we can use the various options available in the middleware to handle the scenarios like above

Approach #1

Add the following command in the Configure method in the Startup.cs file to configure the UseStaticCodePages middleware as shown below

app.UseStatusCodePages();

So if you run the project now, you will see that following error in your browser page and in the developer console will show the status code as 404.

Approach #2

The message shown in the browser is sent by the middleware by default and if you want to override the message with your own, replace the earlier statement with the one given below.

app.UseStatusCodePages("text/plain","Response from the server, status code :{0}");

Here we are using an override for the UseStatusCodePages method which accepts the content type as the first parameter and second one is the message that needs to be sent to the client. The placeholder {0} will get replaced with the status code when the message is being sent to the client.

Approach #3

One disadvantage of the above approach is that by writing the error message directly into the response stream, the browser will show the error message devoid of any themes or layout that we are using throughout the site. Let's consider in our site we are having a banner in the top and content is coming below that as shown in the image below and we need to show the error messages too in the same layout.

In the earlier approaches the message was showing in plain pages  and to overcoming this handicap, we have another extention method UseStatusCodePagesWithRedirects in the middleware which will redirect the user to another page in the case of a 404 error to show the message.

app.UseStatusCodePagesWithRedirects("/{0}.html");

In this method, we have specified the name of the file that needs to served when there is an error. The placeholder {0} will be replaced with  actual status code and will look for the file in the root directory. So, if a 404 error happens then it will serve the 404.html file in the root directory. Iinorder for this method to work as expected, you need to create a static file in the root directory matching the name specified in the parameter like 404.html for 404 error, 500.html for 500 error etc.

So for the above statement to work as expected, I have created a file with name 404.html and saved it in the root directory. Let's run the application and see how the output is coming in the browser.

You can see from the developer console that, when I requested for an incorrect page, it returned with a 302 status code and then redirected to the 404.html page to show the error. You can also see that the url in the address bar also changed to confirm the redirection.

Approach #4

In the earlier approach there was there was an additional request made for serving the error page and this extra request can be avoided by making use of another method, UseStatusCodePagesWithReExecute in the middleware

app.UseStatusCodePagesWithReExecute("/{0}.html");

This method works exactly like the Redirect method, the difference being that the redirection happens at the server itself and the url stays the same