LuisLlamas Logo
yamldotnet

How to work with YAML in .NET with YamlDotNet

  • 3 min

YamlDotNet is a C# library that allows you to work 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.

Furthermore, it has 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 add the library to a .NET project easily, through the corresponding Nuget package.

Install-Package YamlDotNet

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

Serialize an Object to String

To serialize an object, we only need 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);
Copied!

This would result in the following YAML contained 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
Copied!

Deserialize a String to an Object

Deserializing is basically similar. We only need 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);
Copied!

This would give us as a result in ‘person’ 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 repository at https://github.com/aaubry/YamlDotNet

On this page