System.Text.Json. Серіалізація та десеріалізація

18.6. System.Text.Json. Серіалізація та десеріалізація

Текстові та бінарні потоки з попередніх розділів вирішують питання як зберегти байти. Але сучасний застосунок рідко оперує сирими байтами — він оперує об'єктами: пацієнтами, аналізами, рецептами, планами лікування. Зберегти об'єкт C# у файл або передати через мережу означає його серіалізувати — перетворити граф об'єктів у послідовність байтів. Зворотний процес — десеріалізація: відновити об'єкти зі збереженого представлення.

Найпоширеніший формат для серіалізації у сучасних застосунках — JSON (JavaScript Object Notation). Він людиночитабельний, підтримується всіма мовами і платформами, і є стандартом де-факто для REST API, конфігурацій та обміну даними між сервісами.

Починаючи з .NET Core 3.0, платформа включає System.Text.Json — вбудовану бібліотеку серіалізації JSON, оптимізовану для продуктивності. Вона замінила сторонній Newtonsoft.Json (Json.NET) як основний інструмент для більшості задач.

JsonSerializer — базова серіалізація та десеріалізація

Центральний клас бібліотеки — JsonSerializer. Два основних методи: Serialize (об'єкт → рядок JSON) і Deserialize (рядок JSON → об'єкт).

Зверніть увагу на поведінку за замовчуванням: імена властивостей записуються так само, як у C# (PascalCase), значення null включаються, enum записується числом, а при читанні імена властивостей чутливі до регістру (JSON {"id":1} не заповнить властивість Id). Кирилиця за замовчуванням екранується як \u0416 — це коректний JSON, але для людського читання задають Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping (або JavaScriptEncoder.Create(UnicodeRanges.All)). Усе це змінюється через JsonSerializerOptions нижче.

Ще одна особливість .NET 10: у файлових застосунках (dotnet run app.cs) за замовчуванням увімкнено Native AOT, а з ним вимкнено серіалізацію через рефлексію — виклик JsonSerializer.Serialize(obj) кине InvalidOperationException. Для таких скриптів додайте директиву #:property PublishAot=false першим рядком або використовуйте генератор вихідного коду JsonSerializerContext. У звичайних проєктах .csproj цього обмеження немає.

JsonSerializer.Serialize без опцій генерує компактний JSON без пробілів — це оптимально для мережевої передачі. WriteIndented = true додає відступи для читабельності — зручно для конфігурацій і логів.

Серіалізація до файлу та з файлу

Найчастіший сценарій — збереження об'єктів у файл і завантаження з файлу. JsonSerializer інтегрується зі Stream:

Передача Stream у JsonSerializer.Serialize/Deserialize ефективніша за string-варіант: бібліотека пише напряму у потік без проміжного рядкового буфера — важливо для великих об'єктів.

JsonSerializerOptions — налаштування серіалізації

JsonSerializerOptions — центральний об'єкт конфігурації, що контролює практично всі аспекти серіалізації:

Типові JsonSerializerOptions для медичного застосунку

Атрибути керування серіалізацією

System.Text.Json надає атрибути для тонкого контролю над кожним полем і класом:

Атрибут	Призначення
[JsonPropertyName("name")]	Задає ім'я поля у JSON
[JsonIgnore]	Виключає поле з серіалізації
[JsonIgnore(Condition = ...)]	Умовне виключення (null, default)
[JsonPropertyOrder(n)]	Порядок полів у виводі
[JsonInclude]	Включає публічне поле (field, не property)
[JsonRequired]	Поле обов'язкове при десеріалізації
[JsonConverter(typeof(...))]	Кастомний конвертер для типу

Робота з вкладеними структурами та колекціями

Практичний сценарій: JSON-конфігурація медичного застосунку