Introduction

Meziantou.Framework.Yaml reads and writes YAML in .NET. It converts your classes to YAML and back, gives you a model of a document to inspect or change it without a class, keeps the exact text of a file for tools that must not disturb it, and generates the serialization code at build time for NativeAOT and trimmed applications.

What you can do with it

• Read and write configuration files and other YAML data as .NET objects: classes, records, collections, dictionaries, enums and the common scalar types. See Serialization.
• Choose the shape of the YAML: naming policies, ignored members, indentation, flow or block collections, quoted or block strings. See Members and names and Output format.
• Serialize class hierarchies and C# unions, identified by a key or a YAML tag. See Polymorphism and C# unions.
• Keep shared references as anchors and aliases, and read merge keys (<<). See Anchors, aliases and merge keys.
• Serialize without reflection: the source generator ships in the package and creates the metadata at build time. See Source generation.
• Work with documents without a class: load a document, navigate it, change it and write it back. See Document object model.
• Build tools such as linters and formatters: the syntax tree keeps the comments and the whitespace, with the position of every token. See Syntax tree.
• Stream over large documents event by event, and write YAML event by event. See Parser and emitter.
• Read untrusted documents safely: limit the depth, the aliases and the anchors. See Reading untrusted YAML.

Supported YAML

The library implements YAML 1.2. A document that declares %YAML 1.1, %YAML 1.2 or a later 1.x version is read with the YAML 1.2 rules; other versions throw a SemanticErrorException. Streams of several documents, %TAG directives, block and flow collections, the five scalar styles (plain, single-quoted, double-quoted, literal and folded), anchors, aliases, merge keys, tags and comments are supported.

Choose an API

The library has four layers. Use the highest one that does what you need:

The layers work together: a member of a serialized class can hold a document node, and a node converts to and from an object.

Namespaces

Next steps

• Getting started: install the package, serialize a class and read a document.
• Serialization: everything about converting objects.
• Source generation: serialize in NativeAOT and trimmed applications.