System.Text.Json 9.0.0-preview.1.24080.9

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

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
HotChocolate.Types
Contains the Hot Chocolate GraphQL type system.
4,386
HotChocolate.Types
Contains the Hot Chocolate GraphQL type system.
7,701
HotChocolate.Utilities.Introspection
Contains an introspection client to download a GraphQL schema over HTTP.
4,619
HotChocolate.Utilities.Introspection
Contains an introspection client to download a GraphQL schema over HTTP.
7,657
IdentityModel
OpenID Connect & OAuth 2.0 client library
24,267
Microsoft.Extensions.Configuration.Json
JSON configuration provider implementation for Microsoft.Extensions.Configuration.
8,928
Microsoft.Extensions.DependencyModel
Abstractions for reading `.deps` files.
13,315
Microsoft.IdentityModel.JsonWebTokens
Includes types that provide support for creating, serializing and validating JSON Web Tokens.
11,861
Microsoft.IdentityModel.Tokens
Includes types that provide support for SecurityTokens, Cryptographic operations: Signing, Verifying Signatures, Encryption.
2,305
Microsoft.IdentityModel.Tokens
Includes types that provide support for SecurityTokens, Cryptographic operations: Signing, Verifying Signatures, Encryption.
21,376
Npgsql
Npgsql is the open source .NET data provider for PostgreSQL.
4,616
Npgsql
Npgsql is the open source .NET data provider for PostgreSQL.
9,432
Npgsql
Npgsql is the open source .NET data provider for PostgreSQL.
13,231
Refit
The automatic type-safe REST library for Xamarin and .NET
8,932
Refit
The automatic type-safe REST library for Xamarin and .NET
30,737
Swashbuckle.AspNetCore.SwaggerGen
Swagger Generator for APIs built on ASP.NET Core
10,123
Swashbuckle.AspNetCore.SwaggerGen
Swagger Generator for APIs built on ASP.NET Core
10,705
Swashbuckle.AspNetCore.SwaggerUI
Middleware to expose an embedded version of the swagger-ui from an ASP.NET Core application
10,090
Swashbuckle.AspNetCore.SwaggerUI
Middleware to expose an embedded version of the swagger-ui from an ASP.NET Core application
10,669
System.Net.Http.Json
Provides extension methods for System.Net.Http.HttpClient and System.Net.Http.HttpContent that perform automatic serialization and deserialization using System.Text.Json. Commonly Used Types: System.Net.Http.Json.HttpClientJsonExtensions System.Net.Http.Json.HttpContentJsonExtensions System.Net.Http.Json.JsonContent
30,700

https://go.microsoft.com/fwlink/?LinkID=799421

.NET Framework 4.6.2

.NET Standard 2.0

.NET 9.0

.NET 8.0

Version Downloads Last updated
9.0.0-preview.1.24080.9 1 02/17/2024
8.0.2 1 02/17/2024
8.0.1 2 01/18/2024
8.0.0 11 11/14/2023
8.0.0-rc.2.23479.6 7 10/13/2023
8.0.0-rc.1.23419.4 9 09/16/2023
8.0.0-preview.7.23375.6 8 08/10/2023
8.0.0-preview.6.23329.7 26 07/18/2023
8.0.0-preview.5.23280.8 7 06/14/2023
8.0.0-preview.4.23259.5 29 05/17/2023
8.0.0-preview.3.23174.8 19 04/15/2023
8.0.0-preview.2.23128.3 29 03/18/2023
8.0.0-preview.1.23110.8 18 03/02/2023
7.0.4 4 11/14/2023
7.0.3 13 06/14/2023
7.0.2 49 02/27/2023
7.0.1 32 01/24/2023
7.0.0 1,584 11/15/2022
7.0.0-rc.2.22472.3 37 10/12/2022
7.0.0-rc.1.22426.10 25 09/23/2022
7.0.0-preview.7.22375.6 64 08/16/2022
7.0.0-preview.6.22324.4 20 08/19/2022
7.0.0-preview.5.22301.12 56 06/27/2022
7.0.0-preview.4.22229.4 19 09/22/2022
7.0.0-preview.3.22175.4 35 08/19/2022
7.0.0-preview.2.22152.2 35 08/19/2022
7.0.0-preview.1.22076.8 33 08/19/2022
6.0.9 9 11/14/2023
6.0.8 5 06/14/2023
6.0.7 35 12/23/2022
6.0.6 55 09/17/2022
6.0.5 37 08/19/2022
6.0.4 35 08/19/2022
6.0.3 25 08/19/2022
6.0.2 51 08/19/2022
6.0.2-mauipre.1.22102.15 20 08/19/2022
6.0.2-mauipre.1.22054.8 38 08/18/2022
6.0.1 8,895 06/27/2022
6.0.0 22,211 06/28/2022
6.0.0-rc.2.21480.5 40 08/19/2022
6.0.0-rc.1.21451.13 27 08/19/2022
6.0.0-preview.7.21377.19 65 09/25/2022
6.0.0-preview.6.21352.12 57 12/06/2022
6.0.0-preview.5.21301.5 50 09/26/2022
6.0.0-preview.4.21253.7 41 09/24/2022
6.0.0-preview.3.21201.4 25 09/23/2022
6.0.0-preview.2.21154.6 3 01/07/2023
6.0.0-preview.1.21102.12 49 12/26/2022
5.0.2 26 06/27/2022
5.0.1 57 09/09/2022
5.0.0 51 09/06/2022
5.0.0-rc.2.20475.5 16 09/23/2022
5.0.0-rc.1.20451.14 28 12/09/2022
5.0.0-preview.8.20407.11 39 09/27/2022
5.0.0-preview.7.20364.11 16 01/07/2023
5.0.0-preview.6.20305.6 44 09/23/2022
5.0.0-preview.5.20278.1 20 09/25/2022
5.0.0-preview.4.20251.6 31 09/23/2022
5.0.0-preview.3.20214.6 41 09/23/2022
5.0.0-preview.2.20160.6 40 09/23/2022
5.0.0-preview.1.20120.5 38 09/23/2022
4.7.2 11,908 09/07/2022
4.7.1 8,889 06/27/2022
4.7.0 11,089 06/27/2022
4.7.0-preview3.19551.4 12 12/14/2022
4.7.0-preview2.19523.17 47 12/24/2022
4.7.0-preview1.19504.10 48 09/27/2022
4.6.0 13,360 06/27/2022
4.6.0-rc1.19456.4 5 09/25/2022
4.6.0-preview9.19421.4 60 09/21/2022
4.6.0-preview9.19416.11 22 09/22/2022
4.6.0-preview8.19405.3 60 09/25/2022
4.6.0-preview7.19362.9 21 09/21/2022
4.6.0-preview6.19303.8 60 09/22/2022
4.6.0-preview6.19264.9 43 09/21/2022
4.6.0-preview6.19259.10 47 09/23/2022