Optimizing JSON Handling in .NET 8 with Source Generators and System.Text.Json

Why JSON Performance Matters in Modern .NET Apps

Every millisecond counts when a microservice processes thousands of requests per second. A recent benchmark from the .NET team showed that a typical CRUD endpoint can spend up to 30% of its CPU time serializing or deserializing JSON payloads. In high‑traffic scenarios that overhead translates into higher cloud costs and slower user experiences.

Source Generators in .NET 8

.NET 8 introduces built‑in source generators for System.Text.Json. The generator scans your code at compile time, emits strongly‑typed JsonSerializerContext classes, and removes the reflection cost that traditional serialization relies on. The result is a near‑zero allocation path for both reading and writing JSON.

To enable the feature, add the System.Text.Json NuGet package version 8.0 or later and decorate the types you want to serialize with [JsonSerializable]. The compiler then creates a partial context class that you can reuse throughout the application.

Benchmark Setup

All measurements were taken on an Azure D2 v4 VM (2 vCPU, 8 GB RAM) running Windows Server 2022. The test compared three configurations:

• Plain JsonSerializer.Serialize with default options (reflection based).
• Explicit JsonSerializerOptions with DefaultIgnoreCondition set to WhenWritingNull.
• Source‑generated context (PersonJsonContext) with JsonSerializerOptions referencing the generated converter.

Each scenario serialized and deserialized 10 million Person records (Name:string, Age:int, Email:string) and recorded elapsed time, GC allocations, and CPU usage.

Results

The source‑generated path outperformed the reflection‑based approach by a clear margin:

The generated code reduced allocations by roughly 77% and cut CPU usage by more than half. In a real‑world API, that translates into handling roughly 1.5 × more requests with the same hardware.

Step‑by‑Step Implementation

Below is a minimal reproducible example. First, define the model and the source‑generated context:

using System.Text.Json.Serialization;

public record Person(string Name, int Age, string Email);

[JsonSerializable(typeof(Person))]
public partial class PersonJsonContext : JsonSerializerContext { }

Next, configure the serializer options to reuse the generated converter:

var options = new JsonSerializerOptions
{
    WriteIndented = false
};
options.Converters.Add(PersonJsonContext.Default.Person);

var person = new Person("Alice", 30, "alice@example.com");
string json = JsonSerializer.Serialize(person, PersonJsonContext.Default.Person, options);
Person deserialized = JsonSerializer.Deserialize(json, PersonJsonContext.Default.Person, options);

Notice the use of PersonJsonContext.Default.Person – this tells the runtime to use the compile‑time generated metadata instead of falling back to reflection.

Best Practices for Production Code

1. Scope the Context. Generate a separate context per bounded context (e.g., API contracts, domain models). This keeps the generated assembly size small and improves incremental builds.

2. Cache Options. Create a singleton JsonSerializerOptions instance and reuse it. Options are immutable after the first use, and reusing them avoids repeated allocation of internal buffers.

3. Prefer Value Types for Small Payloads. When the JSON schema consists of primitives, consider using struct records. The source generator can emit stack‑only serialization paths, further reducing GC pressure.

4. Benchmark with Real Data. Synthetic strings often hide allocation patterns. Capture a sample payload from production, feed it into BenchmarkDotNet, and verify that the generated code still wins under realistic load.

Common Pitfalls

Missing the partial keyword on the context class will compile, but the generator cannot emit the implementation, causing a runtime fallback to reflection. Also, avoid mixing source‑generated and reflection‑based calls for the same type; doing so defeats the purpose of the generated metadata.

Sources

Microsoft Docs – System.Text.Json source generation
dotnet/runtime GitHub repository – performance benchmarks
BenchmarkDotNet documentation – accurate .NET micro‑benchmarks

Author: Mahmut Sarıkaya — sarikayadev.com