JSON serialization and deserialization (marshalling and unmarshalling) in .NET - overview
System.Text.Json library design emphasizes high performance and low memory allocation over an extensive feature set. Built-in UTF-8 support optimizes the process of reading and writing JSON text encoded as UTF-8, which is the most prevalent encoding for data on the web and files on disk.
The library also provides classes for working with an in-memory document object model (DOM). This feature enables random access to the elements in a JSON file or string.
There are some limitations on what parts of the library you can use from Visual Basic code. For more information, see Visual Basic support.
How to get the library
The library is built-in as part of the shared framework for .NET Core 3.0 and later versions. The source generation feature is built-in as part of the shared framework for .NET 6 and later versions. Use of source generation requires .NET 5 SDK or later.
For framework versions earlier than .NET Core 3.0, install the System.Text.Json NuGet package. The package supports:
- .NET Standard 2.0 and later
- .NET Framework 4.7.2 and later
- .NET Core 2.1 and later
- .NET 5 and later
Run-time reflection vs. compile-time source generation
System.Text.Json uses reflection to gather the metadata it needs to access properties of objects for serialization and deserialization at run time. As an alternative,
System.Text.Json can use the C# source generation feature to improve performance, reduce private memory usage, and facilitate assembly trimming, which reduces app size. For more information, see How to choose reflection or source generation in System.Text.Json.
For information about security threats that were considered when designing JsonSerializer, and how they can be mitigated, see
System.Text.Json Threat Model.
System.Text.Json serializer was designed with thread safety in mind. Practically, this means that once locked, JsonSerializerOptions instances can be safely shared across multiple threads.
JsonDocument was designed to provide an immutable and thus thread-safe DOM representation for JSON values. However, due to a concurrency bug,
JsonDocument is not currently thread safe.
- How to use the library
- Instantiate JsonSerializerOptions instances
- Enable case-insensitive matching
- Customize property names and values
- Ignore properties
- Require properties
- Allow invalid JSON
- Handle overflow JSON or use JsonElement or JsonNode
- Preserve references and handle circular references
- Deserialize to immutable types and non-public accessors
- Polymorphic serialization
- Migrate from Newtonsoft.Json to System.Text.Json
- Customize character encoding
- Use DOM, Utf8JsonReader, and Utf8JsonWriter
- Write custom converters for JSON serialization
- DateTime and DateTimeOffset support
- How to use source generation
- Supported collection types
- System.Text.Json API reference
- System.Text.Json.Serialization API reference
Submit and view feedback for