Document ASP.NET Core breaking changes in .NET 11#37228
Open
halter73 wants to merge 4 commits into
Open
Conversation
Adds 12 per-entry pages plus an overview under aspnetcore/breaking-changes/11/ and wires them into aspnetcore/toc.yml under the existing ASP.NET Core 11 group, mirroring the .NET 10 layout established in #36693. Relative category links (../../categories.md#...) rewritten to the absolute /dotnet/core/compatibility/categories#... form used elsewhere in this repo. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
halter73
requested review from
BrennanConroy,
DeagleGross,
Youssef1313,
guardrex and
javiercn
BrennanConroy
approved these changes
Jun 4, 2026
| Kestrel in ASP.NET Core 11 makes two HTTP-protocol-compliance changes: | ||
|
|
||
| - HTTP/2 and HTTP/3 reject more connection-specific request headers, per RFC 9113 §8.2.2 and RFC 9114 §4.2. | ||
| - HTTP/1.1 closes the connection after a request that included both `Content-Length` and `Transfer-Encoding`, per the updated wording of RFC 9112. |
Member
There was a problem hiding this comment.
nit: This was done for all versions of kestrel (and iis and httpsys). Not sure it needs calling out either.
guardrex
approved these changes
Jun 4, 2026
Collaborator
There was a problem hiding this comment.
Style NITs only. All updates applied. Looks GrEaT!
I also checked the Blazor breaking changes against the docs, and I don't see where reference content requires an update.
@tdykstra ... I noted a couple of reference articles that probably require updates for the breaking change on the Microsoft.Extensions.Caching.SqlServer package ...
BTW ... The metadata isn't in the correct order ( Done! 👍ai-usage: ai-assisted should under the title), but it's trivial if it isn't changed.
Contributor
…eaking changes documentation (#37229) * Initial plan * Move ai-usage metadata under title in breaking changes docs --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
guardrex
reviewed
Jun 4, 2026
guardrex
reviewed
Jun 4, 2026
Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com>
DeagleGross
reviewed
Jun 5, 2026
| description: "Learn about the breaking change in ASP.NET Core 11 where the generated OpenAPI document's servers[0].url no longer ends with a trailing slash when the request PathBase is empty." | ||
| ms.date: 06/04/2026 | ||
| --- | ||
| # OpenAPI server URL no longer has a trailing slash when PathBase is empty |
Member
There was a problem hiding this comment.
Should we call out multiple-produces in OpenAPI as well? I can push another doc here: dotnet/aspnetcore#65650
| # Kestrel tightens HTTP protocol compliance | ||
|
|
||
| Kestrel in ASP.NET Core 11 makes two HTTP-protocol-compliance changes: | ||
|
|
Member
There was a problem hiding this comment.
I did not merge it yet, but wanted to do now: should we also note about change of default for CRLF https://github.com/dotnet/aspnetcore/pull/66807/changes?
Member
Author
There was a problem hiding this comment.
Yes. I think that's worth adding once we merge.
Per BrennanConroy's nit on #37228 (acknowledged by halter73), call out that the HTTP/1.1 connection-close behavior for requests with both Content-Length and Transfer-Encoding is also being shipped to earlier Kestrel versions and to IIS and HTTP.sys. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ports dotnet/docs#54188 into this repo, per the .NET 10 precedent (#36693). The ASP.NET Core breaking-change content now lives in
dotnet/AspNetCore.Docsrather thandotnet/docs.Adds 12 new per-entry pages plus an overview under
aspnetcore/breaking-changes/11/, and wires them intoaspnetcore/toc.ymlunder the existingASP.NET Core 11group, mirroring theASP.NET Core 10block.Process disclosure
A prior agent audited the 975 first-parent merges that landed on
dotnet/aspnetcoremainsince therelease/10.0branch point and produced a candidate list of 16 verified 11-only breaking changes, with citations to each PR. The original docs pass was dotnet/docs#54188; this PR ports those pages over with relative category links rewritten to the absolute/dotnet/core/compatibility/categories#…form used elsewhere in this repo. Both agents are Claude models running with Copilot CLI; both pages and this PR description are AI-assisted and marked accordingly (ai-usage: ai-assistedin front matter).Entries
Vary: Accept-EncodingAll 12 PRs were verified
release/10.0..main-only viagit merge-base --is-ancestoragainst the merge SHA. PR dates are not reliable because some 11-only PRs report a GitHub "merged" date earlier than the branch point (e.g., #63544).Decisions worth a second look
dotnet/aspnetcore#65686("Replace Newtonsoft.Json with System.Text.Json in dotnet-user-secrets"). The audit rated it low-confidence: the only visible difference is thatsecrets.jsonon disk now uses\u00XXescapes for non-ASCII, butIConfigurationunescapes those at read time so app code is unaffected. Add it back if you want a tooling-only callout.Microsoft.AspNetCore.ConcurrencyLimiter9.x and 10.x are still on NuGet and recommended them as a short-term escape hatch. Reasonable?SignInManager<TUser>.PreSignInCheckto bypass the new checks for passkey sign-in. That was unsafe:PreSignInCheckdoesn't know which sign-in method called it, so the override would affect every sign-in path. I removed that paragraph and replaced it with "update user records (e.g., mark the email as confirmed) rather than removing the checks." Please confirm that's the guidance you'd give.OpenApiSchematoIOpenApiSchema. The transformer interfaces actually still takeOpenApiSchema(I verified against the currentIOpenApiSchemaTransformerindotnet/aspnetcore); what changed is the surface area of the nested types it exposes (extensions areJsonNodenow instead ofOpenApiAny, nested schema collections exposeIOpenApiSchema, etc.). I rewrote that section. Could use a second look from an OpenAPI SME.Things I'm explicitly flagging
aspnetcore/mainsince the .NET 10 branch point through approximately 2026-06-03; anything merged since then isn't covered..NET 10entries (e.g.,aspnetcore/breaking-changes/10/cookie-authentication-api-endpoints.md). The Microsoft Style Guide pass — active voice, no gerund leads, lead-with-reason — was applied to the new content; a documentarian eye on phrasing is still welcome.Port notes
dotnet/docs→aspnet/core/breaking-changes/11/overviewredirect is owned bydotnet/docsand is out of scope for this PR.../../categories.md#…links rewritten to the absolute/dotnet/core/compatibility/categories#…form already used inaspnetcore/breaking-changes/10/.Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Internal previews
Toggle expand/collapse