Работа с YAML в C# (.NET) | YamlDotNet

Работа с YAML в C# (.NET): библиотека YamlDotNet

YAML (YAML Ain't Markup Language) — это удобный формат сериализации данных, который часто используется для конфигурационных файлов, описания CI/CD пайплайнов, Docker Compose и Kubernetes манифестов. В экосистеме .NET для работы с YAML основной библиотекой является YamlDotNet — мощный, производительный и полностью совместимый со спецификацией YAML 1.1 и 1.2 инструмент.

В этой статье мы разберём: как установить YamlDotNet, выполнить базовую сериализацию и десериализацию объектов C#, настроить кастомные теги и обработать сложные структуры данных.

Установка YamlDotNet

Библиотека доступна через NuGet. Выполните команду в консоли диспетчера пакетов:

dotnet add package YamlDotNet

Или через Package Manager Console:

Install-Package YamlDotNet

Базовое использование: десериализация YAML в объект C#

Допустим, у нас есть YAML-файл config.yaml с настройками приложения:

app:
  name: MyApp
  version: 2.0.1
  debug: true
database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret

Создадим соответствующие классы C#:

public class AppConfig
{
    public string Name { get; set; }
    public string Version { get; set; }
    public bool Debug { get; set; }
}

public class DatabaseConfig
{
    public string Host { get; set; }
    public int Port { get; set; }
    public CredentialsConfig Credentials { get; set; }
}

public class CredentialsConfig
{
    public string User { get; set; }
    public string Password { get; set; }
}

public class RootConfig
{
    public AppConfig App { get; set; }
    public DatabaseConfig Database { get; set; }
}

Теперь десериализуем YAML в объект:

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

var yamlContent = File.ReadAllText("config.yaml");

var deserializer = new DeserializerBuilder()
    .WithNamingConvention(UnderscoredNamingConvention.Instance) // для snake_case
    .Build();

var config = deserializer.Deserialize<RootConfig>(yamlContent);

Console.WriteLine(config.App.Name);        // MyApp
Console.WriteLine(config.Database.Port);   // 5432

Сериализация объектов C# в YAML

Обратная задача — превратить объект C# в YAML-строку:

var config = new RootConfig
{
    App = new AppConfig { Name = "MyApp", Version = "2.0.1", Debug = true },
    Database = new DatabaseConfig
    {
        Host = "localhost",
        Port = 5432,
        Credentials = new CredentialsConfig { User = "admin", Password = "secret" }
    }
};

var serializer = new SerializerBuilder()
    .WithNamingConvention(CamelCaseNamingConvention.Instance) // camelCase в YAML
    .Build();

var yaml = serializer.Serialize(config);
Console.WriteLine(yaml);

Результат:

app:
  name: MyApp
  version: 2.0.1
  debug: true
database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret

Работа с коллекциями и сложными типами

YamlDotNet отлично поддерживает списки, словари и вложенные структуры. Пример со списком:

public class Project
{
    public string Name { get; set; }
    public List<string> Tags { get; set; }
}

// YAML:
// name: MyProject
// tags:
//   - dotnet
//   - yaml
//   - csharp

var yaml = @"
name: MyProject
tags:
  - dotnet
  - yaml
  - csharp
";

var deserializer = new DeserializerBuilder().Build();
var project = deserializer.Deserialize<Project>(yaml);

foreach (var tag in project.Tags)
    Console.WriteLine(tag);

Кастомные теги и типы (TagMapping)

Иногда YAML-файлы содержат явные теги (например, !!str или !MyType). YamlDotNet позволяет сопоставлять теги с конкретными типами C#:

public class CustomData
{
    public string Value { get; set; }
}

var yaml = @"!custom
value: hello";

var deserializer = new DeserializerBuilder()
    .WithTagMapping("!custom", typeof(CustomData))
    .Build();

var result = deserializer.Deserialize<CustomData>(yaml);
Console.WriteLine(result.Value); // hello