Document System.Text.Json features in .NET 11 - #55467
Draft
eiriktsarpalis wants to merge 1 commit into
Draft
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0d38be7f-79b2-4e2a-9eb4-f7266c6ca5ac
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request updates System.Text.Json documentation for .NET 11 by adding new conceptual coverage (notably C# union serialization) and refreshing several existing articles and .NET 11 “What’s new” content to reflect new APIs and behaviors.
Changes:
- Adds a new conceptual article that documents C# union serialization and customization.
- Updates existing
System.Text.Jsonguidance to cover .NET 11 features across polymorphism, source generation, supported types, naming, ignore behavior, schema export, extension data, and writer reuse. - Updates .NET 11 library highlights content, navigation, and snippets to reference and demonstrate the new features.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/standard/serialization/system-text-json/use-utf8jsonwriter.md | Adds writer reuse guidance via Utf8JsonWriter.Reset(...) and AI usage frontmatter. |
| docs/standard/serialization/system-text-json/union-types.md | New article describing C# union serialization, classification, and source generation. |
| docs/standard/serialization/system-text-json/supported-types.md | Expands supported types coverage (JSON Lines, IReadOnlySet<T>, numeric types, and F# DU notes) and updates wording. |
| docs/standard/serialization/system-text-json/source-generation-modes.md | Updates source-generation guidance for non-public members/constructors and clarifies fast-path limitations. |
| docs/standard/serialization/system-text-json/reflection-vs-source-generation.md | Refreshes comparison text and adds a note about F# discriminated unions being reflection-only. |
| docs/standard/serialization/system-text-json/polymorphism.md | Adds closed-hierarchy inference guidance and open generic derived-type registration guidance. |
| docs/standard/serialization/system-text-json/immutability.md | Updates constructor binding guidance (including by-ref parameters, init-only behavior, and non-public support). |
| docs/standard/serialization/system-text-json/ignore-properties.md | Adds new section documenting type-level ignore conditions and precedence rules. |
| docs/standard/serialization/system-text-json/handle-overflow.md | Updates extension-data guidance (including IReadOnlyDictionary materialization and JsonObject flattening). |
| docs/standard/serialization/system-text-json/extract-schema.md | Updates schema exporter doc and adds new numeric converter/schema notes. |
| docs/standard/serialization/system-text-json/customize-properties.md | Adds PascalCase policy entry and documents per-type/member naming policy via attribute. |
| docs/standard/serialization/system-text-json/custom-contracts.md | Adds strongly typed GetTypeInfo<T>/TryGetTypeInfo<T> guidance and references union contract kind. |
| docs/standard/serialization/system-text-json/converters-how-to.md | Updates open generic converter guidance and clarifies behavior/error notes. |
| docs/fundamentals/toc.yml | Adds navigation entry for the new “Serialize union types” article. |
| docs/core/whats-new/dotnet-11/snippets/csharp/Libraries.cs | Updates/extends .NET 11 snippet code to match new features and examples. |
| docs/core/whats-new/dotnet-11/overview.md | Updates the .NET 11 overview bullet for System.Text.Json improvements. |
| docs/core/whats-new/dotnet-11/libraries.md | Reworks the System.Text.Json improvements section to align with the expanded .NET 11 documentation set. |
Suppressed comments (2)
docs/standard/serialization/system-text-json/polymorphism.md:610
- This open-generic polymorphism example declares
Base<T>andDerived<T>using semicolon-terminatedclassdeclarations, which doesn't compile. Use empty bodies ({ }) for the type declarations.
[JsonDerivedType(typeof(Derived<>), "derived")]
public class Base<T>;
public class Derived<T> : Base<T>;
docs/standard/serialization/system-text-json/supported-types.md:134
- This heading uses a gerund ("Streaming"), which conflicts with the repo's Markdown style guidance to avoid gerunds in headings. Consider reverting to the previous non-gerund heading text.
##### Streaming deserialization
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+572
to
+575
| [JsonPolymorphic(InferClosedTypePolymorphism = true)] | ||
| public closed class Shape; | ||
| public sealed class Circle : Shape; | ||
| public sealed class Square : Shape; |
| The following examples use streams to represent asynchronous data sources. Sources include local files, database query results, and web service API responses. | ||
|
|
||
| ##### Stream serialization | ||
| ##### Streaming serialization |
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.
Summary
Documents the 15
System.Text.Jsonwork items tracked by #55465. The change adds a conceptual article for C# union serialization, expands polymorphism and source-generation guidance, updates the supported-type and customization references, and completes the .NET 11 library highlights.Fixes #55465
Content source breakdown
Stream, andPipeWriterbehavior follows the implementation tests.BFloat16,Decimal32,Decimal64, andDecimal128.IReadOnlyDictionarymaterialization andJsonObjectflattening.IReadOnlySet<T>Utf8JsonWriter.ResetoptionsExpert review notes
All modified Markdown identifies the work as
ai-assisted.The new union article, structural-classifier behavior, closed-hierarchy RC1 APIs, and new numeric converters warrant focused API-owner review. The locally available .NET 11 Preview 7 SDK predates some of those merged/backported APIs, so their descriptions and examples were checked against the corresponding runtime tests and API proposals rather than executed against that SDK. The union, polymorphism, naming, ignore, extension-data, collection, metadata, writer, JSONL, C#, Visual Basic, and F# examples that Preview 7 contains were compiled or executed locally.
Validation
docs/core/whats-new/dotnet-11/snippets/csharp/snippets.csproj: build succeeded with .NET SDK11.0.100-preview.7and 0 warnings.IReadOnlySet<T>, generic metadata lookup, writer reset, by-reference constructors, and JSON Lines output."Point"and{"$type":"Circle","radius":3.14}for the documented discriminated union.git diff --checkcompleted without errors.Internal previews
Toggle expand/collapse