Developer Exception Page Middleware in ASP.NET Core

Back to: ASP.NET Core Tutorials For Beginners and Professionals

Developer Exception Page Middleware in ASP.NET Core Application

In this article, I am going to discuss How to Handle an Unhandled Exception using Developer Exception Page Middleware Component in ASP.NET Core Web Application. Please read our previous article, where we discussed How to Configure the Default Page in ASP.NET Core Web Application. Exception Handling is one of the key features of any application. We can handle the exception in many different ways. But in this article, I am going to discuss how we can use the Developer Exception Page Middleware Component to handle the unhandled exception in ASP.NET Core Web Application. As part of this article, we are going to discuss the following concepts.

1. What is Developer Exception Page Middleware?
2. How to use Developer Exception Page Middleware in ASP.NET Core Application?
3. How to Customize the UseDeveloperExceptionPage Middleware in ASP.NET Core?
4. Where do we need to configure the UseDeveloperExceptionPage Middleware?

Understanding Developer Exception Page Middleware in ASP.NET Core:

First, create an ASP.NET Core Application with the Empty Project template. To create a new Empty ASP.NET Core Web Application, open Visual Studio 2022 and click on the Create a new project tab, as shown in the image below.

Once you click on the Create a new project tab, it will open the Create a new project window. From this window, you need to select the ASP.NET Core Empty project template and click the Next button, as shown in the image below.

Once you click on the Next button, it will open the Configure Your New Project window. Here, you need to provide the necessary information to create a new project. First, give an appropriate name for your project (FirstCoreWebApplication), set the location where you want to create this project, and the solution name for the ASP.NET Core Web application. And finally, click on the Create button, as shown in the image below.

Once you click on the Next button, it will open the Additional Information window. Here, you need to select .NET 6.0 as the Framework. You also need to check the Configure for HTTPS and Do not use top-level statements check boxes, and finally, click on the Create button as shown in the below image.

That’s it. Once you click on the Create Button, the project is going to be created with the Empty template. By default, the ASP.NET Core Web Application (.NET 6) returns the Developer Exception Page in Development Environment if the exception is not handled by the application. Let us understand this with an example. Please modify the Main() method of the Program Class as shown below, where we throw an exception.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            app.MapGet("/", async context =>
            {
                int Number1 = 10, Number2 = 0;
                int Result = Number1 / Number2; //This statement will throw Runtime Exception
                await context.Response.WriteAsync($"Result : {Result}");
            });

            //This will Run the Application
            app.Run();
        }
    }
}

When you run the application, you will get the following output.

As you can see, we are getting the details of the exceptions on the page. This is possible because the .NET Core Framework automatically enables the developer exception page for the Development environment. If you want, then you can also add the Developer Exception Page Middleware component within the Main method of the Program class as follows.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            //If the Environment is Development, Please Show the Unhandled Exception Details 
            if (app.Environment.IsDevelopment())
            {
                //Using UseDeveloperExceptionPage Middleware to Show Exception Details
                app.UseDeveloperExceptionPage();
            }

            app.MapGet("/", async context =>
            {
                int Number1 = 10, Number2 = 0;
                int Result = Number1 / Number2; //This statement will throw Runtime Exception
                await context.Response.WriteAsync($"Result : {Result}");
            });

            //This will Start the Application
            app.Run();
        }
    }
}

With this change, run the application, and you will also get the same exception page as shown in the below image.

As you can see in the above image, the Developer Exception Page contains five tabs: Stack, Queue, Cookies, Headers, and Routing.

1. Stack: The Stack tab gives the information of stack trace, which indicates where exactly the exception occurred, the file name, and the line number that caused the exception.
2. Query: The Query tab gives information about the query strings.
3. Cookies: The Cookies tab displays the information about the cookies set by the request.
4. Header: The Header tab gives information about the headers which is sent by the client when he makes the request.
5. Routing: The Routing tab gives information about the Route Pattern and Route HTTP Verb type of the method, etc.

If you verify the Query tab, you will not see any information as you are not passing any query string value in the URL. In our upcoming sessions, we will discuss the Query string, Cookies, and Routing in detail.

Note: Please Enable the Developer Exception Page Middleware only when the application is running in the Development environment. You don’t want to share detailed exception information when the application is running in the production environment.

How to use DeveloperExceptionPage Middleware in Old Version ASP.NET Core Application?

If you are working with any older versions of .NET Core Application, in order to display a page that shows detailed information about the unhandled exception, you need to configure the Developer Exception Page Middleware in the Request Processing Pipeline. To do so, you need to modify the Configure() Method of the Startup class as shown below to add the Developer Exception Page middleware, which will handle the unhandled exception that occurred in your application.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGet("/", async context =>
        {
            throw new Exception("Error Occurred while processing your request");
            await context.Response.WriteAsync("Hello World!");
        });
    });
}

How to Customize the UseDeveloperExceptionPage Middleware in ASP.NET Core?

If you want, then you can also customize the UseDeveloperExceptionPage middleware. You need to remember whenever you want to customize a middleware component in ASP.NET Core. Then you need to use the respective Options object. For example

1. UseDeveloperExceptionPage => To customize UseDeveloperExceptionPage middleware, we need to use the DeveloperExceptionPageOptions object.
2. UseDefaultFiles => To customize UseDefaultFiles middleware, use the DefaultFilesOptions object
3. UseStaticFiles => To customize UseStaticFiles middleware, use the StaticFileOptions object
4. UseFileServer => To customize UseFileServer middleware, use the FileServerOptions object

As we will customize the UseDeveloperExceptionPage() middleware component, we need to use the DeveloperExceptionPageOptions object. So, modify the Main method of the Program class as shown below.

namespace FirstCoreWebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            var app = builder.Build();

            //If the Environment is Development, Please Show the Unhandled Exception Details 
            if (app.Environment.IsDevelopment())
            {
                //Create an Instance of DeveloperExceptionPageOptions to Customize
                //UseDeveloperExceptionPage Middleware Component
                DeveloperExceptionPageOptions developerExceptionPageOptions = new DeveloperExceptionPageOptions
                {
                    SourceCodeLineCount = 5
                };

                //Passing DeveloperExceptionPageOptions Instance to UseDeveloperExceptionPage Middleware Component
                app.UseDeveloperExceptionPage(developerExceptionPageOptions);
            }

            app.MapGet("/", async context =>
            {
                int Number1 = 10, Number2 = 0;
                int Result = Number1 / Number2; //This statement will throw Runtime Exception
                await context.Response.WriteAsync($"Result : {Result}");
            });

            //This will Start the Application
            app.Run();
        }
    }
}

As you can see in the above code, we are using one property called SourceCodeLineCount. The SourceCodeLineCount property of DeveloperExceptionPageOptions class specifies the number of lines of code to include before and after the line of code that caused the exception.

Now if you run the application with the above changes in place, you will get the following error. Please have a look at the line number of the error, i.e., 28. And also, please look at the number of lines before and after the error line.

Where do we need to Configure the UseDeveloperExceptionPage Middleware?

We need to configure the UseDeveloperExceptionPage() Middleware as early as possible in the application’s Request Processing Pipeline so that it can handle the unhandled exception and then display the Developer Exception Page with detailed information about the exception.

Note: From .NET6 application, no need to configure developer exception page middleware explicitly. By default, the Framework will load the developer exception page if the environment variable is Development.

In the next article, I am going to discuss How to Create, Build, and Run ASP.NET Core Applications using .NET Core CLI (Command Line Interface) Commands. In this article, I try to explain How to handle an unhandled exception using Developer Exception Page Middleware Component in ASP.NET Core Web Application with Examples. I hope this article will help you to understand the Developer Exception Page Middleware in ASP.NET Core Web Applications.