Overview [ Documentation]

These notes are for System.Text.Json.

There are two approaches for serializing and deserializing with System.Text.Json:

1. Using JsonSerializer
   • See notes.
2. Using the JSON DOM
   • Use the DOM when you receive JSON that doesn’t have a fixed schema and must be inspected to know what it contains.
   • Two JSON DOM approaches:
     1. JsonDocument (see notes)
     • A read-only (immutable) DOM. Cannot be changed after creation. Faster.
     • Uses JsonElements.
       • JsonElement has JSON Array and Object enumerators.
     2. JsonNode (see notes)
     • A mutable DOM. Can be changed after creation. Slower.
     • Uses JsonNode, JsonObject, JsonArray, JsonValue, and JsonElement.

Convenience vs. Control

Reference: https://devblogs.microsoft.com/dotnet/the-convenience-of-system-text-json/

The APIs in the System.Text.Json namespace can be placed on a spectrum of convenience vs control. These APIs are listed from low level (most control) to high level (most convenient):

1. System.Text.Json.Utf8JsonReader/Writer — for reading and writing JSON documents one node at a time
2. System.Text.Json.JsonDocument — for providing a view of the entire JSON document with patterns for reading and writing
3. System.Text.Json.JsonSerializer — for automatically serializing and deserializing JSON data

Security

System.Text.Json has a threat model. See: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/docs/ThreatModel.md

Thread Safety

Warning: JsonDocument is not thread safe. All other aspects of System.Text.Json are thread safe.

Reflection vs. Source Generation [ Documentation]

System.Text.Json can gather metadata needed to access properties of objects for serialization/deserialization two ways:

1. Using reflection at run time (default)
2. Using source generation

Source generation has two modes: metadata collection mode and serialization optimization mode:

Enabling Source Generation

Follow instructions here to enable source generation.

Deserialize with HttpClient and HttpContent Extension Methods

This technique still requires that you create a response class.

• Documentation: https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-how-to?pivots=dotnet-6-0#httpclient-and-httpcontent-extension-methods