Dotnet Source Gen Json

Configure System.Text.Json source generation for AOT-compatible, reflection-free JSON serialization with compile-time type metadata.

When to Use

• Preparing application for Native AOT compilation
• Eliminating reflection-based serialization overhead
• Improving startup performance by generating serialization code at compile time
• Ensuring JSON serialization errors surface at compile time

Requirements

• .NET 8 or higher for full options support
• .NET 6+ for basic source generation

Steps

1. Invoke polymorphic skill first:

• Run dotnet-json-polymorphic skill to ensure polymorphic types are configured
• This ensures [JsonDerivedType] attributes are in place before generating context

1. Ask scope:

• Ask user: "Apply to entire solution or specific project?"
• Filter to ASP.NET Core projects (those with web SDK or API endpoints)

1. Scan for API endpoint types:

• Search for Minimal API patterns: MapGet, MapPost, MapPut, MapDelete, MapPatch
• Extract request/response types from lambda parameters and return types

1. Scan for controller types:

• Search for controller attributes: [HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch]
• Extract parameter types and return types from action methods

1. Find direct serialization calls:

• Search for JsonSerializer.Serialize and JsonSerializer.Deserialize calls
• Extract type arguments from these calls

1. Check for existing JsonSerializerContext:

• Search for classes inheriting from JsonSerializerContext
• Note existing [JsonSerializable] types to avoid duplicates

1. Ask about enum serialization:

• Ask user: "Enable enum-as-string converter? (Recommended: Yes)"

1. Ask about property naming:

• Ask user: "Select property naming policy:"
• CamelCase (Recommended)
• SnakeCaseLower
• SnakeCaseUpper
• KebabCaseLower
• KebabCaseUpper
• None (preserve original casing)

1. Ask about null value handling:

• Ask user: "Serialize null values? (Recommended: No)"
• No - Omit null properties from output (smaller payloads)
• Yes - Include null properties in output
• If No: Add DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull

1. Create JsonSerializerContext:

• File: {ProjectName}JsonContext.cs in project root (same level as Program.cs)
• Class name: {ProjectName}JsonContext

1. Add source generation options:

``csharp [JsonSourceGenerationOptions( PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)] [JsonSerializable(typeof(WeatherForecast))] [JsonSerializable(typeof(List))] public partial class MyApiJsonContext : JsonSerializerContext { } ``

1. Include collection types:

• For each type T, also add [JsonSerializable(typeof(List))]
• Add [JsonSerializable(typeof(T[]))] if arrays are used

1. Configure ASP.NET Core:

• Add to Program.cs:

``csharp builder.Services.ConfigureHttpJsonOptions(options => { options.SerializerOptions.TypeInfoResolver = MyApiJsonContext.Default; }); ``

1. Verify with build:

``bash dotnet build ``

1. Report results:

• List the JsonSerializerContext file created
• List all types added to [JsonSerializable]
• Confirm ASP.NET Core integration added
• Confirm build status

Example Context

using System.Text.Json;
using System.Text.Json.Serialization;

namespace MyApi;

[JsonSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    Converters = [typeof(JsonStringEnumConverter)])]
[JsonSerializable(typeof(WeatherForecast))]
[JsonSerializable(typeof(List))]
[JsonSerializable(typeof(CreateOrderRequest))]
[JsonSerializable(typeof(OrderResponse))]
[JsonSerializable(typeof(List))]
[JsonSerializable(typeof(ErrorResponse))]
public partial class MyApiJsonContext : JsonSerializerContext
{
}

ASP.NET Core Integration

Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolver = MyApiJsonContext.Default;
});

var app = builder.Build();

app.MapGet("/weather", () => new WeatherForecast("Seattle", 72));
app.MapPost("/orders", (CreateOrderRequest request) => Results.Ok(new OrderResponse()));

app.Run();

AOT Configuration

For full AOT compatibility, add to the Directory.Build.props file (preferred), or project file:

  false

This ensures compile-time errors if any type is missing from the context.

Notes

• Context naming: Use {ProjectName}JsonContext for consistency
• File location: Place in project root alongside Program.cs
• Collection types: Always include List and array types if used in APIs
• Polymorphic types: Run dotnet-json-polymorphic first; polymorphic types use metadata-based generation only
• Enum handling: JsonStringEnumConverter requires .NET 8+ for AOT support
• Multiple contexts: Can have multiple contexts; use JsonTypeInfoResolver.Combine() to merge them

Documentation

• System.Text.Json Source Generation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Im5tu
• Source: Im5tu/claude
• License: MIT
• Homepage: https://codewithstu.tv

Install and usage instructions live in the source repository linked above.