System.Text.Json 8.0.1
About
Provides high-performance and low-allocating types that serialize objects to JavaScript Object Notation (JSON) text and deserialize JSON text to objects, with UTF-8 support built-in. Also provides types to read and write JSON text encoded as UTF-8, and to create an in-memory document object model (DOM), that is read-only, for random access of the JSON elements within a structured view of the data.
Key Features
- High-performance reader and writer types for UTF-8 encoded JSON.
- A fully-featured JSON serializer for .NET types using reflection or source generated contracts.
- A high-performance read-only JSON DOM (JsonDocument) and a mutable DOM that interoperates with the serializer (JsonNode).
- Built-in support for async serialization, including IAsyncEnumerable support.
- Fully customizable contract model for serializable types.
How to Use
The System.Text.Json library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use the most recent version in older target frameworks.
Serialization:
using System;
using System.Text.Json;
WeatherForecast forecast = new (DateTimeOffset.Now, 26.6f, "Sunny");
var serialized = JsonSerializer.Serialize(forecast);
Console.WriteLine(serialized);
// {"Date":"2023-08-02T16:01:20.9025406+00:00","TemperatureCelsius":26.6,"Summary":"Sunny"}
var forecastDeserialized = JsonSerializer.Deserialize<WeatherForecast>(serialized);
Console.WriteLine(forecast == forecastDeserialized);
// True
public record WeatherForecast(DateTimeOffset Date, float TemperatureCelsius, string? Summary);
Serialization using the source generator:
using System.Text.Json;
using System.Text.Json.Serialization;
WeatherForecast forecast = new (DateTimeOffset.Now, 26.6f, "Sunny");
var serialized = JsonSerializer.Serialize(forecast, SourceGenerationContext.Default.WeatherForecast);
Console.WriteLine(serialized);
// {"Date":"2023-08-02T16:01:20.9025406+00:00","TemperatureCelsius":26.6,"Summary":"Sunny"}
var forecastDeserialized = JsonSerializer.Deserialize<WeatherForecast>(serialized, SourceGenerationContext.Default.WeatherForecast);
Console.WriteLine(forecast == forecastDeserialized);
// True
public record WeatherForecast(DateTimeOffset Date, float TemperatureCelsius, string? Summary);
[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(WeatherForecast))]
internal partial class SourceGenerationContext : JsonSerializerContext
{
}
Using the JSON DOM:
using System;
using System.Text.Json;
using System.Text.Json.Nodes;
string jsonString =
@"{
""Date"": ""2019-08-01T00:00:00"",
""Temperature"": 25,
""Summary"": ""Hot"",
""DatesAvailable"": [
""2019-08-01T00:00:00"",
""2019-08-02T00:00:00""
],
""TemperatureRanges"": {
""Cold"": {
""High"": 20,
""Low"": -10
},
""Hot"": {
""High"": 60,
""Low"": 20
}
}
}
";
JsonNode forecastNode = JsonNode.Parse(jsonString)!;
// Get value from a JsonNode.
JsonNode temperatureNode = forecastNode["Temperature"]!;
Console.WriteLine($"Type={temperatureNode.GetType()}");
Console.WriteLine($"JSON={temperatureNode.ToJsonString()}");
//output:
//Type = System.Text.Json.Nodes.JsonValue`1[System.Text.Json.JsonElement]
//JSON = 25
// Get a typed value from a JsonNode.
int temperatureInt = (int)forecastNode["Temperature"]!;
Console.WriteLine($"Value={temperatureInt}");
//output:
//Value=25
// Get a typed value from a JsonNode by using GetValue<T>.
temperatureInt = forecastNode["Temperature"]!.GetValue<int>();
Console.WriteLine($"TemperatureInt={temperatureInt}");
//output:
//Value=25
// Get a JSON object from a JsonNode.
JsonNode temperatureRanges = forecastNode["TemperatureRanges"]!;
Console.WriteLine($"Type={temperatureRanges.GetType()}");
Console.WriteLine($"JSON={temperatureRanges.ToJsonString()}");
//output:
//Type = System.Text.Json.Nodes.JsonObject
//JSON = { "Cold":{ "High":20,"Low":-10},"Hot":{ "High":60,"Low":20} }
// Get a JSON array from a JsonNode.
JsonNode datesAvailable = forecastNode["DatesAvailable"]!;
Console.WriteLine($"Type={datesAvailable.GetType()}");
Console.WriteLine($"JSON={datesAvailable.ToJsonString()}");
//output:
//datesAvailable Type = System.Text.Json.Nodes.JsonArray
//datesAvailable JSON =["2019-08-01T00:00:00", "2019-08-02T00:00:00"]
// Get an array element value from a JsonArray.
JsonNode firstDateAvailable = datesAvailable[0]!;
Console.WriteLine($"Type={firstDateAvailable.GetType()}");
Console.WriteLine($"JSON={firstDateAvailable.ToJsonString()}");
//output:
//Type = System.Text.Json.Nodes.JsonValue`1[System.Text.Json.JsonElement]
//JSON = "2019-08-01T00:00:00"
// Get a typed value by chaining references.
int coldHighTemperature = (int)forecastNode["TemperatureRanges"]!["Cold"]!["High"]!;
Console.WriteLine($"TemperatureRanges.Cold.High={coldHighTemperature}");
//output:
//TemperatureRanges.Cold.High = 20
// Parse a JSON array
JsonNode datesNode = JsonNode.Parse(@"[""2019-08-01T00:00:00"",""2019-08-02T00:00:00""]")!;
JsonNode firstDate = datesNode[0]!.GetValue<DateTime>();
Console.WriteLine($"firstDate={ firstDate}");
//output:
//firstDate = "2019-08-01T00:00:00"
Using the low-level JSON reader/writer types
using System;
using System.IO;
using System.Text;
using System.Text.Json;
var writerOptions = new JsonWriterOptions
{
Indented = true
};
using var stream = new MemoryStream();
using var writer = new Utf8JsonWriter(stream, writerOptions);
writer.WriteStartObject();
writer.WriteString("date", DateTimeOffset.Parse("8/2/2023 9:00 AM"));
writer.WriteNumber("temp", 42);
writer.WriteEndObject();
writer.Flush();
var jsonBytes = stream.ToArray();
string json = Encoding.UTF8.GetString(jsonBytes);
Console.WriteLine(json);
// {
// "date": "2023-08-02T09:00:00+00:00"
// "temp": 42
// }
var readerOptions = new JsonReaderOptions
{
AllowTrailingCommas = true,
CommentHandling = JsonCommentHandling.Skip
};
var reader = new Utf8JsonReader(jsonBytes, readerOptions);
while (reader.Read())
{
Console.Write(reader.TokenType);
switch (reader.TokenType)
{
case JsonTokenType.PropertyName:
case JsonTokenType.String:
{
string? text = reader.GetString();
Console.Write(" ");
Console.Write(text);
break;
}
case JsonTokenType.Number:
{
int intValue = reader.GetInt32();
Console.Write(" ");
Console.Write(intValue);
break;
}
// Other token types elided for brevity
}
Console.WriteLine();
}
// StartObject
// PropertyName date
// String 2023-08-02T09:00:00+00:00
// PropertyName temp
// Number 42
// EndObject
Main Types
The main types provided by this library are:
System.Text.Json.Utf8JsonWriter
System.Text.Json.Utf8JsonReader
System.Text.Json.JsonSerializer
System.Text.Json.JsonConverter
System.Text.Json.JsonDocument
System.Text.Json.Nodes.JsonNode
System.Text.Json.Serialization.Metadata.JsonTypeInfo
Additional Documentation
Related Packages
- Lightweight data formats abstraction: System.Memory.Data
- Serialization of HttpContent: System.Net.Http.Json
Feedback & Contributing
System.Text.Json is released as open source under the MIT license. Bug reports and contributions are welcome at the GitHub repository.
Showing the top 20 packages that depend on System.Text.Json.
Packages | Downloads |
---|---|
Azure.Core
This is the implementation of the Azure Client Pipeline
|
303 |
Azure.Identity
This is the implementation of the Azure SDK Client Library for Azure Identity
|
305 |
IGeekFan.AspNetCore.Knife4jUI
Middleware to expose an embedded version of the knife4j-vue from an ASP.NET Core application
|
973 |
Microsoft.Extensions.Configuration.Json
JSON configuration provider implementation for Microsoft.Extensions.Configuration.
|
5,474 |
Microsoft.Extensions.Configuration.Json
JSON configuration provider implementation for Microsoft.Extensions.Configuration.
|
8,930 |
Microsoft.Extensions.Configuration.Json
JSON configuration provider implementation for Microsoft.Extensions.Configuration. This package enables you to read your application's settings from a JSON file. You can use JsonConfigurationExtensions.AddJsonFile extension method on IConfigurationBuilder to add the JSON configuration provider to the configuration builder.
|
151 |
Microsoft.Extensions.DependencyModel
Provides abstractions for reading `.deps` files. When a .NET application is compiled, the SDK generates a JSON manifest file (`<ApplicationName>.deps.json`) that contains information about application dependencies. You can use `Microsoft.Extensions.DependencyModel` to read information from this manifest at run time. This is useful when you want to dynamically compile code (for example, using Roslyn Emit API) referencing the same dependencies as your main application.
By default, the dependency manifest contains information about the application's target framework and runtime dependencies. Set the PreserveCompilationContext project property to `true` to additionally include information about reference assemblies used during compilation.
|
189 |
Microsoft.Extensions.Logging.EventSource
EventSource/EventListener logger provider implementation for Microsoft.Extensions.Logging.
|
5,407 |
Microsoft.Extensions.Logging.EventSource
EventSource/EventListener logger provider implementation for Microsoft.Extensions.Logging.
|
8,848 |
Microsoft.IdentityModel.JsonWebTokens
Includes types that provide support for creating, serializing and validating JSON Web Tokens.
|
185 |
Microsoft.IdentityModel.JsonWebTokens
Includes types that provide support for creating, serializing and validating JSON Web Tokens. This is a newer, faster version of System.IdentityModel.Tokens.Jwt that has additional functionality.
|
207 |
Microsoft.IdentityModel.Protocols.OpenIdConnect
Includes types that provide support for OpenIdConnect protocol.
|
220 |
Microsoft.IdentityModel.Tokens
Includes types that provide support for SecurityTokens, Cryptographic operations: Signing, Verifying Signatures, Encryption.
|
184 |
Microsoft.IdentityModel.Tokens
Includes types that provide support for SecurityTokens, Cryptographic operations: Signing, Verifying Signatures, Encryption.
|
186 |
Minio
MinIO .NET SDK for Amazon S3 Compatible Cloud Storage.
|
301 |
Oracle.ManagedDataAccess.Core
Oracle Data Provider for .NET (ODP.NET) Core is a multi-platform ADO.NET driver that provides fast data access from Microsoft .NET (Core) clients to Oracle databases. ODP.NET Core consists of a single 100% managed code dynamic-link library.
|
269 |
Swashbuckle.AspNetCore.SwaggerGen
Swagger Generator for APIs built on ASP.NET Core
|
14,192 |
Swashbuckle.AspNetCore.SwaggerUI
Middleware to expose an embedded version of the swagger-ui from an ASP.NET Core application
|
1,774 |
System.Memory.Data
Contains the BinaryData type, which is useful for converting between strings, streams, JSON, and bytes.
|
335 |
TimeZoneNames
Provides localized time zone names.
|
9,217 |
.NET Framework 4.6.2
- Microsoft.Bcl.AsyncInterfaces (>= 8.0.0)
- System.ValueTuple (>= 4.5.0)
- System.Threading.Tasks.Extensions (>= 4.5.4)
- System.Runtime.CompilerServices.Unsafe (>= 6.0.0)
- System.Memory (>= 4.5.5)
- System.Buffers (>= 4.5.1)
- System.Text.Encodings.Web (>= 8.0.0)
.NET Standard 2.0
- System.Threading.Tasks.Extensions (>= 4.5.4)
- System.Runtime.CompilerServices.Unsafe (>= 6.0.0)
- System.Memory (>= 4.5.5)
- System.Buffers (>= 4.5.1)
- System.Text.Encodings.Web (>= 8.0.0)
- Microsoft.Bcl.AsyncInterfaces (>= 8.0.0)
.NET 8.0
- System.Text.Encodings.Web (>= 8.0.0)
.NET 7.0
- System.Text.Encodings.Web (>= 8.0.0)
.NET 6.0
- System.Text.Encodings.Web (>= 8.0.0)
- System.Runtime.CompilerServices.Unsafe (>= 6.0.0)
Version | Downloads | Last updated |
---|---|---|
9.0.0-preview.4.24266.19 | 8 | 05/25/2024 |
9.0.0-preview.3.24172.9 | 7 | 04/16/2024 |
9.0.0-preview.2.24128.5 | 4 | 05/10/2024 |
8.0.1 | 203 | 05/24/2024 |
8.0.0 | 137 | 12/02/2023 |
8.0.0-preview.6.23329.7 | 20 | 08/07/2023 |
8.0.0-preview.4.23259.5 | 14 | 06/09/2023 |
8.0.0-preview.3.23174.8 | 5 | 04/23/2023 |
7.0.3 | 39 | 03/22/2024 |
7.0.2 | 50 | 03/31/2023 |
7.0.1 | 15 | 04/23/2023 |
7.0.0 | 50 | 03/20/2023 |
6.0.6 | 6 | 07/01/2023 |
6.0.5 | 9 | 08/08/2023 |
6.0.4 | 64 | 05/28/2024 |
6.0.0-rc.1.21451.13 | 5 | 11/03/2022 |
4.6.0-preview8.19405.3 | 7 | 05/30/2024 |