Clarify StatusCodePages ProblemDetails docs#66172
Clarify StatusCodePages ProblemDetails docs#66172mikekistler wants to merge 1 commit intodotnet:mainfrom
Conversation
There was a problem hiding this comment.
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
StatusCodePagesOptionsXML docs to describe theProblemDetails-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). |
| /// 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. |
There was a problem hiding this comment.
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.
| /// 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. |
Summary
UseStatusCodePages()and the default options handler prefer Problem Details whenIProblemDetailsServiceis available