Codebelt.Extensions.YamlDotNet

Overview

Codebelt.Extensions.YamlDotNet adds a stream-based YAML formatter, a package-owned converter model, and emitter helpers on top of YamlDotNet. It centers YAML work around YamlFormatter, YamlSerializerOptions, and custom converter callbacks so callers can keep serialization and parsing behavior in one configurable pipeline instead of rebuilding serializer setup at each call site.

The package also carries diagnostics-focused YAML support for Exception and Cuemon.Diagnostics.ExceptionDescriptor. Tests show the same pipeline being used for ordinary object graphs, multi-document parsing, custom converters, and failure payloads with configurable sensitivity.

Key APIs

YamlFormatter is the main entry point. It derives from StreamFormatter<YamlFormatterOptions>, builds configured SerializerBuilder and DeserializerBuilder instances internally, and reads YamlSerializerOptions for naming, reflection, aliases, roundtrip behavior, scalar style, and registered converters.

YamlFormatter.DeserializeObject handles parser-driven scenarios where a single stream contains more than one YAML document. The static overloads accept an Action<IDeserializer, Parser> delegate, and the tests use that delegate to walk DocumentStart events and materialize multiple Book instances from one stream.

YamlFormatterOptions packages formatter-specific concerns that sit above raw serializer settings. It carries SensitivityDetails, supported media types, and a YamlSerializerOptions instance, and it refreshes converter dependencies so exception and exception-descriptor converters are added with the active fault-sensitivity settings.

YamlSerializerOptions controls the YAML builder configuration that YamlFormatter applies. The source exposes converter registration, reflection rules, indentation, aliases, naming conventions, enum naming conventions, maximum recursion, newline handling, value handling, canonical mode, and EnsureRoundtrip.

YamlConverterFactory creates YamlConverter implementations from delegates instead of requiring a named converter type. Generic and non-generic overloads support either a concrete type or a predicate, and the tests show both read and write delegates building mappings with the package's emitter extension methods.

YamlConverter<T> is the package's typed converter base class. It plugs into YamlDotNet through IYamlTypeConverter, exposes the active YamlFormatter through the Formatter property, and gives custom converters a formatter-aware place to implement WriteYaml and ReadYaml.

ExceptionDescriptorExtensions.ToYaml turns a Cuemon.Diagnostics.ExceptionDescriptor into a YAML string through the same formatter pipeline. Tests use it with FaultSensitivityDetails and PascalCaseNamingConvention to include or omit failure, stack, data, and evidence sections without bypassing the formatter options model.

Basic usage

using System;
using Codebelt.Extensions.Xunit;
using Codebelt.Extensions.YamlDotNet.Formatters;
using Cuemon.Diagnostics;
using Cuemon.Extensions.IO;
using Xunit;
using YamlDotNet.Serialization.NamingConventions;

namespace MyProject.Tests;

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

    [Fact]
    public void ShouldSerializeFailureDetailsAsYaml()
    {
        var descriptor = new ExceptionDescriptor(new InvalidOperationException("Release failed"), "REL-42", "Deployment validation failed.", new Uri("https://docs.example.com/REL-42"));
        var formatter = new YamlFormatter(o =>
        {
            o.SensitivityDetails = FaultSensitivityDetails.Failure;
            o.Settings.NamingConvention = PascalCaseNamingConvention.Instance;
        });

        var yaml = formatter.Serialize(descriptor, typeof(ExceptionDescriptor)).ToEncodedString();

        TestOutput.WriteLine(yaml);

        Assert.Contains("Code: REL-42", yaml);
        Assert.Contains("Failure:", yaml);
    }
}

Use this pattern when a service or background job needs a YAML failure document that follows the same formatter settings as the rest of the application. It matters because YamlFormatterOptions keeps naming and fault-sensitivity rules in one place while the package's built-in converters handle ExceptionDescriptor and nested Exception data.

Installation

dotnet add package Codebelt.Extensions.YamlDotNet

Usage guidance

Choose this package when you want YAML serialization, parsing, or diagnostic failure output to flow through Codebelt's formatter, converter, and options abstractions instead of hand-building YamlDotNet serializer objects at each call site. If you only need raw YamlDotNet builders with no formatter pipeline or exception-focused helpers, plain YamlDotNet is smaller, and if you need HTTP input or output formatting, the sibling ASP.NET Core packages in this repository are the better fit.