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 in ASP.NET Core application. Please read our previous article where we discussed How to configure the Default Page in ASP.NET Core Application. The exception handling is one of the key features of any application. We can handle the exception in many different ways. But in this article, we are going to discuss how we can use the Developer Exception Page Middleware to handle the unhandled exception. 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. By default, ASP.NET Core application simply returns a status code for an exception that is not handled by the application. Let us understand this with an example. Please modify the Configure() method of the startup class as shown below where we throw an exception.

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

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

As you can see in the above image it gives you the status code as 500 which means Internal Server Error. But as a developer when you are developing the application, you should know the detailed information about the exception on the page so that you can take necessary actions to fix the error. And this where DeveloperExceptionPage Middleware comes into the picture.

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

If you want your application to display a page that shows the detailed information about the unhandled exception, then you need to configure the Developer Exception Page middleware in the request processing pipeline. To do so, 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!");
        });
    });
}

With the above change in place, now run the application and it should display the following page with the detailed information about the unhandled exception.

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

1. Stack: The Stack tab gives the information of stack trace which indicated where exactly the exception occurred, the file name, and the line number that causes 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 makes the request.
5. Route: The Route tab gives information about the Route Pattern and Route HTTP Verb type of the method, etc.

Now if you verify the Query tab and Cookies tab, then you will not see any information as you are not passing any query string value in the URL or you are not setting the cookies in the request. In our upcoming articles, we will discuss the Query string and Cookies 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 Customize the UseDeveloperExceptionPage Middleware in ASP.NET Core?

If you want then you can also customize the UseDeveloperExceptionPage middleware. The point that you need to remember is 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 this middleware use DeveloperExceptionPageOptions object
2. UseDefaultFiles => to customize this middleware use DefaultFilesOptions object
3. UseStaticFiles => to customize this middleware use StaticFileOptions object
4. UseFileServer => to customize this middleware use FileServerOptions object

As we are going to customize the UseDeveloperExceptionPage() middleware component, so we need to use the DeveloperExceptionPageOptions object. So, modify the Configure method of the Startup class as shown below.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        DeveloperExceptionPageOptions developerExceptionPageOptions = new DeveloperExceptionPageOptions
        {
            SourceCodeLineCount = 5
        };

        app.UseDeveloperExceptionPage(developerExceptionPageOptions);
    }

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

As you can see in the above code, we are using one property called SourceCodeLineCount. The SourceCodeLineCount property of the 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, then you will get the following error. Please have a look at the line number of the error i.e. 39. And also please look at the numbers 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 the detailed information about the exception.

Let us see what happened when we configure the UseDeveloperExceptionPage() middleware after the middleware which is causing the exception. Please modify the Configure() method as shown below.

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

    if (env.IsDevelopment())
    {
        DeveloperExceptionPageOptions developerExceptionPageOptions = new DeveloperExceptionPageOptions
        {
            SourceCodeLineCount = 5
        };

        app.UseDeveloperExceptionPage(developerExceptionPageOptions);
    }
}

With the above changes in place, when we run the application, it will not display the developer’s exception page instead of simply returns the default error status code. This is the reason why we need to configure the UseDeveloperExceptionPage() middleware as early as possible to handle the unhandled exception of the application in the request processing pipeline.

In the next article, I am going to discuss how to create, build, and run ASP.NET Core Application 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 in ASP.NET Core application. I hope this article will help you to understand the Developer Exception Page Middleware in ASP.NET Core Application.