Table of Contents

Bodu serializer guides

Recipe-style walk-throughs for the three Bodu serializers - Bodu.Text.Bencode (BencodeSerializer), Bodu.Text.Toml (TomlSerializer), and Bodu.Text.Yaml (YamlSerializer). The libraries share an architecture and a System.Text.Json-aligned shape, so a pattern learned in one transfers to the next by swapping the Bencode / Toml / Yaml prefix. Each library has its own guide set below, written against its real surface.

If you are new to the family, start with the introduction for the three-tier mental model (serializer, DOMs, reader/writer) and how to choose a format, then open the guide hub for the library you need.

Per-library guides

TOML guides

TomlSerializer - type mapping, spec-version selection (v1.0.0 / v1.1.0), both DOMs, the full attribute family, converters and factories, callbacks, and the built-in catalog.

Bencode guides

BencodeSerializer - byte strings as first-class values, canonical key ordering, a torrent-style worked example, the full attribute family, converters and factories, callbacks, and the built-in catalog.

YAML guides

YamlSerializer - type mapping, the 1.2 core schema (opt-in 1.1 typing), both DOMs, multi-document streams, member shaping with the shared Bodu.Text.Serialization attributes and naming policies, custom converters, and the built-in catalog.

Cross-format guides

These guides apply to every serializer in the family - the three above and the three line formats - because they describe the shared Bodu.Text.Serialization layer and the options lifecycle all six implement.

Migrating from System.Text.Json

The rename table - attributes, options, converters, naming policies, callbacks, DOMs, using directives - followed by the behavioral differences: null handling per format, string-only line formats, YAML implicit typing, the two exception types.

Serializer options: freezing, caching, and thread safety

First-use freeze and MakeReadOnly, IsReadOnly, the InvalidOperationException on a frozen instance, converter resolution order, what is cached, sharing one instance across threads, and the <Format>SerializerDefaults presets.

Suggested reading path

  1. Introduction - the shared shape and how to choose a format.
  2. The guide hub for your library - TOML, Bencode, or YAML - starting with its Using… walk-through.
  3. Mapping attributes and naming policies - declarative shaping covers most customization needs.
  4. Writing converters - when a type needs a wire form the defaults do not provide; check the built-in catalog first so you do not rewrite a provisioned one.
  5. Serializer options: freezing, caching, and thread safety - once the options carry converters, learn when they freeze and how to share them. Coming from System.Text.Json? Start instead with the migration guide.

Where to go next