Codebelt.Extensions.AspNetCore.Text.Yaml

Overview

Codebelt.Extensions.AspNetCore.Text.Yaml adds ASP.NET Core specific YAML integration on top of Codebelt.Extensions.YamlDotNet. Its public surface centers on service registration for YAML exception responses and on converters that serialize HttpExceptionDescriptor and ProblemDetails into the same formatter pipeline.

When the formatter is registered, it uses YamlFormatter plus YamlFormatterOptions from the lower-level package to emit either a fault descriptor or a decorated ProblemDetails projection. The package also exposes a minimal convenience registration through AddMinimalYamlOptions for applications that just need the YAML exception response formatter wired into DI.

Key APIs

AddProblemDetailsConverter adds YAML converters for both ProblemDetails and IDecorator<ProblemDetails>. It writes the standard problem fields and then emits any non-null Extensions entries into the YAML object.

AddHttpExceptionDescriptorConverter adds a converter for HttpExceptionDescriptor. It always writes the core error payload and conditionally includes failure details, evidence, correlation ID, request ID, and trace ID based on ExceptionDescriptorOptions.

AddYamlFormatterOptions registers YamlFormatterOptions through IServiceCollection. Tests show repeated calls still leave a single IConfigureOptions<YamlFormatterOptions> registration, so serializer settings, sensitivity, and supported media types stay centralized.

AddYamlExceptionResponseFormatter registers a singleton HttpExceptionDescriptorResponseFormatter<YamlFormatterOptions>. It serializes either the descriptor itself or a ProblemDetails projection and exposes handlers for text/plain; charset=utf-8, text/plain, application/yaml, text/yaml, and */*.

AddMinimalYamlOptions forwards directly to AddYamlExceptionResponseFormatter. Use it when you want the package's YAML exception response behavior without reaching into the formatter namespace yourself.

Basic usage

using System.Linq;
using Codebelt.Extensions.AspNetCore.Text.Yaml.Formatters;
using Codebelt.Extensions.Xunit;
using Codebelt.Extensions.YamlDotNet.Formatters;
using Cuemon.AspNetCore.Diagnostics;
using Cuemon.Diagnostics;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Xunit;

namespace MyProject.Tests;

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

    [Fact]
    public void ShouldRegisterYamlFormatter_WithConfiguredSensitivity()
    {
        var services = new ServiceCollection();
        services.AddOptions();
        services.AddYamlExceptionResponseFormatter(o => o.SensitivityDetails = FaultSensitivityDetails.All);

        using var provider = services.BuildServiceProvider();
        var options = provider.GetRequiredService<IOptions<YamlFormatterOptions>>().Value;
        var formatterCount = services.Count(sd => sd.ServiceType == typeof(HttpExceptionDescriptorResponseFormatter<YamlFormatterOptions>));

        Assert.Equal(FaultSensitivityDetails.All, options.SensitivityDetails);
        Assert.Equal(5, options.SupportedMediaTypes.Count);
        Assert.Equal(1, formatterCount);
        TestOutput.WriteLine($"Media types: {string.Join(", ", options.SupportedMediaTypes.Select(mt => mt.MediaType))}");
    }
}

Use this pattern when you configure ASP.NET Core services centrally and want YAML exception responses to inherit the same YamlFormatterOptions settings registered in DI. It matters because the formatter registration, sensitivity policy, and negotiated media types stay aligned instead of being wired separately.

Installation

dotnet add package Codebelt.Extensions.AspNetCore.Text.Yaml

Usage guidance

Adopt this package when an ASP.NET Core application already uses Cuemon fault descriptors or ProblemDetails and you want YAML error responses without writing the response formatter and ASP.NET Core specific converters yourself. If you only need general YAML serialization outside ASP.NET Core, use Codebelt.Extensions.YamlDotNet instead; if you need YAML input and output formatters for MVC endpoints, Codebelt.Extensions.AspNetCore.Mvc.Formatters.Text.Yaml is the better fit.