Codebelt.Extensions.AspNetCore.Newtonsoft.Json

Overview

Codebelt.Extensions.AspNetCore.Newtonsoft.Json adds ASP.NET Core registrations and converter extensions that make NewtonsoftJsonFormatter work cleanly for exception responses and ASP.NET Core specific payloads. It extends Codebelt.Extensions.Newtonsoft.Json with service registration for IServiceCollection and converter helpers for types such as ProblemDetails, HttpExceptionDescriptor, and StringValues.

The package centers on fault response formatting. Its formatter registration wires HttpExceptionDescriptorResponseFormatter<NewtonsoftJsonFormatterOptions> into the container, while the converter extensions ensure ASP.NET Core response models serialize with the naming strategy and sensitivity settings defined by the formatter options.

Key APIs

AddNewtonsoftJsonExceptionResponseFormatter registers NewtonsoftJsonFormatterOptions and a singleton HttpExceptionDescriptorResponseFormatter<NewtonsoftJsonFormatterOptions>. The formatter resolves its options from IOptions<NewtonsoftJsonFormatterOptions>, adds the HTTP exception descriptor converter, and serializes either FaultDetails or ProblemDetails output depending on the configured FaultDescriptorOptions.

AddNewtonsoftJsonFormatterOptions adds and validates NewtonsoftJsonFormatterOptions through DI. Tests show that it guards against a null IServiceCollection, applies the caller's setup delegate, preserves the package defaults when no setup is supplied, and only registers one IConfigureOptions<NewtonsoftJsonFormatterOptions> entry even when called multiple times.

AddMinimalNewtonsoftJsonOptions is the package-level shortcut in the root namespace. It validates the service collection and forwards directly to AddNewtonsoftJsonExceptionResponseFormatter, which makes it the smallest registration path when you want the package's default ASP.NET Core fault formatting behavior.

AddHttpExceptionDescriptorConverter extends a JsonConverter collection with HttpExceptionDescriptor serialization. It builds on AddExceptionDescriptorConverterOf<T> from Codebelt.Extensions.Newtonsoft.Json and adds ASP.NET Core specific fields such as Instance, Status, CorrelationId, RequestId, and TraceId.

AddProblemDetailsConverter adds converter support for ProblemDetails and IDecorator<ProblemDetails>. The writer emits the standard problem details members and any non-null extension entries, so decorated fault payloads can still be serialized through the same formatter settings.

AddStringValuesConverter adds a converter for Microsoft.Extensions.Primitives.StringValues. Single values are emitted as JSON strings, while multi-value headers or collections are emitted as JSON arrays.

Basic usage

using Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters;
using Codebelt.Extensions.Newtonsoft.Json.Formatters;
using Codebelt.Extensions.Xunit;
using Cuemon.AspNetCore.Diagnostics;
using Cuemon.Diagnostics;
using Cuemon.Extensions.AspNetCore.Diagnostics;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Xunit;

namespace MyProject.Tests;

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

    [Fact]
    public void AddNewtonsoftJsonExceptionResponseFormatter_RegistersFormatterAndOptions()
    {
        var services = new ServiceCollection();
        services.AddFaultDescriptorOptions();
        services.AddNewtonsoftJsonExceptionResponseFormatter(o => o.SensitivityDetails = FaultSensitivityDetails.All);

        using var provider = services.BuildServiceProvider();
        var options = provider.GetRequiredService<IOptions<NewtonsoftJsonFormatterOptions>>().Value;
        var formatter = provider.GetRequiredService<HttpExceptionDescriptorResponseFormatter<NewtonsoftJsonFormatterOptions>>();

        TestOutput.WriteLines(
            $"Sensitivity: {options.SensitivityDetails}",
            $"Media types: {string.Join(", ", options.SupportedMediaTypes)}");

        Assert.Equal(FaultSensitivityDetails.All, options.SensitivityDetails);
        Assert.NotNull(formatter);
    }
}

Use this pattern when an ASP.NET Core application already uses Cuemon fault handling and you want Newtonsoft.Json to produce the registered error response payloads through DI. It matters because the package keeps formatter configuration, exception descriptor rendering, and ASP.NET Core specific converters in one registration point.

Installation

dotnet add package Codebelt.Extensions.AspNetCore.Newtonsoft.Json

Usage guidance

Use this package when your ASP.NET Core application needs Newtonsoft.Json-backed fault responses and you want ProblemDetails, HttpExceptionDescriptor, and StringValues to serialize through the same formatter options. If you need MVC formatters for request and response bodies, use Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json instead, and if you only need lower-level Newtonsoft.Json formatter primitives outside ASP.NET Core, use Codebelt.Extensions.Newtonsoft.Json.