Skip to content

Clarify IExceptionHandler middleware requirements - #37453

Draft
tdykstra with Copilot wants to merge 2 commits into
mainfrom
copilot/fix-iexceptionhandler-section-again
Draft

Clarify IExceptionHandler middleware requirements#37453
tdykstra with Copilot wants to merge 2 commits into
mainfrom
copilot/fix-iexceptionhandler-section-again

Conversation

Copilot AI commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

The IExceptionHandler docs implied that registering handlers with AddExceptionHandler<T>() was enough. They also omitted key runtime behaviors around bare UseExceptionHandler(), handled-exception logging in .NET 8/9, and 404 responses from handlers that don't write a response.

  • Middleware setup
    • Added an important note that registered IExceptionHandler implementations only run when exception handling middleware is added.
    • Updated the registration example to show both AddExceptionHandler<T>() and UseExceptionHandler(...).
builder.Services.AddExceptionHandler<CustomExceptionHandler>();

// ...

app.UseExceptionHandler("/Error");
  • UseExceptionHandler configuration

    • Added guidance that parameterless UseExceptionHandler() requires a fallback through an error path, problem details, or a fallback handler.
    • Clarified that registered handlers run before the configured fallback and the fallback is used only when all handlers return false.
  • Handled exception behavior

    • Documented that handlers returning true stop later handlers and must write the full response.
    • Added the 404/AllowStatusCode404Response warning for handlers that return true without setting a response.
  • Version-specific diagnostics

    • Added .NET 8/9 guidance that middleware diagnostics are still emitted for handled exceptions and showed how to filter the middleware log category.
    • Left .NET 10 guidance aligned with the existing diagnostics suppression section.

Internal previews

File Preview link
aspnetcore/fundamentals/error-handling.md aspnetcore/fundamentals/error-handling
aspnetcore/fundamentals/error-handling/includes/error-handling8.md aspnetcore/fundamentals/error-handling/includes/error-handling8
aspnetcore/fundamentals/error-handling/includes/error-handling9.md aspnetcore/fundamentals/error-handling/includes/error-handling9

Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix misleading IExceptionHandler documentation in error-handling.md Clarify IExceptionHandler middleware requirements Aug 10, 2026
Copilot AI requested a review from tdykstra August 10, 2026 18:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants