How to work with YAML in .NET with YamlDotNet

YamlDotNet is a C# library that allows working with YAML files in .NET applications.

YAML (Yet Another Markup Language) is a plain text file format used to represent structured data, such as configurations or resource definitions.

It is an alternative to other formats like JSON or XML, and is frequently used in configuration files. For example, it is common to find it in ‘frontmatter’ in markdown documents.

YamlDotNet allows us to deserialize YAML format very easily. It provides compatibility with all YAML features, including annotations, resource references, etc.

It has also been designed to offer high optimization. Therefore, you can expect high performance, even when working with large files.

It is compatible with .NET Framework, .NET Standard 2.0 and 2.1, and .NET 6.0 or later.

How to use YamlDotNet

We can easily add the library to a .NET project through the corresponding Nuget package.

Install-Package YamlDotNet

Here are some examples of how to use YamlDotNet to work with YAML files in C#, taken from the library’s documentation.

Serialize an object to a string

To serialize an object, we only have to instantiate a Serializer and call the ‘Serialize’ method. It’s that simple.

using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

// Sample object
var person = new Person
{
    Name = "Abe Lincoln",
    Age = 25,
    HeightInInches = 6f + 4f / 12f,
    Addresses = new Dictionary<string, Address>{
        { "home", new  Address() {
                Street = "2720  Sundown Lane",
                City = "Kentucketsville",
                State = "Calousiyorkida",
                Zip = "99978",
            }},
        { "work", new  Address() {
                Street = "1600 Pennsylvania Avenue NW",
                City = "Washington",
                State = "District of Columbia",
                Zip = "20500",
            }},
    }
};

// Serialize
var serializer = new SerializerBuilder()
    .WithNamingConvention(CamelCaseNamingConvention.Instance)
    .Build();
var yaml = serializer.Serialize(person);
System.Console.WriteLine(yaml);

Which would result in the following YAML content in the string.

name: Abe Lincoln
age: 25
heightInInches: 6.3333334922790527
addresses:
  home:
    street: 2720  Sundown Lane
    city: Kentucketsville
    state: Calousiyorkida
    zip: 99978
  work:
    street: 1600 Pennsylvania Avenue NW
    city: Washington
    state: District of Columbia
    zip: 20500

Deserialize a string to an object

Deserializing is basically similar. We only have to create a Deserializer and call the ‘Deserialize’ method.

using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;
...

// Our string with the yaml
var yml = @"
name: George Washington
age: 89
height_in_inches: 5.75
addresses:
  home:
    street: 400 Mockingbird Lane
    city: Louaryland
    state: Hawidaho
    zip: 99970
";

// Deserialize
var deserializer = new DeserializerBuilder()
    .WithNamingConvention(UnderscoredNamingConvention.Instance)
    .Build();

var person = deserializer.Deserialize<Person>(yml);

Which would result in ‘person’ containing our object with all properties correctly filled, including child members and collections.

YamlDotNet is Open Source, and all the code and documentation is available in the project’s repository at https://github.com/aaubry/YamlDotNet