Cuemon.Extensions.AspNetCore.Text.Json

Overview

Cuemon.Extensions.AspNetCore.Text.Json adds ASP.NET Core-aware converters and service registrations on top of Cuemon's System.Text.Json formatter stack. It extends Cuemon.Extensions.AspNetCore and Cuemon.Extensions.Text.Json so ProblemDetails, IHeaderDictionary, StringValues, and HttpExceptionDescriptor can move through JSON serialization with package-provided handling instead of ad hoc converter code.

The package also connects those converters to application startup. AddJsonFormatterOptions, AddJsonExceptionResponseFormatter, and AddMinimalJsonOptions let one JsonFormatterOptions configuration feed Cuemon's exception response formatter and Microsoft.AspNetCore.Http.Json.JsonOptions for minimal API serialization.

Key APIs

JsonConverterCollectionExtensions.AddHeaderDictionaryConverter adds a converter for IHeaderDictionary that writes headers as a JSON object and can rebuild a HeaderDictionary while reading JSON back.

JsonConverterCollectionExtensions.AddProblemDetailsConverter adds converters for both ProblemDetails and IDecorator<ProblemDetails>, serializing the standard fields plus any non-null extension entries through the active JsonSerializerOptions.

JsonConverterCollectionExtensions.AddHttpExceptionDescriptorConverter extends Cuemon's exception descriptor conversion with ASP.NET Core-specific fields such as Instance, Status, CorrelationId, RequestId, and TraceId, while honoring the configured SensitivityDetails.

JsonConverterCollectionExtensions.AddStringValuesConverter makes StringValues serialize as a single string or a JSON array based on the number of values, which matches common ASP.NET Core header and query-value shapes.

Formatters.ServiceCollectionExtensions.AddJsonFormatterOptions validates the caller-supplied configurator and registers JsonFormatterOptions so downstream services can resolve one shared JSON configuration model.

Formatters.ServiceCollectionExtensions.AddJsonExceptionResponseFormatter registers HttpExceptionDescriptorResponseFormatter<JsonFormatterOptions>, clones the configured serializer settings, adds the HTTP exception descriptor converter, and returns StreamContent with the negotiated content type.

ServiceCollectionExtensions.AddMinimalJsonOptions is the high-level registration entry point for minimal APIs. It adds MinimalJsonOptions as an IConfigureOptions<JsonOptions> implementation and then delegates to AddJsonExceptionResponseFormatter so minimal API JSON settings and Cuemon fault responses stay aligned.

MinimalJsonOptions copies the configured JsonFormatterOptions.Settings into JsonOptions.SerializerOptions, including converters and serializer settings such as naming policy, ignore rules, indentation, reference handling, and .NET 10 duplicate-property support when available.

Basic usage

using System.Text.Json;
using Codebelt.Extensions.Xunit;
using Cuemon.Extensions.AspNetCore.Text.Json;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Http.Json;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Xunit;

namespace MyProject.Tests;

public class MinimalJsonOptionsRegistrationTest : Test
{
    public MinimalJsonOptionsRegistrationTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void AddMinimalJsonOptions_ShouldApplyAspNetCoreConvertersToJsonOptions()
    {
        var services = new ServiceCollection();
        services.AddOptions();
        services.AddMinimalJsonOptions();

        using var provider = services.BuildServiceProvider();
        var jsonOptions = provider.GetRequiredService<IOptions<JsonOptions>>().Value;
        var problem = new ProblemDetails { Title = "Validation failed", Status = StatusCodes.Status400BadRequest };
        problem.Extensions["headers"] = new HeaderDictionary { ["x-correlation-id"] = "corr-42" };

        var json = JsonSerializer.Serialize(problem, jsonOptions.SerializerOptions);

        Assert.Contains("\"headers\":", json);
        Assert.Contains("\"x-correlation-id\":\"corr-42\"", json);
        TestOutput.WriteLine(json);
    }
}

Use this pattern when a minimal API application should serialize ASP.NET Core payload types through the same Cuemon JSON configuration used for fault responses. It matters because one registration call moves the package's converters into JsonOptions.SerializerOptions, so framework JSON output can handle ProblemDetails, headers, and related ASP.NET Core types consistently.

Installation

dotnet add package Cuemon.Extensions.AspNetCore.Text.Json

Usage guidance

Adopt this package when an ASP.NET Core application should keep Cuemon JsonFormatterOptions, minimal API JSON settings, and HTTP exception response serialization on the same System.Text.Json configuration path. If you only need lower-level JSON formatter helpers outside ASP.NET Core, use Cuemon.Extensions.Text.Json; if you only need MVC input and output formatters, use Cuemon.Extensions.AspNetCore.Mvc.Formatters.Text.Json or the framework's built-in JSON stack instead.