Breaking change doc: Nullable.GetUnderlyingType throws for custom Type subclasses (.NET 11)

[Copilot]

Closes #53407

In .NET 11 Preview 4, Nullable.GetUnderlyingType was changed to delegate to the new Type.GetNullableUnderlyingType() virtual. The base implementation throws NotSupportedException, so custom Type subclasses that don't override it now throw where they previously returned null.

Changes

• New article docs/core/compatibility/core-libraries/11/nullable-getunderlyingtype-throws.md — covers previous/new behavior, reason (fixes MetadataLoadContext nullable detection bug), and three override patterns:
  • Return null (subclass never represents Nullable<T>)
  • Inspect generic type definition and return the type argument
  • Delegate to an inner wrapped Type
• docs/core/compatibility/toc.yml — adds entry under .NET 11 / Core .NET libraries
• docs/core/compatibility/11.md — adds row to the Core .NET libraries breaking changes table

Affected APIs

• System.Nullable.GetUnderlyingType(System.Type)
• System.Type.GetNullableUnderlyingType (new virtual)

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/11.md	Breaking changes in .NET 11
docs/core/compatibility/core-libraries/11/nullable-getunderlyingtype-throws.md	Nullable.GetUnderlyingType throws for custom Type subclasses
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[AaronRobinsonMSFT]

@gewarren @jkotas These changes have been merged. I think it will be going into .NET 11 Preview 4 - dotnet/runtime#126905.

[Copilot]

Pull request overview

Adds a new .NET 11 breaking change article documenting that Nullable.GetUnderlyingType(Type) now forwards to Type.GetNullableUnderlyingType() and can throw NotSupportedException for custom Type subclasses that don’t override the new virtual.

Changes:

• Adds a new breaking change article describing the behavior change, rationale, and recommended override patterns.
• Updates the .NET compatibility TOC to include the new article under .NET 11 core libraries.
• Updates the .NET 11 breaking changes index table to reference the new article.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/core/compatibility/core-libraries/11/nullable-getunderlyingtype-throws.md	New breaking change article documenting the new forwarding behavior and mitigation guidance.
docs/core/compatibility/toc.yml	Adds the new breaking change article to the navigation tree.
docs/core/compatibility/11.md	Adds the new breaking change entry to the .NET 11 index table.

[AaronRobinsonMSFT]

@gewarren I'm seeing

Cross reference not found: 'System.Type.GetNullableUnderlyingType'.

in https://buildapi.docs.microsoft.com/Output/PullRequest/a3bda507-3390-de91-8f7f-26f90f4e5fc8/202604291851254639-53409/BuildReport?accessString=aa4585a1989a22ee47264fec513db0a7ccd24ebb715277e92091f33bdc1d25d9. Is this a real error?

[gewarren]

@gewarren I'm seeing

Cross reference not found: 'System.Type.GetNullableUnderlyingType'.

in https://buildapi.docs.microsoft.com/Output/PullRequest/a3bda507-3390-de91-8f7f-26f90f4e5fc8/202604291851254639-53409/BuildReport?accessString=aa4585a1989a22ee47264fec513db0a7ccd24ebb715277e92091f33bdc1d25d9. Is this a real error?

@AaronRobinsonMSFT Yes, it's a real error because that method isn't published in the .NET API reference. I assume this is a new API for Preview 4? We can either wait to merge this until the Preview 4 APIs are published, or we can just put the API name in backticks for now (instead of an xref).