MinimalSerializers.Json 1.0.5

MinimalSerializers.Json

Automatically generate System.Text.Json source-generation roots from [DataContract] graphs.

Stop hand-maintaining hundreds of [JsonSerializable(typeof(...))] attributes (and the T[] / List<T> variants ASP.NET needs). Mark your DTOs with [DataContract] / [DataMember], put [MinimalJsonSerializerContext] on a partial JsonSerializerContext, and let the package emit the roots before CoreCompile so the built-in STJ source generator produces serializers in a single dotnet build.

Why this exists

JsonSerializerContext is the right AOT-friendly path, but root registration is manual and brittle:

• every DTO
• every nested type
• every List<T> / T[] / dictionary shape used as a root

MinimalSerializers.Json fills the gap .NET should have shipped: discover the graph, emit the roots, reuse STJ.

How it works

[DataContract] models + partial context [MinimalJsonSerializerContext]
        │
        ▼
MSBuild target (buildTransitive) → discovery task
        │
        ▼
obj/.../*.MinimalJson.g.cs   // [JsonSerializable(typeof(T))] + arrays/lists
        │
        ▼
CoreCompile → System.Text.Json source generator
        │
        ▼
Context.Default  (same runtime path as hand-written contexts)

There is no generator ordering hack. Roslyn generators cannot see each other's main outputs, so this package writes compile-visible source via MSBuild before STJ runs.

Runtime performance is the same as a complete manual STJ context, because the serializers are still generated by STJ.

Install

dotnet add package MinimalSerializers.Json

No custom Target in your csproj. The package ships buildTransitive props/targets automatically.

Quick start

using System.Runtime.Serialization;
using System.Text.Json.Serialization;
using MinimalSerializers.Json;

[DataContract]
public sealed record OrderDto
{
    [DataMember] public required Guid Id { get; init; }
    [DataMember] public required List<OrderItemDto> Items { get; init; }
}

[DataContract]
public sealed record OrderItemDto
{
    [DataMember] public required string Sku { get; init; }
    [DataMember] public required int Quantity { get; init; }
}

[MinimalJsonSerializerContext]
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
public partial class AppJsonSerializerContext : JsonSerializerContext;

Wire into options / DI

using System.Text.Json;
using MinimalSerializers.Json;

var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
options.AddMinimalJsonContext<AppJsonSerializerContext>();

// ASP.NET Core
builder.Services.ConfigureHttpJsonOptions(o =>
{
    o.SerializerOptions.AddMinimalJsonContext<AppJsonSerializerContext>();
});

Or insert the context yourself (same as today):

options.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);

What gets registered

For each discovered object/enum type T (from [DataContract] and nested [DataMember] graphs):

• T
• T[] (default on — important because ASP.NET often materializes arrays)
• List<T> (default on)

Also registers closed collection/dictionary shapes found on members when enabled.

TypeInfo property names

Collection and array roots are emitted with an explicit TypeInfoPropertyName so they cannot collide with DTOs named List*Dto (STJ SYSLIB1031):

[JsonSerializable(typeof(ListMoneyDetailsDto))]
[JsonSerializable(typeof(ListMoneyDetailsDto[]), TypeInfoPropertyName = "ArrayOf_ListMoneyDetailsDto")]
[JsonSerializable(typeof(List<MoneyDetailsDto>), TypeInfoPropertyName = "ListOf_MoneyDetailsDto")]

Plain object/enum roots keep STJ's default short names unless two types would still share the same short name (different namespaces), in which case Minimal assigns unique names. Prefer options.GetTypeInfo(typeof(T)) / JsonSerializer.Serialize(value, options) when you do not want to depend on generated property names; typed Context.Default.ListOf_… members follow the mangled names above.

Conventions

One context per project is the intended model (for example one DTO/project assembly → one context).

MSBuild properties

Performance

The package does not invent a new serializer. It discovers your DataContract graph and emits the same [JsonSerializable] roots you would have written by hand, then the built-in System.Text.Json source generator builds the serializers.

So the fair comparison is three paths on the same payload:

Benchmarks use a warmed order with 64 line items and include both:

• options/resolver-chain APIs (Serialize(value, options) / Deserialize<T>(json, options))
• typed source-gen APIs (Serialize(value, Context.Default.T) / Deserialize(json, Context.Default.T))

Results

Representative numbers from benchmarks/MinimalSerializers.Json.Benchmarks on .NET 11 / Apple M4 Max (InProcess, warmed):

Takeaways

1. Minimal ≈ Manual on both serialize and deserialize (within noise). That is the point: you get the source-generated STJ path without typing every root and every T[] / List<T> by hand.
2. Serialize is a clear win for source-gen. Prefer the typed API (Context.Default.MyDto) when you can; it is roughly 4–6× faster than reflection here. Options-based source-gen is still about 2× faster than reflection.
3. Deserialize is not automatically faster than reflection on warm, property-based DTOs. Reflection’s cached metadata path can allocate less and finish sooner on this shape. Manual and Minimal stay locked together, so the gap is STJ source-gen vs reflection — not Minimal overhead.
4. Prefer source-gen anyway for AOT/trimming, ASP.NET root coverage (T / T[] / List<T>), and predictable startup. Minimal’s product win is authoring: one [MinimalJsonSerializerContext] partial instead of a brittle attribute list, at the same runtime speed as the hand-written context.

dotnet run --project benchmarks/MinimalSerializers.Json.Benchmarks -c Release

Samples

• samples/Sample.Contracts — sample DataContract models + minimal context
• samples/Sample.Host — sample host that serializes/deserializes with options wiring

dotnet run --project samples/Sample.Host

Limitations (v1)

• Open generics are skipped as roots (closed constructed types only)
• Generic DTO inheritance of the form Derived<T> : Base<T> (both DataContracts) can break the built-in STJ source generator with CS0102 (duplicate nested accessor types). MinimalSerializers emits MSJ0009 when it detects this shape. Prefer composition or flattened records. Closed constructions are still registered.
• Polymorphism / $type discriminators are not auto-generated (keep your own JsonTypeInfo modifiers)
• DataMember.Name is not rewritten to [JsonPropertyName] (STJ naming policies remain source of truth)
• Multi-assembly discovery is not enabled by default (one project → one context)

Diagnostics

Development

dotnet tool restore
dotnet build MinimalSerializers.slnx
dotnet test MinimalSerializers.slnx --settings coverage.runsettings
dotnet pack src/MinimalSerializers.Json/MinimalSerializers.Json.csproj -c Release -o artifacts/packages

Maintainer publish steps (Trusted Publishing / local push) live in PUBLISHING.md.

License

MIT