Огляд стандартних класів серіалізації в .NET

1. Вступ

Раз ми вже вирішили «розбирати фігурку LEGO на деталі», давайте з’ясуємо, які інструменти у нас є для цього у .NET. Іншими словами — які стандартні класи допомагають серіалізувати й десеріалізувати об’єкти в різні формати та що стоїть за кожним із них.

Як влаштовано сімейство серіалізації .NET

Станом на 2025 р. .NET пропонує кілька основних підходів до серіалізації, кожен із власним набором класів та інструментів. Основні й найуживаніші:

• JSON-серіалізація — основний і найсучасніший варіант, застосовується в більшості проєктів.
• XML-серіалізація — дещо старомодніша, але досі активно використовується.
• Бінарна серіалізація — лише для окремих випадків і зазвичай через сучасні сторонні бібліотеки.

Багато прикладів і значна частина коду у .NET 9 використовують саме JSON, і це не мода — це галузевий стандарт. Але .NET підтримує й інші способи — за потреби.

Головні герої серіалізації в .NET

System.Text.Json

System.Xml.Serialization.XmlSerializer

Коротко про кожен

• System.Text.Json: Новий стандарт серіалізації JSON у .NET, з’явився в .NET Core 3.0, став основним у .NET 5+. Швидкий, легкий, безпечний, вбудований «з коробки» у .NET 9. Документація
• XmlSerializer: Старий і перевірений варіант для серіалізації в XML. Простий у використанні, але з обмеженнями (наприклад, потрібен public-клас і публічні властивості). Добрий для сумісності та строгих контрактів даних. Документація
• Newtonsoft.Json: Тривалий час був де-факто стандартом JSON-серіалізації до появи System.Text.Json. Часто використовується для складних сценаріїв (динамічні типи, приватні властивості тощо). Документація

Куди подівся BinaryFormatter?

Якщо ви натрапите в інтернеті на поради використовувати BinaryFormatter, найімовірніше, це застарілий матеріал. Не використовуйте BinaryFormatter: його вилучено з .NET 9 із міркувань безпеки. Сучасну бінарну серіалізацію забезпечують сторонні рішення — наприклад, Protobuf або MessagePack.

2. Прості приклади

Спробуймо застосувати на практиці серіалізацію та десеріалізацію на прикладі нашого вже знайомого класу Player з ігрового всесвіту.

Підготуємо клас до серіалізації

// Player.cs
public class Player
{
    public string Name { get; set; }
    public int Health { get; set; }
    public bool IsAlive { get; set; }
    public List<string> Inventory { get; set; }
    public Position Position { get; set; }
}

public class Position
{
    public int X { get; set; }
    public int Y { get; set; }
}

a) Серіалізація та десеріалізація в JSON за допомогою System.Text.Json

using System.Text.Json;

Player aragorn = new Player
{
    Name = "Aragorn",
    Health = 100,
    IsAlive = true,
    Inventory = new List<string> { "sword", "bow", "healing potion" },
    Position = new Position { X = 10, Y = 25 }
};

// Серіалізація об’єкта Player у рядок JSON
string json = JsonSerializer.Serialize(aragorn);
// Виведемо JSON на екран
Console.WriteLine(json);

// Десеріалізація рядка JSON назад у об’єкт Player
Player? aragornClone = JsonSerializer.Deserialize<Player>(json);
// Перевіримо, чи працює клон :)
Console.WriteLine(aragornClone?.Name); // Має вивести "Aragorn"

І все просто — жодних хитрощів і «магічних» атрибутів. Тепер подивімося, як це виглядає в XML.

b) Серіалізація та десеріалізація в XML за допомогою XmlSerializer

using System.Xml.Serialization;

// Налаштуємо серіалізатор для класу Player
XmlSerializer serializer = new XmlSerializer(typeof(Player));

// Серіалізація у файл
using FileStream fs = new FileStream("aragorn.xml", FileMode.Create);
serializer.Serialize(fs, aragorn); // Зберігаємо Aragorn у XML-файл

// Десеріалізація з файлу
using FileStream fs = new FileStream("aragorn.xml", FileMode.Open);
Player aragornFromXml = (Player) serializer.Deserialize(fs)!;
Console.WriteLine(aragornFromXml.Name); // Має вивести "Aragorn"

Зверніть увагу! XmlSerializer вимагає, щоб класи та їхні властивості були публічними і мали порожній конструктор за замовчуванням (якщо визначаєте власний конструктор — зробіть його public і без параметрів). Інакше серіалізація завершиться помилкою.

c) Серіалізація та десеріалізація в JSON за допомогою Newtonsoft.Json

using Newtonsoft.Json; // Не забудьте додати пакет Newtonsoft.Json через NuGet!

// Серіалізація
string json2 = JsonConvert.SerializeObject(aragorn);

// Десеріалізація
Player? aragornFromNewtonsoft = JsonConvert.DeserializeObject<Player>(json2);

Console.WriteLine(aragornFromNewtonsoft?.Name); // Знову "Aragorn"

Виглядає майже так само, але в Newtonsoft.Json є багато додаткових опцій — наприклад, можна серіалізувати приватні поля, налаштовувати форматування та вирішувати нетривіальні сценарії.

3. Корисні нюанси

Стандартні серіалізатори та їхні можливості

System.Text.Json

Newtonsoft.Json

XmlSerializer

Як зрозуміти, який клас використовувати?

Якщо ви не знаєте, навіщо вам XML — майже завжди обирайте JSON і System.Text.Json. Це швидше, простіше й відповідає сучасним практикам.

XML варто обирати, якщо:

• Ви інтегруєтеся зі старими системами, які вимагають саме XML.
• Потрібні строга схема та валідація структури даних.
• Структури великі, стабільні і важлива формальна сумісність (налаштування, конфіги, обмін із корпоративними системами).

JSON — якщо:

• Створюєте сучасний застосунок, взаємодієте з вебом і мобільними пристроями.
• Потрібні простота, читабельність і компактність.
• Не хочете додавати зайві залежності.

Newtonsoft.Json — якщо:

• Потрібна серіалізація приватних полів, особливі налаштування, повна гнучкість.
• Або проєкт уже використовує цю бібліотеку, і міграція зараз недоречна.

4. Типові помилки та підводні камені

Кодування. Основні класи серіалізації (особливо під час роботи з файлами) використовують стандартне UTF-8. Якщо бачите некоректні символи, перевірте, як ви читаєте/пишете файли, і за потреби встановіть кодування явно. Документація з налаштування кодування.

Непідтримувані типи. Деякі стандартні серіалізатори (особливо XML) не вміють серіалізувати, наприклад, словники (Dictionary), приватні чи protected-поля, події, делегати й інтерфейси. Зазвичай підтримуються публічні прості властивості та класи.

Версії класів. Якщо ви змінюєте структуру класів (додаєте/перейменовуєте/видаляєте властивості), старі збережені дані можуть не прочитатися або десеріалізуватися некоректно. Плануйте версіонування форматів.

Значення null. Під час десеріалізації, якщо в даних немає якогось поля, відповідна властивість отримає значення за замовчуванням (для посилального типу — null). Не забувайте про перевірки.

Атрибути. Для тонкого налаштування часто використовують атрибути на кшталт [JsonIgnore], [XmlElement] тощо. Вони дають змогу виключати властивості, змінювати імена елементів і керувати форматом — подробиці в наступних лекціях.