How to use the Developer Exception Page in ASP.NET Core

By FoxLearn 2/26/2025 4:11:14 AM 29

The Developer Exception Page in ASP.NET Core is a useful feature that helps developers troubleshoot errors during development by providing detailed error information, stack traces, and request data.

Developers often need this level of detail to debug issues, while end-users do not. To prevent exposing sensitive error information to users, the Developer Exception Page is activated only in the Development environment by default in ASP.NET Core.

In ASP.NET Core, the Developer Exception Page feature is part of the Microsoft.AspNetCore.Diagnostics package, but it is included by default in the web application template.

Handling Errors in an ASP.NET Core Web API

Consider the following code where an exception is intentionally thrown in the Configure method of the Startup class for a Web API:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
    throw new Exception("Something went wrong in the application!");
}

When running this application, you’ll encounter an error.

However, by default, the error messages will not provide enough detail to effectively troubleshoot the issue.

Developer Exception Page in the Development Environment

In a Development environment, the Developer Exception Page middleware is used to provide detailed error messages. These messages can assist in debugging by showing critical details, including the stack trace, query parameters, cookies, headers, and routing information.

In a newly created ASP.NET Core Web API project, the following code will be automatically generated within the Configure method of the Startup class to enable the Developer Exception Page in development:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    if (env.IsDevelopment()) {
        app.UseDeveloperExceptionPage();
    } else {
        app.UseExceptionHandler("/Home/Error");
    }
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

This ensures that detailed error pages are displayed only when the application is running in the Development environment. If the application is running in Production, these detailed error messages are hidden to prevent exposing sensitive information to users.

How the Developer Exception Page Works

The Developer Exception Page middleware is added early in the application's request pipeline. This ensures that any exception raised by later middleware will be captured and displayed in a detailed, developer-friendly format. The middleware breaks the error information into five sections: Stack Trace, Query String, Cookies, Headers, and Routing, making it easier to pinpoint the issue.

Exception Handling in Production Environment

In Production environments, displaying detailed exception information can be a security risk. Therefore, a different approach is needed. ASP.NET Core uses the UseExceptionHandler extension method to manage errors in production.

For example, How to handle exceptions using a custom error page in production:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    if (env.IsDevelopment()) {
        app.UseDeveloperExceptionPage();
    } else {
        app.UseExceptionHandler("/Error");
    }
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

This setup ensures that when an exception occurs in a production environment, the user is redirected to a user-friendly error page at /Error.

Custom Error Handling with Lambda Expressions

In some cases, you may want to customize the error handling further. This can be done using a lambda expression in the UseExceptionHandler method.

Here’s an example of a custom error handler:

app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;
        context.Response.ContentType = "text/html";
        await context.Response.WriteAsync("<html lang=\"en\"><body>");
        await context.Response.WriteAsync("An unexpected error occurred...<br><br>");
        await context.Response.WriteAsync("</body></html>");
        await context.Response.WriteAsync(new string(' ', 512));
    });
});

In this example, if an error occurs in the production environment, the application will respond with a generic HTML page indicating an error, instead of showing detailed technical information.

In an ASP.NET Core Web API, the Developer Exception Page is a useful tool for debugging during development by providing detailed error information. This page is enabled only in the Development environment to prevent exposing sensitive information to end-users. For production environments, you should configure custom error handling with the UseExceptionHandler method to display friendly error pages or custom error messages.