Cuemon.Extensions.AspNetCore.Xml

Overview

Cuemon.Extensions.AspNetCore.Xml extends Cuemon.Extensions.AspNetCore and Cuemon.Extensions.Xml with ASP.NET Core aware XML serialization primitives. Its public surface focuses on registering XML formatter services for dependency injection and on teaching the XML formatter pipeline how to serialize request-specific types such as ProblemDetails, HttpExceptionDescriptor, StringValues, headers, query collections, form collections, and cookies.

The package also wires those converters into XmlFormatterOptions.DefaultConverters the first time the formatter service extensions are touched. That gives ASP.NET Core applications a ready-made XML path for fault payloads and request metadata without having to hand-build converters for common framework types.

Key APIs

AddMinimalXmlOptions is the package's shortest entry point for ASP.NET Core registration. It validates the IServiceCollection input and forwards directly to AddXmlExceptionResponseFormatter, which makes it the practical choice when the goal is to enable XML exception output with one call.

AddXmlExceptionResponseFormatter registers an IHttpExceptionDescriptorResponseFormatter singleton backed by XmlFormatter. The implementation resolves XmlFormatterOptions and FaultDescriptorOptions from DI, adds the package's HttpExceptionDescriptor converter, and emits StreamContent with the negotiated content type.

AddXmlFormatterOptions applies XmlFormatterOptions through TryConfigure and preserves the important formatter knobs from the validated options instance. In source, that includes Settings, SensitivityDetails, SupportedMediaTypes, and SynchronizeWithXmlConvert.

AddProblemDetailsConverter adds XML converters for both ProblemDetails and IDecorator<ProblemDetails>. The converter writes the standard problem-details fields and then serializes each non-null extension value with its extension key as the XML root name.

AddHttpExceptionDescriptorConverter adds XML serialization for HttpExceptionDescriptor and lets callers shape the output with ExceptionDescriptorOptions. The implementation conditionally includes failure details, evidence, correlation identifiers, request identifiers, and trace identifiers based on the configured sensitivity flags.

AddStringValuesConverter inserts a converter at the front of the converter list for StringValues. It writes a single value as text and switches to repeated <Value> elements when the collection contains multiple entries.

AddHeaderDictionaryConverter serializes IHeaderDictionary as repeated <Header> elements with a name attribute. Each header value is passed back through the XML formatter pipeline, so the package-specific StringValues converter participates automatically.

AddQueryCollectionConverter, AddFormCollectionConverter, and AddCookieCollectionConverter add ASP.NET Core request collection support to the XML converter list. Query and form pairs are emitted as keyed <Field> elements, while cookies are emitted as keyed fields whose value is written directly.

Basic usage

using Codebelt.Extensions.Xunit;
using Cuemon.AspNetCore.Diagnostics;
using Cuemon.Extensions.AspNetCore.Xml;
using Cuemon.Xml.Serialization.Formatters;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Xunit;

namespace MyProject.Tests;

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

    [Fact]
    public void ShouldRegisterXmlExceptionFormattingForAspNetCore()
    {
        var services = new ServiceCollection();

        var registrations = services.AddMinimalXmlOptions();

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

        TestOutput.WriteLine($"Formatter type: {formatter.GetType().Name}");

        Assert.Same(services, registrations);
        Assert.NotNull(formatter);
        Assert.NotNull(options);
    }
}

Use this pattern when an ASP.NET Core application wants XML exception responses and formatter options to be available through the standard DI container. It matters because the package bundles the formatter registration and its ASP.NET Core specific converter bootstrapping into one predictable service setup step.

Installation

dotnet add package Cuemon.Extensions.AspNetCore.Xml

Usage guidance

Adopt this package when your ASP.NET Core application already uses Cuemon's XML formatter pipeline and needs framework-aware XML output for exception payloads, problem details, and request collections. If you need MVC input and output formatters instead, use Cuemon.Extensions.AspNetCore.Mvc.Formatters.Xml; if you only need general XML serialization outside ASP.NET Core, stay with the lower-level Cuemon.Extensions.Xml package.