Bodu.Text.Yaml.Serialization Namespace

Package

Bodu.Text.Yaml 1.0.0

Purpose

Bodu.Text.Yaml.Serialization holds the extensibility surface of the YamlSerializer: the converter base types you derive from to control how a CLR type is written and read, and the built-in enum converters. A converter reads through the Utf8YamlReader and writes through the Utf8YamlWriter. The attribute family, naming policies, and serialization callbacks it works with are shared across formats and live in Bodu.Text.Serialization.

Key types

• YamlConverter - the non-generic root (CanConvert) that YamlSerializerOptions.Converters holds.
• YamlConverter<T> - the per-type base: implement Read and Write for T.
• YamlConverterFactory - the base for converter families: CanConvert plus CreateConverter for a closed type.
• YamlStringEnumConverter / YamlStringEnumConverter<TEnum> - enums as member-name strings, with an optional NamingPolicy and integer fallback.
• YamlNumberEnumConverter<TEnum> - enums as their underlying integer.

Example

using Bodu.Text.Yaml;
using Bodu.Text.Yaml.Reader;
using Bodu.Text.Yaml.Serialization;
using Bodu.Text.Yaml.Writer;

public sealed class VersionConverter : YamlConverter<Version>
{
    public override Version Read(ref Utf8YamlReader reader, Type typeToConvert, YamlSerializerOptions options) =>
        Version.Parse(reader.GetString());

    public override void Write(Utf8YamlWriter writer, Version value, YamlSerializerOptions options) =>
        writer.WriteString(value.ToString());
}

var options = new YamlSerializerOptions();
options.Converters.Add(new VersionConverter());

Notes

• Scalar converters are format-local. YAML's implicit typing coerces across scalar kinds (string / integer / float / boolean / null), so the built-in scalar converters live here rather than in the shared engine; the structural (nullable, collection, dictionary, object) factories are the shared ones.
• Resolution order. A [Converter] attribute on the member or type wins, then Converters in registration order, then the built-in catalog.
• Internal converters. The Bodu.Text.Yaml.Serialization.Converters sub-namespace is internal; extend through the public base types above.
• See also: the Bodu.Text.Yaml introduction and the writing converters guide.

Classes

YamlConverter

Serves as the non-generic base for custom YAML converters, in the manner of JsonConverter.

YamlConverterFactory

Produces a YamlConverter for a family of types that cannot be served by a single YamlConverter<T> - for example every Nullable<T>, every enumeration, or every collection.

YamlConverter<T>

Serves as the strongly-typed base for custom YAML converters that read and write values of type T. This is the base authors derive to customize how a specific type is serialized.

YamlNumberEnumConverter<TEnum>

Produces a converter that serializes the enumeration TEnum as a YAML integer scalar carrying its underlying numeric value.

YamlStringEnumConverter

Produces a converter that serializes any enumeration as a YAML string holding its member name, applying an optional naming policy and honoring StringEnumMemberNameAttribute on individual members.

YamlStringEnumConverter<TEnum>

Produces a converter that serializes the enumeration TEnum as a YAML string holding its member name, applying an optional naming policy and honoring StringEnumMemberNameAttribute on individual members.