Skip to content

Clarify StatusCodePages ProblemDetails docs#66172

Open
mikekistler wants to merge 1 commit intodotnet:mainfrom
mikekistler:docs/clarify-statuscodepages-problemdetails
Open

Clarify StatusCodePages ProblemDetails docs#66172
mikekistler wants to merge 1 commit intodotnet:mainfrom
mikekistler:docs/clarify-statuscodepages-problemdetails

Conversation

@mikekistler
Copy link
Copy Markdown
Contributor

Summary

  • clarify that UseStatusCodePages() and the default options handler prefer Problem Details when IProblemDetailsService is available
  • document the plain-text fallback behavior in the XML comments

Copilot AI review requested due to automatic review settings April 6, 2026 16:11
@github-actions github-actions bot added the area-middleware Includes: URL rewrite, redirect, response cache/compression, session, and other general middlewares label Apr 6, 2026
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the XML documentation for Status Code Pages to clarify that the default handler prefers emitting ProblemDetails (via IProblemDetailsService) and otherwise falls back to a plain-text response.

Changes:

  • Updated StatusCodePagesOptions XML docs to describe the ProblemDetails-first behavior and fallback conditions.
  • Updated UseStatusCodePages() XML docs to describe default handler behavior (ProblemDetails vs plain text).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File Description
src/Middleware/Diagnostics/src/StatusCodePage/StatusCodePagesOptions.cs Clarifies the default HandleAsync behavior: try IProblemDetailsService, then fall back to plain text.
src/Middleware/Diagnostics/src/StatusCodePage/StatusCodePagesExtensions.cs Updates UseStatusCodePages() docs to describe default handler behavior (needs a small accuracy tweak re: fallback).

Comment on lines +38 to +39
/// when an <see cref="IProblemDetailsService"/> is available, generates a <see cref="ProblemDetails"/>
/// response. Otherwise, it generates a plain text response that includes the status code.
Copy link

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The XML doc for UseStatusCodePages() implies that if IProblemDetailsService is available it will always generate a ProblemDetails response, with plain text only when the service is unavailable. In practice, the default handler also falls back to plain text when IProblemDetailsService.TryWriteAsync(...) returns false (e.g., due to content negotiation). Please update this doc to reflect the same fallback behavior described in StatusCodePagesOptions.

Suggested change
/// when an <see cref="IProblemDetailsService"/> is available, generates a <see cref="ProblemDetails"/>
/// response. Otherwise, it generates a plain text response that includes the status code.
/// when an <see cref="IProblemDetailsService"/> is available, attempts to generate a
/// <see cref="ProblemDetails"/> response. If the service is unavailable or cannot write the response,
/// it generates a plain text response that includes the status code.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-middleware Includes: URL rewrite, redirect, response cache/compression, session, and other general middlewares

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants