dotnet-source-gen-json

Files (1)

• SKILL.md

SKILL.md (first lines)

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

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

3. **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

4. **Scan for controller types**:
   - Search for controller attributes: `[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`
   - Extract parameter types and return types from action methods

5. **Find direct serialization calls**:
   - Search for `JsonSerializer.Serialize` and `JsonSerializer.Deserialize` calls
   - Extract type arguments from these calls

6. **Check for existing JsonSerializerContext**:
   - Search for classes inheriting from `JsonSerializerContext`
   - Note existing `[JsonSerializable]` types to avoid duplicates

7. **Ask about enum serialization**:
   - Ask user: "Enable enum-as-string converter? (Recommended: Yes)"

8. **Ask about property naming**:
   - Ask user: "Select property naming policy:"
     - CamelCase (Recommended)
     - SnakeCaseLower
     - SnakeCaseUpper
     - KebabCaseLower
     - KebabCaseUpper
     - None (preserve original casing)

9. **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`

10. **Create JsonSerializerContext**:
    - File: `{ProjectName}JsonContext.cs` in project root (same level as Program.cs)
    - Class name: `{ProjectName}JsonContext`

11. **Add source generation options**:
    ```csharp
    [JsonSourceGenerationOptions(
        PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
    [JsonSerializable(typeof(WeatherForecast))]
    [JsonSerializable(typeof(List<WeatherForecast>))]
    public partial class MyApiJsonContext : JsonSerializerContext
    {
    }
    ```

12. **Include collection types**:
    - For each type `T`, also add `[JsonSerializable(typeof(List<T>))]`
    - Add `[JsonSerializable(typeof(T[]))]` if arrays are used

13. **Configure ASP.NET Core**:
    - Add to Program.cs:
    ```csharp
    builder.Services.ConfigureHttpJsonOptions(options =>
    {
        options.SerializerOptions.TypeInfoResolver = MyApiJsonContext.Default;
    });
    ```

14. **Verify with build**:
    ```bash
    dotnet build
    ```

15. **Report results**:
    - List the JsonSerializerContext file created
    - List all types added to [JsonSerializable]
    - Confirm ASP.NET Core integration added
    - Confirm build status

## Example Context

```csharp
using System.Text.Json;
using System.Text.Json.Serialization;

namespace MyApi;

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

From Im5tu/claude, MIT.

More from Im5tu/claude