What's New 11 P2 follow up suggestions

[wadepickett]

Description

Issue #36858 — What's New 11 P2 Follow-Up Fixes

Summary

PR #36856 (Add ASP.NET Core .NET 11 Preview 2 release notes include files) was merged with several outstanding review suggestions from @guardrex (and notes from @wadepickett and @tdykstra) that were not applied before merge. This follow-up issue tracks applying all of those unresolved changes.

---

Outstanding Changes to Apply

1. aspnetcore/release-notes/aspnetcore-11.md — Fix absolute link (should be relative)

Line 67 (current):

Use the articles in [Breaking changes in .NET]([/dotnet/core/compatibility/breaking-changes](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes)) to find breaking changes that might apply when upgrading an app to a newer version of .NET.

Should be (per @guardrex suggestion):

Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET.

The merged version has a malformed link with the relative path nested inside the absolute URL as the href target. It should use only the relative /dotnet/core/compatibility/breaking-changes path, which is the standard pattern for learn.microsoft.com cross-references.

---

2. aspnetcore/release-notes/aspnetcore-11/includes/native-otel-tracing-preview2.md — Reword sentence (line 14)

Current:

No additional instrumentation library (such as `OpenTelemetry.Instrumentation.AspNetCore`) is needed. The framework now directly populates semantic convention attributes like `http.request.method`, `url.path`, `http.response.status_code`, and `server.address` on the request activity.

Should be (per @guardrex suggestion):

No additional instrumentation library (such as `OpenTelemetry.Instrumentation.AspNetCore`) is needed. The framework now directly populates semantic convention attributes on the request activity, such as `http.request.method`, `url.path`, `http.response.status_code`, and `server.address`.

Moves the attribute list to the end of the sentence for improved readability.

---

3. aspnetcore/release-notes/aspnetcore-11/includes/infer-passkey-display-name-preview2.md — Fix wording and remove file extension (line 5)

Current:

For known authenticators, the name is automatically assigned without prompting the user. For unknown authenticators, the user is redirected to a rename page. Developers can extend the mappings by adding entries to the `PasskeyAuthenticators.cs` dictionary in their project.

Should be (per @guardrex suggestion):

For known authenticators, the name is automatically assigned without prompting the user. For unknown authenticators, the user is redirected to a rename page. Extend the mappings by adding entries to the `PasskeyAuthenticators` dictionary in the project.

Removes Developers can (unnecessary preamble), drops the .cs file extension (referring to the dictionary/API, not the file), and changes "their" to "the".

---

4. aspnetcore/release-notes/aspnetcore-11/includes/openapi-3-2-support-preview2.md — Three changes

4a. Reword intro paragraph (line 3)

Current:

`Microsoft.AspNetCore.OpenApi` now supports OpenAPI 3.2.0 through an updated dependency on `Microsoft.OpenApi` 3.3.1. This update includes breaking changes from the underlying library — see the [Microsoft.OpenApi upgrade guide](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-3.md) for details.

Should be (per @guardrex suggestion):

`Microsoft.AspNetCore.OpenApi` now supports OpenAPI 3.2.0 through an updated dependency on `Microsoft.OpenApi` 3.3.1. This update includes breaking changes from the underlying library. For more information, see the [Microsoft.OpenApi upgrade guide](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-3.md).

Replaces the em dash + "see ... for details" pattern with the standard "For more information, see ..." docs phrasing.

4b. Use xref for AddOpenApi (line 5)

Current:

To generate an OpenAPI 3.2.0 document, specify the version when calling `AddOpenApi()`:

Should be (per @guardrex suggestion):

To generate an OpenAPI 3.2.0 document, specify the version when calling <xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A>:

Replaces the inline code reference with a proper <xref:> link to the API documentation.

4c. Change future tense to present tense (line 14)

Current:

Subsequent updates will take advantage of new capabilities in the 3.2.0 specification, such as item schema support for streaming events.

Should be (per @guardrex suggestion):

Subsequent updates take advantage of new capabilities in the 3.2.0 specification, such as item schema support for streaming events.

Changes "will take" (future) to "take" (present) — the What's New article is cumulative and shouldn't imply future work.

---

5. aspnetcore/release-notes/aspnetcore-11/includes/performance-improvements-preview2.md — Use xref for BadHttpRequestException (line 3)

Current:

...Instead of throwing `BadHttpRequestException` on every parse failure...

Should be (per @guardrex suggestion):

...Instead of throwing <xref:Microsoft.AspNetCore.Http.BadHttpRequestException> on every parse failure...

Replaces the inline code reference with a proper <xref:> link to the API documentation.

---

Additional Notes (from @wadepickett's own review comments — not blocking, but noted for future PRs)

• infer-passkey-display-name-preview2.md: Needs a link to PasskeyAuthenticators.cs in the ASP.NET Core source — pending verification that the Preview 2 change is in that specific file. (comment)
• native-otel-tracing-preview2.md: The code sample uses AddConsoleExporter() which requires the OpenTelemetry.Exporter.Console NuGet package, but this isn't mentioned. Consider adding a note or NuGet link in a future update. (comment)

---

Files to Modify

#	File	Changes
1	aspnetcore/release-notes/aspnetcore-11.md	Fix malformed Breaking Changes link (absolute → relative)
2	aspnetcore/release-notes/aspnetcore-11/includes/native-otel-tracing-preview2.md	Reword attribute list sentence
3	aspnetcore/release-notes/aspnetcore-11/includes/infer-passkey-display-name-preview2.md	Remove .cs extension, simplify wording
4	aspnetcore/release-notes/aspnetcore-11/includes/openapi-3-2-support-preview2.md	Reword intro, use <xref:> for AddOpenApi, fix tense
5	aspnetcore/release-notes/aspnetcore-11/includes/performance-improvements-preview2.md	Use <xref:> for BadHttpRequestException

Page URL

https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-11?view=aspnetcore-10.0&tabs=minimal-apis

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/release-notes/aspnetcore-11.md

Document ID

5f749050-bd63-c782-f5a6-834dbaa7a1bc

Platform Id

e8eaff50-8e78-f831-b4d1-c5309fcb547e

Article author

@wadepickett

Metadata

• ID: 5f749050-bd63-c782-f5a6-834dbaa7a1bc
• PlatformId: e8eaff50-8e78-f831-b4d1-c5309fcb547e
• Service: aspnet-core
• Sub-service: release-notes

Related Issues

---

Associated WorkItem - 560231