diff --git a/docs/standard/serialization/system-text-json/llms.txt b/docs/standard/serialization/system-text-json/llms.txt index 28aa411fd6f8c..0b8329dde3814 100644 --- a/docs/standard/serialization/system-text-json/llms.txt +++ b/docs/standard/serialization/system-text-json/llms.txt @@ -2,38 +2,26 @@ > High-performance JSON serialization and deserialization for .NET applications. -*Topics available: 31* - -**.NET 10 adds:** `JsonSerializerOptions.Strict` preset for best-practice defaults, `AllowDuplicateProperties` option to reject duplicate JSON properties, `PipeReader` deserialization support, and `ReferenceHandler` in `JsonSourceGenerationOptions`. - -- [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. -- [Migrate from Newtonsoft.Json to System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md): Learn about the differences between Newtonsoft.Json and System.Text.Json and how to migrate to System.Text.Json. -- [How to enable case-insensitive property name matching with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/character-casing.md): Learn how to enable case-insensitive property name matching while serializing to and deserializing from JSON in .NET. -- [How to customize character encoding with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/character-encoding.md): Learn how to customize character encoding while serializing to and deserializing from JSON in .NET. -- [How to instantiate JsonSerializerOptions with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/configure-options.md): Learn about constructors for JsonSerializerOptions instances and how to reuse JsonSerializerOptions instances. -- [How to write custom converters for JSON serialization](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/converters-how-to.md): Learn how to create custom converters for the JSON serialization classes that are provided in the System.Text.Json namespace. -- [Custom serialization and deserialization contracts](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/custom-contracts.md): Learn how to write your own contract resolution logic to customize the JSON contract for a type. -- [How to customize property names and values with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/customize-properties.md): Learn how to customize property names and values when serializing with System.Text.Json in .NET. -- [How to deserialize JSON in C#](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/deserialization.md): Learn how to use the System.Text.Json namespace to deserialize from JSON in .NET. Includes sample code. -- [JSON schema exporter](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/extract-schema.md): Learn how to use the JsonSchemaExporter class to extract JSON schema documents from .NET types. -- [Include fields in serialization](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/fields.md): Learn how to include fields when you serialize to and deserialize from JSON in .NET. -- [How to handle overflow JSON or use JsonElement or JsonNode in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/handle-overflow.md): Learn how to handle overflow JSON or use JsonElement or JsonNode while using System.Text.Json to serialize and deserialize JSON in .NET. -- [Serialization extension methods on HttpClient](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/httpclient-extensions.md): Learn how to serialize and deserialize JSON payloads from the network in a single line of code using extension methods on HttpClient and HttpContent. -- [How to ignore properties with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/ignore-properties.md): Learn how to ignore properties when serializing with System.Text.Json in .NET. -- [Use immutable types and properties](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/immutability.md): Learn how to deserialize JSON to immutable types and properties in .NET. -- [How to allow some kinds of invalid JSON with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/invalid-json.md): Learn how to allow comments, trailing commas, and quoted numbers while serializing to and deserializing from JSON in .NET. -- [Handle unmapped members during deserialization](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/missing-members.md): Learn how to configure the JSON deserialization behavior when properties are present in the JSON payload that aren't present in the POCO type. -- [Respect nullable annotations](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/nullable-annotations.md): Learn how to configure serialization and deserialization to respect nullable annotations. -- [How to serialize properties of derived classes with System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/polymorphism.md): Learn how to serialize polymorphic objects while serializing to and deserializing from JSON in .NET. -- [Populate initialized properties](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/populate-properties.md): Learn how to modify properties and fields that are already initialized when deserializing from JSON in .NET. -- [How to preserve references in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/preserve-references.md): Learn how to preserve references and handle or ignore circular references while using System.Text.Json to serialize and deserialize JSON in .NET. -- [How to choose reflection or source generation in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/reflection-vs-source-generation.md): Learn how to choose reflection or source generation in System.Text.Json. -- [Require properties for deserialization](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/required-properties.md): Learn how to mark properties as required for deserialization to succeed. -- [Source-generation modes in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/source-generation-modes.md): Learn about the two different source-generation modes in System.Text.Json. -- [How to use source generation in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/source-generation.md): Learn how to use source generation in System.Text.Json. -- [Supported types in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/supported-types.md): Learn which types are supported for serialization by the APIs in the System.Text.Json namespace. -- [How to use a JSON DOM in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/use-dom.md): Learn how to use a JSON document object model (DOM). -- [How to use Utf8JsonReader in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/use-utf8jsonreader.md): Learn how to use Utf8JsonReader. -- [How to use Utf8JsonWriter in System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/use-utf8jsonwriter.md): Learn how to use Utf8JsonWriter. -- [Visual Basic support for System.Text.Json](https://raw.githubusercontent.com/dotnet/docs/refs/heads/llmstxt/docs/standard/serialization/system-text-json/visual-basic-support.md): Learn which parts of the System.Text.Json namespace aren't supported in Visual Basic. +## What's New in .NET 10 + +### New APIs + +- `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(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). + +### Breaking Changes + +- **Property name conflict validation** — System.Text.Json now validates that user-defined property names don't conflict with metadata property names (`$type`, `$id`, `$ref`, or custom `TypeDiscriminatorPropertyName`). Previously, conflicts silently produced invalid JSON with duplicate properties; now an `InvalidOperationException` is thrown. Rename the conflicting property or apply `[JsonIgnore]` to resolve. + +For details, see: [System.Text.Json checks for property name conflicts](https://github.com/dotnet/docs/blob/main/docs/core/compatibility/serialization/10/property-name-validation.md). + +## 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.