System Text Json

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(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(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.

temperatureInt = forecastNode["Temperature"]!.GetValue();

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($