Skip to content

Clarify IExceptionHandler requirements and fallback behavior in error-handling docs - #37452

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

Clarify IExceptionHandler requirements and fallback behavior in error-handling docs#37452
tdykstra with Copilot wants to merge 2 commits into
mainfrom
copilot/fix-iexceptionhandler-section

Conversation

Copilot AI commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

The IExceptionHandler guidance implied DI registration alone was sufficient and omitted critical runtime behaviors around middleware configuration, duplicate logging, and handled-without-response outcomes. This update aligns .NET 10 and versioned includes with the actual middleware execution model.

  • IExceptionHandler setup requirements (all targeted docs)

    • Added an explicit IMPORTANT note: AddExceptionHandler<T>() does not execute handlers unless UseExceptionHandler(...) middleware is also added.
    • Updated the registration walkthrough text to describe both registration and middleware wiring.
    • Updated snippet highlighting to emphasize both required lines.
  • UseExceptionHandler fallback configuration

    • Added a new subsection explaining why parameterless UseExceptionHandler() can throw at startup when no fallback is configured.
    • Documented supported fallback patterns:
      • error path,
      • problem details (AddProblemDetails + UseExceptionHandler()),
      • explicit fallback lambda.
    • Clarified that IExceptionHandler implementations still run first; middleware fallback runs only when all handlers return false.
  • Handled exception response semantics

    • Added guidance for TryHandleAsync returning true:
      • remaining handlers are skipped,
      • middleware error page/path/lambda is not used,
      • handler must produce the full response.
    • Documented 404 + warning behavior when a handler returns true without writing status/body, and when to set AllowStatusCode404Response.
  • .NET 8/9 diagnostics behavior (versioned includes)

    • Added a .NET 8/9 note that middleware still logs/emits metrics for handled exceptions, which can cause duplicate logging if handlers also log.
    • Included category-filter configuration example and pointed to .NET 10 suppression behavior.
  • Metadata and scope

    • Updated ms.date in aspnetcore/fundamentals/error-handling.md to current date.
    • Reviewed error-handling-api.md for the same misleading pattern; no matching AddExceptionHandler-only guidance requiring edits was found.
builder.Services.AddExceptionHandler<CustomExceptionHandler>();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

Co-authored-by: tdykstra <1569635+tdykstra@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix misleading information in IExceptionHandler section Clarify IExceptionHandler requirements and fallback behavior in error-handling docs Aug 10, 2026
Copilot AI requested a review from tdykstra August 10, 2026 17:43
@tdykstra tdykstra closed this Aug 10, 2026
@tdykstra

Copy link
Copy Markdown
Contributor

Replaced by #37453

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