StatusCodePagesMiddleware

As explained in ASP.NET Core in Action, 3e

StatusCodePagesMiddleware is ASP.NET Core middleware that generates or modifies responses for HTTP status codes, including adding a body to error responses that lack one.

StatusCodePagesMiddleware intercepts error HTTP responses that lack a body and supplies a useful response. It can add Problem Details for APIs or generate friendly HTML error pages for Razor Pages applications. section 5.3.3 section 15.5

Choose the handling style that matches the application:

• Call UseStatusCodePages() to intercept empty 4xx and 5xx responses and apply the configured response behavior. section 15.5
• Pair UseStatusCodePages() with AddProblemDetails() to give API errors, including automatic 404 responses, a consistent Problem Details body. section 5.3.3
• Use UseStatusCodePagesWithReExecute("/{0}") to rerun the pipeline through a status-code-specific path and render an HTML error page. section 15.5
• Use UseStatusCodePagesWithRedirects("/{0}") when the error experience should involve a separate browser request, while recognizing that the original response becomes a redirect. section 15.5

Consistent Problem Details for a missing endpoint

WebApplicationBuilder builder = WebApplication.CreateBuilder(args); builder.Services.AddProblemDetails(); WebApplication app = builder.Build(); app.UseStatusCodePages(); app.MapGet("/", () => Results.NotFound()); app.Run(); The 404 response has no body, so the middleware adds a Problem Details body. Place it early in the pipeline so it can handle errors produced by later middleware. section 5.3.3 section 15.5

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

Shows the compact reexecution configuration used to route status-code errors through an error path. section 15.5

Figure 15.6 StatusCodePagesMiddleware reexecuting the pipeline to generate an HTML body for a 404 response. A request to the / path returns a 404 response, which is handled by the status code middleware. The pipeline is reexecuted using the /404 path to generate the HTML response.

Illustrates how a 404 response can reexecute the pipeline through /404 to produce an HTML response. section 15.5

How ASP.NET Core in Action, 3e covers it

How deep it goes

Explains interception, pipeline placement, Problem Details integration, reexecution, and redirects without detailing middleware internals.

Examples

Uses unmatched URLs, Results.NotFound(), missing products, reexecuted /404 paths, and redirected error paths.

What you can do after

Operate/configure it with UseStatusCodePages, AddProblemDetails, reexecution, or redirects for API and Razor Pages error handling.

How it connects

Connects HTTP status codes with Problem Details, exception-handling middleware, middleware pipelines, Razor Pages, and redirects.

liveBookmanning.com

Read ASP.NET Core in Action, 3e on liveBook Get the book at manning.com

Related concepts

• UseStatusCodePagesconfigured by · UseStatusCodePages is an ASP.NET Core application-builder method that adds middleware for enriching eligible HTTP status-code responses with content.
• UseStatusCodePagesWithReExecuteconfigured by · UseStatusCodePagesWithReExecute is an ASP.NET Core application-builder method that configures status-code middleware to rerun requests through an alternative URL.
• Problem Detailsproduces · Problem Details is a standardized HTTP response format for communicating machine-readable information about a problem occurrence, commonly serialized as JSON.
• error responseuses · An error response is a server or API response that communicates that a request or operation was unsuccessful and may provide details about the failure.
• middlewarepart of · Middleware is an intermediate software component or layer that processes or mediates requests, messages, or operations between other components, often adding behavior or controlling their flow.

This explainer was generated by Manning's knowledge graph from the text of ASP.NET Core in Action, 3e. The section links point to the parts of the book it draws on.