Skip to content

update AGENTS.md file for System.Text.Json #52302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
kartheekp-ms wants to merge 9 commits into
base: llmstxt
Choose a base branch
from
+27 −39
Draft

update AGENTS.md file for System.Text.Json #52302

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
55e1d3f
Update System.Text.Json llms.txt
kartheekp-ms Mar 13, 2026
a193fda
Revise System.Text.Json documentation
kartheekp-ms Mar 13, 2026
e70a553
Update llms.txt with .NET 10 JSON serialization features
kartheekp-ms Mar 13, 2026
dc10686
Fix formatting in llms.txt for serialization update
kartheekp-ms Mar 13, 2026
ab61ab7
Update llms.txt with .NET 10 changes
kartheekp-ms Mar 16, 2026
229cb34
Clarify property name conflict validation message
kartheekp-ms Mar 16, 2026
8847e58
remove topics from the llms.txt
kartheekp-ms Mar 19, 2026
ed61ea2
Rename llms.txt to llms.md
kartheekp-ms Mar 24, 2026
927ca55
Add AGENTS.md documentation for system text JSON
kartheekp-ms Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions docs/standard/serialization/system-text-json/llms.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,25 @@

> High-performance JSON serialization and deserialization for .NET applications.

*Topics available: 31*
## What's New in .NET 10

**.NET 10 adds:** `JsonSerializerOptions.Strict` preset for best-practice defaults, `AllowDuplicateProperties` option to reject duplicate JSON properties, `PipeReader` deserialization support, and `ReferenceHandler` in `JsonSourceGenerationOptions`.
The following APIs were added in .NET 10:
Comment thread
kartheekp-ms marked this conversation as resolved.
Outdated

- `JsonSerializerOptions.Strict` / `JsonSerializerDefaults.Strict` — best-practice preset that disallows unmapped members, duplicate properties, and enforces nullable annotations.
- `JsonSerializerOptions.AllowDuplicateProperties` — option to reject duplicate JSON keys (disabled in Strict).
- `JsonSerializer.DeserializeAsync<T>(PipeReader)` — direct PipeReader deserialization without Stream conversion.
- `JsonSourceGenerationOptionsAttribute.ReferenceHandler` — specify ReferenceHandler in source-generated contexts to handle circular references.

For full details and code examples, see: [.NET 10 Serialization update](https://github.com/dotnet/docs/blob/main/docs/core/whats-new/dotnet-10/libraries.md#serialization).

## Best Practices

- **Reuse `JsonSerializerOptions` instances.** Creating a new instance per call is expensive — the metadata cache is rebuilt each time. Use a shared static instance or the built-in singletons (`JsonSerializerOptions.Default`, `.Web`, `.Strict`).
- **Use source generation for AOT/trimming.** Reflection-based serialization is incompatible with Native AOT. Use `[JsonSerializable]` attribute to the context classes for AOT-safe serialization. See the source generation topic below.
- **Prefer `Strict` for new projects.** The `Strict` preset catches common mistakes (unmapped members, duplicate keys, null violations) at deserialization time rather than silently ignoring them.
- **Serialize to UTF-8 when possible.** `SerializeToUtf8Bytes()` is 5–10% faster than string-based serialization because it avoids UTF-16 conversion.

## Topics
Copy link
Copy Markdown

@aortiz-msft aortiz-msft Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need all these topics? Would removing all of these reduce token usage for the corresponding evaluation while maintaining accuracy and perf improvements? If not, what's the minimal set?

Copy link
Copy Markdown
Contributor Author

@kartheekp-ms kartheekp-ms Mar 16, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is hard to finalize list of topics without evaluating how Copilot handles related tasks with and without these topics. Maybe we can use learn.microsoft.com metrics and add links to frequently visited topics.

Copy link
Copy Markdown
Contributor Author

@kartheekp-ms kartheekp-ms Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed, I have removed topics from the file.


- [Serialize and deserialize JSON using C#](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/overview.md): This overview describes the System.Text.Json namespace functionality for serializing to and deserializing from JSON in .NET.
- [How to serialize JSON in C#](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/how-to.md): Learn how to use the System.Text.Json namespace to serialize to JSON in .NET. Includes sample code.
Expand Down
Loading