C# YAML
last modified July 12, 2023
In this article we show how to work with the YAML format in C# using the
YamlDotNet library.
YAML format
YAML (YAML Ain't Markup Language) is a human-readable data-serialization language. It is commonly used for configuration files, but it is also used in data storage (e.g. debugging output) or transmission (e.g. document headers).
YAML natively supports three basic data types: scalars (such as strings, integers, and floats), lists, and associative arrays.
The .yaml is the official recommended filename extension for YAML
files.
YamlDotNet is a .NET library for YAML.
$ package add YamlDotNet
We add the library to the project.
C# YamlStream
YamlStream allows us to read YAML data via a stream.
using YamlDotNet.RepresentationModel;
string doc = @"
cities:
- Bratislava
- Kosice
- Trnava
- Moldava
- Trencin
name: John Doe
occupation: gardener";
using var sr = new StringReader(doc);
var yaml = new YamlStream();
yaml.Load(sr);
var root = (YamlMappingNode) yaml.Documents[0].RootNode;
foreach (var e in root.Children)
{
Console.WriteLine(e);
Console.WriteLine($"{e.Key} {e.Value}");
}
Console.WriteLine("------------------------------");
Console.WriteLine(root["name"]);
Console.WriteLine(root["occupation"]);
Console.WriteLine(root["cities"]);
In the example, we read YAML from a string using YamlStream.
string doc = @"
cities:
- Bratislava
- Kosice
- Trnava
- Moldava
- Trencin
name: John Doe
occupation: gardener";
This is the YAML data defined inside a C# string.
using var sr = new StringReader(doc); var yaml = new YamlStream(); yaml.Load(sr);
We pass the string to the StringReader. The
StringReader is then loaded to the YamlStream with
Load.
var root = (YamlMappingNode) yaml.Documents[0].RootNode;
We get the root node of the document.
foreach (var e in root.Children)
{
Console.WriteLine(e);
Console.WriteLine($"{e.Key} {e.Value}");
}
We iterate over the children of the root node. Each node has a key and value.
Console.WriteLine(root["name"]); Console.WriteLine(root["occupation"]); Console.WriteLine(root["cities"]);
This is another way to access the keys.
$ dotnet run [cities, [ Bratislava, Kosice, Trnava, Moldava, Trencin ]] cities [ Bratislava, Kosice, Trnava, Moldava, Trencin ] [name, John Doe] name John Doe [occupation, gardener] occupation gardener ------------------------------ John Doe gardener [ Bratislava, Kosice, Trnava, Moldava, Trencin ]
YAML documents
YAML documents are separated with ---.
name: Document 1 cities: - Bratislava - Kosice - Trnava - Moldava - Trencin --- name: Document 2 companies: - Eset - Slovnaft - Duslo Sala - Matador Puchov
We have two documents in the YAML file.
using YamlDotNet.RepresentationModel;
string data = File.ReadAllText("data.yaml");
using var sr = new StringReader(data);
var yaml = new YamlStream();
yaml.Load(sr);
int n = yaml.Documents.Count;
for (int i = 0; i < n; i++)
{
var root = (YamlMappingNode)yaml.Documents[i].RootNode;
foreach (var e in root.Children)
{
Console.WriteLine($"{e.Key} {e.Value}");
}
Console.WriteLine("-------------------------------");
}
The program reads both documents with YamlStream.
string data = File.ReadAllText("data.yaml");
We read the data from the file into a string with File.ReadALlText.
int n = yaml.Documents.Count;
We get the number of documents using Count.
for (int i = 0; i < n; i++)
{
var root = (YamlMappingNode)yaml.Documents[i].RootNode;
foreach (var e in root.Children)
{
Console.WriteLine($"{e.Key} {e.Value}");
}
Console.WriteLine("-------------------------------");
}
We iterate over the children of the documents.
$ dotnet run name Document 1 cities [ Bratislava, Kosice, Trnava, Moldava, Trencin ] ------------------------------- name Document 2 companies [ Eset, Slovnaft, Duslo Sala, Matador Puchov ]
Serialize data
YAML serializing is the process of transforming C# objects into YAML strings.
This is done with the SerializerBuilder.
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;
var users = new List<User>
{
new ("John Doe", "gardener") ,
new ("Roger Roe", "driver") ,
new ("Valeria Smith", "teacher"),
};
var serializer = new SerializerBuilder()
.WithNamingConvention(CamelCaseNamingConvention.Instance)
.Build();
var yaml = serializer.Serialize(users);
Console.WriteLine(yaml);
record User(string Name, string Occupation);
The program transforms a list of User objects into a YAML string.
var serializer = new SerializerBuilder()
.WithNamingConvention(CamelCaseNamingConvention.Instance)
.Build();
We create the SerializerBuilder and configure it.
var yaml = serializer.Serialize(users);
We serialize the data using the Serialize method.
$ dotnet run - name: John Doe occupation: gardener - name: Roger Roe occupation: driver - name: Valeria Smith occupation: teacher
Deserialize data
Deserializing is the process of transforming a YAML string into C# objects.
- Name: John Doe Occupation: gardener - Name: Roger Roe Occupation: driver - Name: Valeria Smith Occupation: teacher
We have a list of users in the users.yaml file.
using YamlDotNet.Serialization;
var deserializer = new DeserializerBuilder()
.Build();
using var sr = File.OpenText("users.yaml");
List<User> users = deserializer.Deserialize<List<User>>(sr);
foreach (var user in users)
{
Console.WriteLine(user);
}
class User
{
public string? Name { get; set; }
public string? Occupation { get; set; }
public override string ToString()
{
return $"{this.Name} {this.Occupation}";
}
}
In the program, we read the data from the file and deserialize it into a list
of User objects.
$ dotnet run John Doe gardener Roger Roe driver Valeria Smith teacher
Source
In this article we worked with the YAML format in C# using the
YamlDotNet library.
Author
List all C# tutorials.
