(C# ASP.NET Core) What and Why of the UseDeveloperExceptionPage Middleware

Objective of this Tutorial

We shall learn about the UseDeveloperExceptionPage middleware, and also learn that a developer exception page provides a lot of information about an un-handled exception. This information can be used for troubleshooting the cause of failure. We shall also verify that this page is enabled only for an app running in development environment.

Video Explanation

Please watch the following youtube video:

Create a Project to throw a test exception

First of all, open visual studio and create a simple asp.net core project.

I have created an asp.net core project of just one razor page called Index. Double-click to open this page. As we can see, this page has a link, which is connected to a handler called MyClickHandler.

Open the IndexModel class. We can see that this function throws a test exception. For our purposes, this as an un-expected, and un-handled exception.

public class IndexModel : PageModel
{

  // generates an exception for testing 
  public void OnGetMyClickHandler()
  {

    throw new Exception("This is a test exception");

  }

}

I have made no other change. This project was created through Visual Studio 2022, running .NET 6. And, just for record, let us have a look at the program.cs file also. As you can see, it is a simple file of a few lines of code, and it sets the environment to Development:

// set the environment to development 
var builder = WebApplication.CreateBuilder(new WebApplicationOptions()
{

  EnvironmentName = Environments.Development
}

);

builder.Services.AddRazorPages();

var app = builder.Build();

app.MapRazorPages();

app.Run();

Developer Exception Page and Unhandled Exceptions in a Development Environment

Just for curiosity, let's see what happens when an unhandled exception is thrown.

Run the project without debugging by using Ctrl+F5, so that visual studio doesn't break on the line that throws our artificial exception. The usual behaviour of visual studio is to break to the line that throws the exception. We do not need that here, so let us start the project directly - with Ctrl + F5.

Allow the index page to open. Click the link to invoke the click event handler, and let it throw an artificial exception.

We observe that ASP.NET Core catches the exception and returns a fairly detailed error page. I am sure you must already be familiar with the looks of this page.

This page is called Developer Exception Page. The features of this page are:

1. ASP.NET Core automatically enables it if the app runs under Development environment. No action needs to be taken at your end for enabling it. It is automatically done for you by the start-up code. This happens through various behind-the-scenes calls in the CreateBuilder method of the Program.cs file - the very first line.
2. It is a "safety net". It handles any un-handled exception.
3. It is dynamically generated by ASP.NET Core. There is no physical page for this.
4. It contains a lot of sensitive data - like Stack Trace, it also contains data about cookies, and query string, and http headers.
5. It can be used during development to have a quick snapshot of the issue.
6. It should never be used in a production scenario. We shall come to that later.

What happens without the "Safety catch"?

Next let us see what happens if the app runs in a production environment - where the developer exception page is not enabled. What happens in that case? What happens if the "safety catch" is not available?

Let us open the Program.cs file and change the environment to Production.

Again run the app without debugging. Allow the index page to open. Click the handler and throw an exception.

We observe that the application responds as a dead end. It doesn't send any response. Think of yourself as a developer with a huge project and no clue about the problem.

You might argue that the project could be run in visual studio in debug mode, and use breakpoints etc., to reach the line causing the error. My answer is that it is not always possible, and not always practical to install visual studio on a production server. Usually, a downtime is planned on an application, and environment variables are changed so as to switch the mode to development. When this app runs under development, the detailed exception page as well as detailed logs become available, which is far more convenient and systematic approach to debugging the issue.

In the next tutorial we shall continue from here and discuss how to use custom error pages when the app runs in a production scenario. Thanks!