В своем подходе к обучению я применяю довольно простую схему - у меня есть репозиторий, и каждый раз, когда я сталкиваюсь с новой для себя технологией - я иду туда, создаю папку-подпапку, в ней .cs файл и решаю какую-то проблему, применяя изученное. Если теоретическая составляющая темы слишком обширна, чтобы запихнуть ее в голову и комментарии к коду, я пишу конспекты в .md формат.
Недавно я актуализировал конспект по сериализации, и мне пришла идея - почему бы не вытесать из этого статью.

В этой статье мы пройдемся по тому как сериализация работает, основным форматам и языкам разметки, а также объединим знания об использовании .NET System.Text.Json в формат напоминалки. Сразу же отмечу два дисклеймера:

1. Это личная база знаний, над которой была проведена большая редакторская работа, я старался оформить данные в формат напоминалки, к которой можно вернуться в любое время, поэтому местами могут встретиться грубые упрощения и не-академическая терминология.

2. Мы довольно подробно поговорим об XML и SOAP, однако работы с классом XmlSerializer вы здесь не увидите. Причины можно найти в данном видеофрагменте. А если серьезно - мне просто не довелось применить данный вид сериализации на практике, но знание основ XML не навредит. О BinaryFormatter и ISerializable речи идти вовсе не будет, так как грядущий .NET 9 захлопнет крышку этого гроба окончательно.

Примечание: Хабр не очень дружит с переносом строки внутри блоков кода, для удобства чтения раздутых XML и комментариев - используйте Shift+Колесико мыши. Возможно, отоспавшись, я оформлю переносы вручную.

Оглавление:

1. Форматы и языки разметки

   • JSON

   • XML

     • XSD - XML схемы

     • SOAP

   • YAML

2. System.Text.Json

   • Основы System.Text.Json

   • Иммутабельные типы и заполнение

   • Обработка ссылок. $id и $ref

   • Полиморфизм

   • Json Document Object Model

   • UTF8Json Writer/Reader

   • Реализация JsonConverter

   • Контракты

   • Режимы сериализации

Сериализация

Сериализация - процесс преобразования объекта среды выполнения в форму, пригодную для дальнейшей транспортировки. Выражаясь простым языком, это процесс записи данных объекта в памяти, то есть класса или структуры, в такую форму, которую можно передать по сети, сохранить на диске, использовать между процессами и так далее. Десериализация, соотвественно, обратный процесс восстановления состояния объекта из формата транспортировки.

Обычно это текстовые форматы вроде JSON или языки разметки YAML, XML, SOAP и прочие. Например, бинарные сериализаторы пишут непосредственно байты в стрим назначения, хотя, если углубиться в тему - всё перечисленное также проходит процесс кодировки (обычно используя UTF-8), и уже парсеры, разрабатываемые авторами форматов, восстанавливают состояние благодаря строгим протоколам оформления данных.

Форматы и языки разметки

JSON

JSON (JavaScript Object Notation) — это легковесный текстовый формат для представления структурированных данных в виде пар ключ-значение, композитных объектов, состоящих из этих пар, а также JSON-массивов. JSON изначально был основан на синтаксисе JavaScript, но является языконезависимым и поддерживается большинством современных языков программирования.

Представление данных в формате JSON:

• Простые классы и структуры состоят из JSON-свойств (или JSON Value). Свойство выглядит как пара "name":value, или, если вам так привычнее, "key":value.

  public class SomeData
  {
      public float pi { get; set; } = 3.14f;
      public bool b { get; set; } = false;
      public char c { get; set; } = 'c';
      public object? o { get; set; } = null;
      public string s { get; set; } = "Some Text";
  }
  

  {
    "pi": 3.14,
    "b": false,
    "c": "c",
    "o": null,
    "s": "Some Text"
  }
  

• Композитные объекты (JSON Object) заключаются в фигурные скобки {}, внутри которых содержатся свойства, которые также могут представлять собой объекты. Размер такого дерева вложенных объектов называется глубиной сериализации.
  К слову, когда мы сериализуем сам корневой объект, он также начинается с фигурных скобок:

  public class SomeData
  {
      public float pi { get; set; } = 3.14f;
      public bool b { get; set; } = false;
      public char c { get; set; } = 'c';
      public Vector2 ComplexStruct { get; set; } = new(1.5f, 2.7f);
  }
  

  { // Начало SomeData
    "pi": 3.14,
    "b": false,
    "c": "c",
    "ComplexStruct": { // Начало Vector2
      "X": 1.5,
      "Y": 2.7
    } // Конец Vector2 
  } // Конец SomeData
  

• Коллекции. Стоит отметить, что разные реализации фреймворков сериализуют коллекции, соответственно, по разному. Массивы, листы, очереди и прочие сериализуются в виде обычного JsonArray.
  А вот сериализация, например, словаря, будет выглядеть как объект, свойства которого являются парами "key":value.
  Синтаксис Json массивов, в данном случае сериализуется массив строк:

  "someValues": 
  [
      "first",
      "second",
      "third"
  ]
  

• Логические единицы, то есть простые свойства, объекты, массивы и элементы внутри них разделяются запятыми. Когда мы видим упоминание "trailing commas" где-либо, это означает обработку хвостовых запятых, за которыми не следует еще один элемент, иногда это может вызывать ошибки.

• Для сериализации специфических типов, например, словарей, ключом которых выступает композитный объект, может потребоваться предоставить свою реализацию алгоритмов конвертации и разрешения типов.

XML

XML (расширяемый язык разметки) — это язык разметки, предназначенный для хранения и передачи данных в формате, удобном для обработки компьютером. Синтаксис XML основывается на тегах, определяемых пользователем. XML также допускает атрибуты, экранирование (escape characters), комментарии, пространства имен и валидацию при помощи схем. Правильно составленный XML документ называют well-formed.

Общий синтаксис XML для C# объекта будет выглядеть так:

• Простые свойства(элементы), имя указывается в открывающемся и закрывающемся теге, значение указывается между ними. Также,
  тег может быть самозакрывающимся, используя синтаксис <tag/>.

  public class SomeData
  {
      public float pi { get; set; } = 3.14f;
      public bool b { get; set; } = false;
      public char c { get; set; } = 'c';
      public string s { get; set; } = "Some Text";
  }
  

  <?xml version="1.0" encoding="UTF-8"?> <!--Этого мы коснемся позже-->
  <SomeData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <pi>3.14</pi>
    <b>false</b>
    <c>c</c>
    <s>Some Text</s>
  </SomeData>
  

• Вы могли обратить внимание на атрибуты вроде xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". Значение некоторых мы рассмотрим позже. Говоря о самих атрибутах - они являются частью XML тегов, синтаксически выглядят как attribute="value", не разделяются запятыми, если атрибутов несколько. Атрибуты это такие же данные, записываемые пользователем или программой, общепринятой практикой считается размещение в них метаданных, то есть "информации об информации", вторая "информация" в данном случае это значение XML-элемента, например:

  <Order time="8/18/2010 4:32:00"> <!--Метаданные о времени заказа-->
    <ID>114</ID>
  </Order>
  

• Композитные объекты работают по тем же правилам.

  <?xml version="1.0" encoding="UTF-8"?>
  <SomeData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <pi>3.14</pi>
    <b>false</b>
    <c>с</c>
    <ComplexStruct> <!--Композитный объект. Кстати, это комментарий. -->
      <X>1.5</X>
      <Y>2.7</Y>
    </ComplexStruct>
  </SomeData>
  

• Коллекции не имеют какого-либо специфического синтаксиса. Однако, можем заметить, что теги элементов внутри массивов используют тип элемента в качестве имени, хотя это поведение можно переопределить разными конфигурациями.

  <?xml version="1.0" encoding="UTF-8"?>
  <SomeData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <values>
      <string>first</string>
      <string>second</string>
      <string>third</string>
    </values>
  </SomeData>
  

• XML поддерживает escape sequences (экранирование) для зарезервированных символов < > & ' ". К слову, единственные места, где можно использовать эти символы напрямую это комментарии и блоки CDATA.

  Экранируемые символы

  &lt; — представляет символ < (открывающая угловая скобка).
  &gt; — представляет символ > (закрывающая угловая скобка).
  &amp; — представляет символ & (амперсанд).
  &quot; — представляет символ " (двойная кавычка).
  &apos; — представляет символ ' (одинарная кавычка).
  

• Отличие CDATA от комментария заключается в том, что комментарий не является частью XML документа и игнорируется парсерами, тогда как CDATA (character data) является частью данных XML, внутри которой текст располагается "сырым" (это можно сравнить с raw string в C#).

  <?xml version="1.0" encoding="UTF-8"?>
  
  <SomeData>
      <SomeElement>
          <!--Внутри этого блока я могу использовать <>&"", но комментарии не являются "полезной" частью XML документа.-->
  
          <![CDATA[ CDATA - character data, т.е. данные, которы не требуют экранирования.
          Я могу использовать <>&", а также это часть XML документа.]]>
      </SomeElement>
  </SomeData>
  

Мы уже могли обратить внимание, что в начале XML документа содержится пролог <?xml version="1.0" encoding="UTF-8"?>, описывающий версию xml и кодировку. Когда вы видите тег со знаками ?, это означает, что данный тег является не представлением данных, а инструкцией обработки (Processing Instruction - PI), подобные инструкции зачастую требуются принимающей XML документ стороне, например веб серверу.

Далее идет открывающий тег объекта, в котором указаны пространства имен через атрибут xmlns:namespace_name. Пространства имен нужны чтобы не допустить конфликта имён, а также использовать предопределенные элементы и атрибуты. Сами по себе пространства имен обычно являются URI, хотя могут быть и обычной строкой вроде foo. Большинство xml-парсеров знают о тех определениях, что предоставляет какой либо из стандартных (не-пользовательских) неймспейсов, поэтому никакого процесса запроса к веб серверу не происходит, под стандартным имеется ввиду, например, http://www.w3.org/2001/XMLSchema-instance, содержащий атрибуты вроде nil(для обозначения может ли значение быть нулевым) или type(для ограничения по типу) или schemaLocation для указания пути к XSD для текущего XML документа. При этом пройдя по самому URL мы получим просто информационную страницу с ссылками. И опять же, повторяясь снова, все пространства имен, атрибуты и элементы - всего лишь текстовые данные, с которыми уже оперируют парсеры лексеры и валидаторы, что возможно благодаря детерменированной структуре XML.

XML Схемы

XSD (XML Schema Definition) — это язык для описания структуры, содержимого и семантики XML-документов. XSD определяет правила и ограничения, которым должны соответствовать XML-документы, чтобы считаться допустимыми (валидными) по отношению к данной схеме и использует синтаксис XML. Основной задачей схемы является валидация XML документов. Например схема может передаваться какому-то сервису, который затем по ней будет валидировать приходящие XML, или же при ручном заполнении XML файла при наличии схемы можно избежать ошибок. Обращаю внимание, что ссылка на схему и ее наличие не является обязательной частью XML.

Хочу отметить, что данная тема довольно сложна и на ее полный разбор потребовалась бы отдельная статья. Пройдемся по

Основам XSD:

• XSD начинается с импорта xsd неймспейса(xmlns:xs в примере ниже), указания корневого тега schema из этого неймспейса, а также необходимых пользователю атрибутов

  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  

  Сделаем посложнее

  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://www.alexfitbie.com"
      xmlns:ftb="http://www.alexfitbie.com"
      elementFormDefault="unqualified">
  

  здесь, например, мы указали, что создаем свой неймспейс, который будет использован XML документом позже, затем подключили этот неймспейс в схему(xmlns:ftb), а атрибут elementFormDefault указывает на то, что целевой XML не обязан указывать неймспейс для объявления атрибутов и элементов из схемы (при qualified в XML мы должны были бы указывать наш неймспейс перед всеми атрибутами и элементами).

• Далее мы формируем структуру будущего XML используя элементы и атрибуты из неймспейса xs. Мы можем указать требуемый элемент, его имя, типы которые в него можно поместить, комплексный это объект или простой и так далее.

  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="Person"> <!--Корневой элемент-->
          <xs:complexType> <!--Комплексный тип, может содержать другие элементы, атрибуты-->
              <xs:sequence> <!--Элементы в XML будут идти в указанном порядке-->
                  <xs:element name="Name" type="xs:string"></xs:element> <!--Имя xml элемента, тип значения-->
                  <xs:element name="ID" type="xs:int"></xs:element>
                  <xs:element name = "BirthDate" type="xs:date"></xs:element>
              </xs:sequence>
              <xs:attribute name="ID" type="xs:int" use="required"/> <!--атрибуты, которые должны(здесь required) быть у элемента размещаются после sequence-->
          </xs:complexType>
      </xs:element>
  </xs:schema>
  

• Мы можем предопределить типы для повторного использования внутри нашей схемы, объявив complexType на уровне схемы (то есть под корневым <xs:schema>). Здесь мы определяем Student, который затем будет использован в массиве Students. К слову, для создания массива элементов свободного размера мы используем атрибуты minOccurs="0" maxOccurs="unbounded".
  А внутри студента мы также используем коллекцию из пользовательских типов Grade

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:element name="School"> <!--Корневой элемент будущего XML-->
        <xs:complexType>
            <xs:all> <!--All - элементы в любом порядке(в противовес sequence). Но в данном случае у нас только массив студентов-->
                <xs:element name="Students"> <!--Массив-->
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="Student" type="Student" minOccurs="0" maxOccurs="unbounded"/> <!--Здесь мы ограничиваем элементы массива по типу Student(он ниже), а также указываем что этот элемент может встречаться от 0 до неограниченного кол-ва раз, тем самым создавая коллекцию-->
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:all>
        </xs:complexType>
    </xs:element>


    <xs:complexType name="Student"> <!--Объявление типа Student, complexType под корнем схемы-->
        <xs:sequence>
            <xs:element name="Name" type="xs:string"/>
            <xs:element name="Grades">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="Grade" type="Grade" minOccurs="1" maxOccurs="30"/> <!--Массив элементов типа Grade(он ниже), с размером от 1 до 30 элементов-->
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>


    <xs:complexType name="Grade"> <!--Также объявление типа Grade-->
        <xs:sequence>
            <xs:element name="Subject" type="xs:string"/>
            <xs:element name="Value" type="xs:float"/>
        </xs:sequence>
    </xs:complexType>

</xs:schema>

Итоговый XML, составленный по нашей схеме выглядел бы так:

<School
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="School.xsd">

    <Students>

        <Student ID="11">
            <Name>Jimmy McGill</Name>
            <Grades>
                <Grade>
                    <Subject>Math</Subject>
                    <Value>5.6</Value>
                </Grade>
            </Grades>
        </Student>

        <Student ID="01">
            <Name>Pit Ritt</Name>
            <Grades>
                <Grade>
                    <Subject>History</Subject>
                    <Value>8.7</Value>
                </Grade>

                <Grade>
                    <Subject>Math</Subject>
                    <Value>7.8</Value>
                </Grade>
            </Grades>
        </Student>

    </Students>

</School>

Помимо XSD существует DTD (Document Type Definition), служащий также для определения структуры XML. Но он считается устаревшим, не использует синтаксис XML и обладает куда меньшими возможностями. Пример синтаксиса:

<!DOCTYPE note [
  <!ELEMENT note (to,from,heading,body)>
  <!ELEMENT to (#PCDATA)>
  <!ELEMENT from (#PCDATA)>
  <!ELEMENT heading (#PCDATA)>
  <!ELEMENT body (#PCDATA)>
]>

SOAP

SOAP (Simple Object Access Protocol) — это протокол обмена сообщениями, используемый для передачи данных между компьютерами. SOAP основывается на XML и определяет строгие правила обмена данными между веб-сервисами и клиентами. Протокол включает описание сообщений, как и каким образом они должны быть переданы, а также стандартные вызовы и ответы.

То есть, SOAP сообщения представляют данные, передаваемые, например, в теле HTTP запроса/ответа. По правде говоря, с SOAP я не работал, протокол можно отнести к категории устаревших и используемых в основном в гигантских легаси проектах, вроде банковских систем и прочих Госуслуг, современные сервисы чаще полагаются на обмен данными через форматы вроде JSON или YAML.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ex="http://example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ex:GetStudentDetailsRequest>
         <ex:StudentID>12345</ex:StudentID>
      </ex:GetStudentDetailsRequest>
   </soapenv:Body>
</soapenv:Envelope>

YAML

YAML (Yet Another Markup Language YAML Ain't Markup Language) — это текстовый формат("бывший" язык разметки) для сериализации данных, предназначенный для удобочитаемого представления структурированных данных. YAML используется для хранения конфигурационных файлов, передачи данных между программами и различных других задач. YAML не является форматом "из коробки" для .NET, хотя существует сторонняя библиотека YAML.NET.

Общий синтаксис YAML:

• Yaml начинается с первой строки --- и заканчивается строкой ...(опционально, например несколько yaml в одном файле).

• Простые свойства хранятся в паре key:value

  ---
  pi: 3.14
  b: false
  c: c
  o: null
  s: Some Text
  

• Для образования композитных типов и обозначения вложенности используются пробелы (не табуляция!):

  ---
  pi: 3.14
  b: false
  c: c
  ComplexStruct: # Вложенные члены X и Y
   X: 1.5
   Y: 2.7
  

• Коллекции используют или inline синтаксис Values: {a, b, c}, или синтаксис новой строки с отступом, пробелом и тире, особенно полезным для обозначения композитных элементов массива.

  Students: # Array
   - Name: Pam Beasley # Element 1
     Age: 10
     AverageGrade: 3.9
   - Name: Ryan Howard # Element 2
     Age: 11
     AverageGrade: 4.2
  

• Некоторые структуры данных могут потребовать своих алгоритмов сериализации. Например словари, также как и в JSON(в/из которого yaml легко конвертируется), также могут выглядить как композитный объект

  Teachers:
   MichaelScott: {Pam Beasley, Ryan Howard} # string key, string[] value, "" опционально
   JanGofrey: {"Alex Swanson"}

• Кроме этого, присутствует явный синтаксис пары ключ-значение (Complex Mapping Key):

TeachersComplexMappingKey:
? Name: MichaelScott # Явный ключ начинается с ?
  Age: 41        
  Subject: Math  
: # Явное значение ключа начинается с :, в данном случае значение это массив 
  - Name: Pam Beasley
    Age: 10
    AverageGrade: 3.9
  - Name: Ryan Howard
    Age: 11
    AverageGrade: 4.4

Технологии сериализации

Мы переходим к практическим заметкам. Отмечу, что практически вся информация была взята и переварена из документации Microsoft, где довольно подробно описан каждый раздел и приведены примеры кода.

System.Text.Json

На сегодняшний день самой удобной библиотекой для сериализации в/из JSON является System.Text.Json. Большая часть работы с ним заключаются в использовании статических методов JsonSerializer, конфигурации при помощи экземпляра JsonSerializerOptions, передаваемого в методы JsonSerializer, использовании атрибутов, реализации кастомных обработчиков и конвертеров объектов.

Основы System.Text.Json

Для сериализации/десериализации используется JsonSerializer.Serialize<T>(), JsonSerializer.Deserialize<T>() и их async собратья. Сериализация возможна как в/из Stream, так и в обычную строку или Utf8Json Reader/Writer. Методы обладают большим количеством перегрузок для разных нужд.
Также важнейшим (но при этом необязательным) этапом сериализации является создание экземпляра JsonSerializerOptions, передаваемого в вышеупомянутые методы для конфигурации всего процесса, поэтому каждый раз, когда вы видите упоминание JsonSerializerOptions в данном материале, я имею ввиду конструкцию вроде:

JsonSerializerOptions options = new()
{   // В 99% случаев мы конфигурируем опции через синтаксис инициализатора 
    WriteIndented = true,
    IncludeFields = true,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    // И прочие свойства JsonSerializerOptions, что я указываю после точки
};

string serialized = JsonSerializer.Serialize<MyData>(myobj, options);

Кастомизация политики имен и самих имен в выходном JSON происходит при помощи JsonSerializerOptions.PropertyNamingPolicy и атрибута [JsonPropertyName("")] перед свойством/полем.

По умолчанию JSONSerializer сериализует только все публичные свойства (если их тип поддерживает сериализацию). Это поведение можно конфигурировать, игнорируя свойства при помощи [JsonIgnore](с возможностью указания условия игнорирования) или при конфигурировании JsonSerializerOptions.DefaultIgnoreCondition (а также JsonSerializerOptions.IgnoreReadOnlyProperties). Также возможно включение в Json непубличных свойств и полей через атрибут JsonInclude / JsonSerializerOptions.IncludeFields.

Если в JSON присутствуют элементы, которые нельзя смаппить ни с одним свойством в целевом типе, мы можем создать Dictionary<string, JsonElement> и пометить его атрибутом [JsonExtensionData], куда будут писаться "потерявшиеся" JSON-свойства, для прочтения которых мы пользуемся типом из DOM модели JsonElement, его мы коснемся позже.

Поддерживаемые типы коллекций перечислены здесь. Говоря в общих чертах, для сериализации поддерживается все, что реализует IEnumerable (где оно просто перебирается и пишется в JSON). Для десериализации тип должен реализовывать один из перечисленных в статье интерфейсов, это общие интерфейсы коллекций от ICollection<> до IQueue<>, предоставляющие интерфейс для добавления элементов. Нюансы есть у Dictionary<K,V> и Stack<T>, в случае стека из-за его семантики при десериализации значения будут идти задом наперед (то есть сериализованный стек 3 2 1 0 будет десериализован в 0 1 2 3). В случае же словаря, список ключей ограничен простыми сериализуемыми типами (иначе говоря теми, которые в качестве полей/свойств сериализуются как "name":value), поскольку словарь сериализуется как JSON Object, а не Array, т.е. если мы взглянем на представление словаря в JSON:

{ // Dictionary<string, int> выглядит так
  "First": 1,
  "Second": 2,
  "Third": 3
}

то увидим, что string ключ пишется как имя Json свойства, а int значение - соответственно, как значение.

А для сериализации ключей более сложного типа, может потребоваться реализовать свой JsonConverter, на который мы взглянем позже.

Иммутабельные типы и заполнение

С десериализацией в изменяемые типы с публичными get set свойстами все просто, если очень грубо упростить - JSON находит член объекта, имя которого соответствует имени JSON-свойства, и пишет в него данные (на самом деле при первом обращении генерируются метаданные в режиме рефлексии, но это сейчас не важно).
Однако возможна и десериализация в иммутабельные типы, вернее сказать в их get-only/readonly данные, путем использования параметризованного конструктора. Если конструктор не один, или присутствует конструктор без параметров, конструктор для десериализации должен быть помечен [JsonConstructor]. Все имена параметров конструктора должны соответствовать именам сериализуемых полей/свойств, без учета регистра. Например, имя в конструкторе должно быть simpleNumber, а имя поля/свойства в объекте должно быть SimpleNumber/SIMPLENUMBER/simpleNumber, при этом [JsonPropertyName] ни на что в этой реализации не влияет. Также учтите, что тип передаваемых в конструктор аргументов должен совпадать с типом соответствующих свойств объекта.

public class ReadonlyData
{
  [JsonInclude]
  public readonly int ID;
  public string Name { get; }
  public DateOnly BirthDate { get; init; }
  public IReadOnlyCollection<int> Numbers { get; } // IReadOnlyCollection чтобы одурачить вас. Это не относится к теме.

  [JsonConstructor]
  public ReadonlyData(int id, string name, DateOnly birthDate, IReadOnlyCollection<int> numbers)
  {
    ID = id;
    Name = name;
    BirthDate = birthDate;
    Numbers = numbers;
  }
}

Помимо десериализации в иммутабельные типы, JsonSerializer также может заполнять инициализированные значения. В обычной ситуации сериализатор для каждого json-свойства создает новый объект, затем присваивая ссылку на него c#-свойству. Однако, если какое либо c#-свойство/поле уже инициализированно, например

[JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)] // На уровне класса
class A
{
  [JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)] // или тут
  public List<int> Numbers { get; } = [1, 2, 3];
}

то, для того, чтобы "заполнить" данный лист, а не пересоздавать его, мы можем использовать атрибут JsonObjectCreationHandling(JsonObjectCreationHandling.Populate). Сериализатор через get возьмет ссылку на лист, и заполнит его десериализуемыми значениями через Add(). К слову, данный атрибут помогает при работе с иммутабельными get-only/readonly свойствами ссылочного типа, однако для value-типов(struct) обязательно должен быть указан set (поскольку вместо ссылки на объект в хипе сериализатор получит копию структуры через get, заполнит ее и должен будет записать обратно через set).

Обработка ссылок. $id и $ref

Сериализуемые объекты могут оказаться сложными по своей структуре и указывать друг на друга. Более того, один и тот же объект может встречаться несколько раз в сериализуемых данных. Например, предположим у нас есть класс сотрудника, имеющего свойство, указывающего на его начальника:

public class Employee
{
    public string Name { get; set; }
    public Employee? Boss { get; set; }
}

и предположим у нас есть класс Corporate, содежащий ссылку на директора и полный лист сотрудников (куда директор также входит). При создании компании мы создаем граф сотрудников, где у CEO Boss = null, а у двух менеджеров Boss = CEO и так далее.

public class Corporate
{
  public Employee CEO { get; set; }

  public List<Employee> Employees { get; set; } // Сюда мы пишем сотрудников, указывающих на свое начальство, и само начальство
  }

Если у нас будет 1 директор и 2 сотрудника, указывающих на директора, то при обычной десериализации мы получим 4 объекта директора: 1 в свойство Company.CEO, 1 в листе Company.Employees и еще по одному у каждого сотрудника в свойстве Employee.Boss:

{
  "CEO": { // CEO 1
    "Name": "Jim Root",
    "Boss": null
  },
  "Employees": 
  [
    {
      "Name": "Jim Root", // CEO 2. Директор также находится в листе сотрудников.
      "Boss": null
    },
    {
      "Name": "Jason Tward",
      "Boss": {
        "Name": "Jim Root", // CEO 3
        "Boss": null
      }
    },
    {
      "Name": "Alex Stein",
      "Boss": {
        "Name": "Jim Root", // CEO 4. Итого, десериализуя, мы получим 4! одинаковых объекта
        "Boss": null
      }
    }
  ]
}

Однако, мы можем передать в конфигурацию JsonSerializerOptions определенный в .NET обработчик ссылок ReferenceHandler.Preserve:

JsonSerializerOptions options = new()
{
    // Preserve НЕ работает с readonly полями и свойствами и НЕ работает с иммутабельными типами.
    ReferenceHandler = ReferenceHandler.Preserve,
};

После этого каждому объекту в выходном JSON будет добавлено мета-свойство $id, являющееся целым числом. Это будет что-то вроде ключа для каждой записи в Json, в свою очередь объекты (в нашем случае сотрудники), ссылающиеся на директора, вместо полной(повторной) сериализации директора разместят в "Boss" мета-свойство $ref с ключом $id:

{
  "CEO": {
    "$id": "1", // ключ для указания на нашего директора
    "Name": "Jim Root",
    "Boss": null
  },
  "Employees": 
  {
    "$id": "2", // У каждой сериализуемой записи будет $id, в том числе у листа. Но эти ключи нас не интересуют.
    "$values": 
    [
      {
        "$ref": "1" // Ссылка на CEO, поскольку он также в листе сотрудников
      },
      {
        "$id": "3",
        "Name": "Jason Tward",
        "Boss": {
          "$ref": "1" // Ссылка на CEO
        }
      },
      {
        "$id": "4",
        "Name": "Alex Stein",
        "Boss": {
          "$ref": "1" // Еще одна
        }
      }
    ]
  }
}

Работает это довольно простым образом, внутри JsonReferenceHandler находится ссылка на класс-стратегию JsonReferenceResolver. Внутри же него находится словарь, сериализатор читает JSON директора, находит мета-свойство $id, десериализует объект, помещает в упомянутый словарь директора под ключом, равным его $id, и затем, натыкаясь на $ref в сотрудниках, он уже получает ИЗ словаря объект директора по указанному в $ref ключу и присваивает ссылку на этот объект в десериализуемое поле сотрудника Boss.

К слову, именно из-за порядка чтения, крайне важно чтобы объекты НА которые ссылалаются шли раньше чем объекты которые ссылаются, однако мы можем применить атрибут [JsonPropertyOrder] для детерменирования порядка. Совет: при отстуствии сторонних конфигураций, поля, включенные в сериализацию через, например, [JsonInclude], всегда идут позже свойств.

Полиморфизм

Полиморфизм - одна из проблем сериализации. Если имеется ссылка базового типа, указывающая на самом деле на объект дочернего, то десериализовать исходное состояние объекта без дополнительных инструментов будет невозможно, поскольку мы знаем лишь о базовом типе, какой тип объекта был фактически сериализован, остается неизвестным. Для таких ситуаций существует атрибут [JsonDerivedType(typeof(DerivedTypeName))]. Он указывается перед базовым классом, в его аргументах мы перечисляем дочерние типы. То есть, мы как бы говорим сериализатору "Если ты десериализуешь объект в ссылку этого типа, то, возможно, ты работаешь с объектом одного из перечисленных в его атрибуте дочерних типов". Атрибут может быть использован несколько раз, если унаследованных типов, которые требуют полиморфической десериализации, несколько.

На всякий случай я уточню, при сериализации сериализатор опирается на объект в памяти. Любой ваш объект, сериализуемый через ссылку типа object, будет сериализован как ваш объект, поскольку сериализатор внутри опирается на рефлексию.С десериализацией все интереснее, поскольку ему этот самый объект нужно создать, а значит опираться можно только на аргумент типа JsonSerializer.Deserialize<T>(). Для поддержки полиморфизма в JSON-представление сериализуемого объекта добавляется мета-свойство $type. Оно содержит дискриминатор(ключ) типа, экземпляр которого нужно создать. К слову атрибут [JsonDerivedType(typeof(DerivedTypeName), typeDiscriminator)] принимает аргумент typeDiscriminator, в который мы можем передать int или string, для ручной конфигурации, иначе будет использован счетчик int 0..n для каждого дочернего типа в атрибутах.

[JsonDerivedType(typeof(Developer), "developer")] // "developer" - наш дискриминатор
[JsonPolymorphic(UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)] // Об этом позже
public class Employee
{
  // ...
}

Таким образом, выходной JSON получит новую запись:

{
  "$type": "developer",
  // Другие данные
}

Сопоставив значение из мета-свойства $type и один из дискриминаторов в атрибуте JsonDerivedType - сериализатор создаст экземпляр указанного типа и десериализует данные в него.

К слову, при полиморфической десериализации и сериализации в качестве аргумента типа JsonSerializer.Serialize<T>()/JsonSerializer.Deserialize<T> мы должны указывать базовый тип, то есть тип, помеченный атрибутами [JsonDerivedType].

Также выше в примере C# кода был упомянут атрибут [JsonPolymorphic]. Он служит для дополнительной конфигурации полиморфической десериализации, например в примере используется [JsonPolymorphic(UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)], говорящий о том, что если будет обнаружен неизвестный тип, не указанный в [JsonDerivedType], то JSON десериализует объект в экземпляр ближайшего известного(указанного) предка.

JSON Document Object Model

JSON DOM (Document Object Model) — это модель представления структуры JSON-документа в памяти в виде объекта или дерева объектов, с которыми можно работать программно. Мы можем десериализовать любой объект в такую структуру, с которой можно работать не имея конкретного типа.

Основными типами для работы с DOM являются JsonNode и JsonDocument. Первый допускает работу с данными и их изменение, второй - иммутабелен. JsonNode основывается на синтаксисе индексатора

{ // Исходник
  "ID": 1,
  "Name": "Jim Carry",
  "Sales":
  [
    1,2,3,4,5
  ]
}

JsonNode node = JsonNode.Parse(stream)!;
JsonNode idJsonValue = node["ID"]!;
int ID = idJsonValue.Deserialize<int>();
Console.WriteLine(ID);

и представляет данные в виде 3 сущностей: JsonValue, т.е. примитивное ключ-значение свойство вроде "id":1, JsonObject, являющийся композитным объектом (заключен в фигурные скобки), и JsonArray, представляющий массивы. Все три типа наследуются от JsonNode, что позволяет также использовать его интерферфейс и в частности индексатор и идти по дереву объектов вглубь.

JsonDocument - иммутабельная реализация для работы с DOM. Также по сути является графом объектов из спарсенного Json и позволяет обращаться к вложенным свойствам, перебирать их и так далее. Работа с JsonDocument происходит через тип JsonElement и начинается с обращения к JsonDocument.RootElement:

{ // Исходник
  "ID": 1,
  "Name": "Jim Carry",
  "Sales":
  [
    1,2,3,4,5
  ]
}

using JsonDocument document = JsonDocument.Parse(stream); // IDisposable, поэтому using
JsonElement root = document.RootElement; // Корневой элемент
foreach (var obj in root.EnumerateObject()) // Перебираем все записи в корневом объекте
{
    Console.WriteLine(obj);
}

JsonElement sales = root.GetProperty("Sales"); // Получаем массив в корне, перебираем элементы массива.
foreach (JsonElement sale in sales.EnumerateArray())
{
    Console.Write(sale.GetInt32() + ", ");
}

UTF8 Json Writer/Reader

Utf8JsonWriter / Utf8JsonReader - типы, обеспечивающие запись/чтение JSON на самом низком уровне. Вся сериализация и десериализация сводится к использованию их. Вкратце примеры их работы:

Utf8JsonWriter предоставляет API для записи шаг-за-шагом объектов, свойств, массивов, довольно прост в использовании, издалека похож на обычный StreamWriter. Если вы возьмете лист бумаги, ручку, сядете десериализовывать объект вручную и будете проговаривать каждое ваше действие - вы превратитесь в Utf8JsonWriter:

using MemoryStream ms = new(); // Создадим стрим, куда будем писать
using Utf8JsonWriter writer = new(ms, options); // Writer тоже IDisposable

writer.WriteStartObject(); // Начинаем писать сам сериализуемый объект
writer.WriteStartObject("Employee"); // Начинаем писать Json-объект. Employee здесь имя свойства в выходном Json, т.е. "Employee":{value}

// Совет: кодируем UTF-16 .NET строку в UTF-8 через JsonEncodedText для производительности своими руками.
JsonEncodedText name = JsonEncodedText.Encode("Jim Carry");
writer.WriteString("Name", name); // На Json выходе получаем: "Name": "Jim Carry"

writer.WriteNull("Null"); // "Null": null
writer.WriteNumber("ID", 10); // "ID": 10

writer.WriteStartArray("Values"); // Начинаем писать массив внутри Json объекта
writer.WriteNumberValue(10);
writer.WriteNumberValue(20);
writer.WriteEndArray(); // Закрываем массив

writer.WriteEndObject(); // Закрываем Json объект Employee
writer.WriteEndObject(); // Закрываем сам сериализуемый объект
writer.Flush(); // Записываем оставшееся в буфере JsonWriter'a в целевой поток ms

Utf8JsonReader - куда более оптимизирован, является ref struct, читает Json payload(содержимое) по токенам. Токеном может быть начало объекта, имя свойства, значение свойства, конец объекта, начало массива и т.д.

JsonReaderOptions options = new() // Опции reader'a для обработки комментариев и "лишних" замыкающих запятых
{
    CommentHandling = JsonCommentHandling.Skip,
    AllowTrailingCommas = true
};

ReadOnlySpan<byte> jsonBytes = Encoding.UTF8.GetBytes(json); // Быстренько (и неоптимизированно) получим байты
Utf8JsonReader reader = new(jsonBytes, options);

while (reader.Read()) // Пока буфер не кончился
{
    switch (reader.TokenType) // Reader читает все байты одного токена, после чего мы проверяем что это за токен
    {
        case JsonTokenType.StartArray: // Если это начало массива, следующий токен будет элементом массива
        
        while (reader.Read() && reader.TokenType != JsonTokenType.EndArray) // Пока не дошли до конца массива
        {
            Console.Write(reader.GetInt32() + ", "); // Читаем данные элемента массива и пишем их в консоль
        }
    }
}

Реализация JsonConverter

Если тип по каким то причинам требует кастомных правил сериализации, то решением может быть реализация своего JsonConverter<T>, передаваемого в коллекцию JsonSerializerOptions.Converters. Конвертеры делятся на 2 типа: Basic (JsonConverter<T>) и Factory (JsonConverterFactory, создающий экземпляры basic JsonConverter<T>).

С обычным все просто, он проверяет, может ли обработать переданный тип (сериализатор передает конвертерам все сериализуемые свойства начиная с корневого объекта, где каждый проверяет через CanConvert(Type typeToConvert), может ли он конвертировать объекты данного типа). Если он может конвертировать данный тип, вызывается переопределенные вами void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options);
или T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options);. Как мы можем видеть, конвертеру передаются Utf8Json Writer/Reader, через которые вы пишете/читаете объекты, как оговаривалось ранее.

public class Employee // Тип для сериализации
{
    public string Name { get; set; }
    public int ID { get; }
    public readonly DateTime dateOfBirth;

    public Employee(string name, int iD, DateTime dateOfBirth)
    {
        Name = name;
        ID = iD;
        this.dateOfBirth = dateOfBirth;
    }
}

public class EmployeeJsonConverter : JsonConverter<Employee>
{
  public override void Write(Utf8JsonWriter writer, Employee value, JsonSerializerOptions options)
  {
    // Алгоритм записи супер примитивный, давайте просто запишем все свойства и поля объекта через дефис
    string data = $"{value.Name} - {value.ID} - {value.dateOfBirth.ToString(CultureInfo.InvariantCulture)}";
    writer.WriteStringValue(data);
  }

  public override Employee? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
  {
    // Создаем переменные для будущей передачи в конструктор
    string Name = string.Empty;
    int ID = 0;
    DateTime dateOfBirth = DateTime.MinValue;

    // В нашем алгоритме записи мы просто пишем 3 поля объекта через дефис. Поэтому читаем 1 строку.
    string? data = reader.GetString();
    if (data != null)
    {
      // Делим данные в JSON
      var splitted = data.Split('-', StringSplitOptions.TrimEntries); 
      
      // И парсим их
      Name = splitted[0];
      ID = int.Parse(splitted[1]);
      dateOfBirth = DateTime.Parse(splitted[2], CultureInfo.InvariantCulture);
    }

    return new Employee(Name, ID, dateOfBirth);
  }
}

С фабричными конвертерами сложнее. Основная их цель - создавать basic converter'ы, упомянутые ранее, а значит фабричные конвертеры мы используем тогда, когда конвертации требует какой-то неопределенный тип, который мы не можем реализовать вручную. Самый распространенный случай - незакрытые generic типы. Например у нас есть некоторый класс DictionaryKey, который используется в качестве ключа в словаре. Поскольку это композитный тип с полями и свойствами, использовать его "из коробки" в качестве ключа не выйдет. А значит нам нужно создать конвертер для Dictionary<DictionaryKey,>, второй generic аргумент после запятой не указан, что означает открытый generic тип, благодаря чему нам не придется писать отдельный basic конвертер для каждого типа значения, что мы планируем использовать в словаре.

Убедившись, что fabrick converter имеет дело с нужным типом, он создает экземпляр уже basic converter(также написанного нами), обычно используя System.Reflection.Activator(что является обычной техникой создания экземпляров в рантайме). Итого, для работы с фабричным конвертерам нам также потребуется определить обычный конвертер, который знает как читать/писать наш DictionaryKey.

public override bool CanConvert(Type typeToConvert)
{
    return typeToConvert.IsGenericType && // Если тип generic
    typeToConvert.GetGenericTypeDefinition() == typeof(Dictionary<,>) &&  // И словарь
    typeToConvert.GetGenericArguments()[0] == typeof(DictionaryKey); // И первый (известный) аргумент это DictionaryKey, значит я могу создать для вас экземпляр обычного конвертера.
}

public override JsonConverter? CreateConverter(Type typeToConvert, JsonSerializerOptions options)
{
    var genArgs = typeToConvert.GetGenericArguments(); // Получаем все gen аргументы словаря
    Type valueType = genArgs[1]; // Второй аргумент, в данном случае тип значения в словаре, о котором мы ничего не знаем

    // Создаем экземпляр заранее определенного Basic конвертера, в данном случае JsonConverter<TValue>, типизируя его вторым generic аргументом, то есть valueType. Почему типизируем его вторым аргументом - потому что об аргументе значения словаря, т.е. DictionaryKey, он и так знает, в этом есть цель его существования. Описанный конвертер вы можете найти ниже.

    return 
        (JsonConverter)Activator.CreateInstance(typeof(DictionaryKeyJsonConverter<>).MakeGenericType(valueType), // Типизируем конвертер типом значения словаря
        BindingFlags.Instance | BindingFlags.Public,
        binder: null,
        args: [options], // Конструктор конвертера ожидает JsonSerializerOptions
        culture: null)!;
}

public class DictionaryKey
{
  // Поля вместо свойств просто потому что. Не играет роли.
  [JsonInclude]
  private int first;
  [JsonInclude]
  private float second;
  [JsonInclude]
  private string name;


  [JsonConstructor]
  public DictionaryKey(int first, float second, string name)
  {
      this.first = first;
      this.second = second;
      this.name = name;
  }


  public override string ToString()
  {
      return $"{first}-{second}-{name}";
  }
}

public class DictionaryKeyJsonConverter<TValue> : JsonConverter<Dictionary<DictionaryKey, TValue>>
{
    private JsonConverter<TValue> valueConverter; // Конвертер для TValue, тип значения нашего словаря.

    
    public DictionaryKeyJsonConverter(JsonSerializerOptions options)
    {
        valueConverter = (JsonConverter<TValue>)options.GetConverter(typeof(TValue)); // Который мы получаем из конфигурации сериализатора. Если в конфигурацию не был передан конвертер для данного типа, используется конвертация по умолчанию, с которой мы имели дело все это время.
    }


    public override void Write(Utf8JsonWriter writer, Dictionary<DictionaryKey, TValue> dict, JsonSerializerOptions options)
    {
        writer.WriteStartObject(); // Начинаем писать объект, который на самом деле является словарем.

        foreach ((DictionaryKey key, TValue value) in dict)
        {
            string propertyName = key.ToString()!; // Наш ключ для наблюдателя будет выглядеть как имя json-свойства. То есть "key": value, где key это DictionaryKey, умело уместивший свои данные в строку через ToString(), для простоты примера.

            // Соблюдая политику наименования, которая возможно была передана в JsonSerializerOptions, записываем наш DictionaryKey как имя свойства.
            writer.WritePropertyName(options.PropertyNamingPolicy?.ConvertName(propertyName) ?? propertyName);

            valueConverter.Write(writer, value, options); // А значение записываем через конвертер нашего TValue типа, полученный в конструкторе.
        }    

        writer.WriteEndObject(); // Словарь записан как объект.
    }


    public override Dictionary<DictionaryKey, TValue>? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // Наш словарь - JSON объект, а значит начинается с этого токена.
        if (reader.TokenType != JsonTokenType.StartObject)
        {
            throw new JsonException();
        }

        Dictionary<DictionaryKey, TValue> result = new();
        
        while(reader.Read())
        {
            if (reader.TokenType == JsonTokenType.EndObject) // Закончили читать словарь
            {
                return result;
            }

            // Запись в словаре всегда начинается с PropertyName, в которое мы умело запихали DictionaryKey 
            if (reader.TokenType != JsonTokenType.PropertyName)
            {
                throw new JsonException();
            }

            string propertyName = reader.GetString()!; // Читаем имя свойства
            // И, предположим, мы ToString() реализовали путем склеивания всех свойств и полей DictionaryKey через дефисы. Расклеиваем обратно.
            string[] data = propertyName.Split('-', StringSplitOptions.RemoveEmptyEntries);

            // Предположим DictionaryKey состоит из 3 свойств int,float,string.
            DictionaryKey key = new(int.Parse(data[0]), float.Parse(data[1]), data[2]);

            // Reader читает токенами, а значит вызывав Read мы переместим его указатель с токена имени свойства(DictionaryKey здесь) на его значение, которое также является TValue для нашей пары <DictionaryKey, TValue>
            reader.Read();

            // Делегируем чтение конвертеру TValue
            TValue value = valueConverter.Read(ref reader, typeof(TValue), options)!;

            result.Add(key, value); // Добавляем пару в словарь
        }


        throw new JsonException(); // Вас здесь не должно быть, вы пропустили JsonTokenType.EndObject, делающий return.
    }

}

Контракты

Для каждого сериализуемого типа .NET необходимо то, что называется контрактом. Контракт определяет стоит ли включать поля, как записывать имена свойств в JSON, какие свойства игнорировать, какой конвертер использовать для какого свойства и т.д.. Обычно мы кастомизируем контракты используя JSON атрибуты, передавая сериализатору экземпляр JsonSerializerOptions, создавая свои конвертеры и т.д.. Однако, существует также опция кастомизации контрактов на более высоком уровне.
Для кастомизации конракта мы можем обратиться к JsonSerializerOptions.TypeInfoResolver и инициализировать либо своей реализацией, либо экземпляром предопределенного типа DefaultJsonTypeInfoResolver. В чем удобство второго подхода - нам не нужно наследоваться и реализовывать сложную логику, как это было с конвертерами, поскольку работа с JsonTypeInfoResolver заключается в передаче делегатов в коллекцию Modifiers.
Эта коллекция принимает любого делегата с сигнатурой Action<JsonTypeInfo>, то есть мы можем передавать туда методы (хуки в своей сути, перехватывающие процесс сериализации), которые ничего не возвращают и принимают объект JsonTypeInfo. Под этим объектом скрывается каждая сущность, которую сериализатор планирует включать в JSON, от корневого объекта до вложенных.
Если вкратце, JsonTypeInfo немного похож на MemberInfo из рефлексии, через него мы можем получить список его собственных свойств и полей, через него мы можем определить, будет ли сериализовываться тип как Json-объект/простое свойство/массив, обратиться к его C# типу, получить доступ к конвертерам, если такие определены, и так далее.

Простые примеры кастомизации контрактов:

public static void IgnorePasswords(JsonTypeInfo typeInfo)
{
    for (int i = 0; i < typeInfo.Properties.Count; i++) // Перебираем все свойства объекта
    {
        if (typeInfo.Properties[i].PropertyType == typeof(Password)) // Если любое свойство является паролем ( какой-то наш класс)
        {
            typeInfo.Properties.RemoveAt(i); // То удаляем его из списка свойств. То есть объекты типа Password не будут включены в выходной JSON.
        }
    }
}

Или, например, мы можем использовать рефлексию внутри модификатора контракта, чтобы включить все поля в сериализацию(но, конечно, переданный сериализатору JsonSerializerOptions.IncludeFields был бы куда эффективнее)

public static void IncludeFieldsModifier(JsonTypeInfo typeInfo)
{
    if (typeInfo.Kind is not JsonTypeInfoKind.Object) // Если это не композитный JSON-объект, игнорируем его, массивы и примитивные пары "key":value не обладают полями
    {
        return;
    }

    // Вытаскиваем все поля, обращаясь к уже .NET типу сериализуемого typeInfo через свойство Type
    foreach (var fieldInfo in typeInfo.Type.GetFields(System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.NonPublic))
    {
        // Создаем новый JsonPropertyInfo. Это информация о JSON-свойстве, используя которую сериализатор запишет "key":value пару. 
        JsonPropertyInfo jsonPropertyInfo = typeInfo.CreateJsonPropertyInfo(fieldInfo.FieldType, fieldInfo.Name);

        // Нам нужно указать на логику чтения и записи значения новоиспеченного JSON-свойства, в данном случае мы передаем методы рефлексии для чтения/записи FieldInfo, поскольку по сигнатуре они подходят под делегаты Get/Set
        jsonPropertyInfo.Get = fieldInfo.GetValue; // Передаем в делегат Get метод для получения значения
        jsonPropertyInfo.Set = fieldInfo.SetValue; // Передаем в делегат Set метод для установки значения

        typeInfo.Properties.Add(jsonPropertyInfo); // Добавляем JSON-свойство к JSON-свойствам нашего Json-объекта
    }
}

После создания наших контрактов, мы передаем их в конфигурацию:

JsonSerializerOptions options = new()
{
    TypeInfoResolver = new DefaultJsonTypeInfoResolver()
    {
        Modifiers = { IncludeFieldsModifier } // Передаем наш метод в лист делегатов, которые будут вызываться.
    }
};

Режимы сериализации

Обычно JsonSerializer работает в режиме Reflection. При первой сериализации типа создаются метаданные (контракты), описывающие как этот тип должен сериализовываться, какие свойства и поля, их атрибуты и тд.. Этот подход удовлетворяет большинство потребностей, однако в некоторых случаях, когда особенно важна оптимизация, мы можем захотеть избежать сбора метаданных в рантайме.

Поэтому у сериализатора есть второй режим работы: SourceGeneration.
Он также делится на 2 подрежима: Matadata-based и Serialization Optimization.

• Metadata-based позволяет сгенерировать файлы исходного кода, содержащие метаданные, описывающие сериализуемые типы, которые затем будут интегрированы и скомпилированы вместе с вашим кодом.

• Serialization-optimization - довольно свежий режим, позволяет заменить использование JsonSerializer на Utf8JsonWriter/Reader, что очень повышает производительность кода.

Однако у этих режимов есть недостатки: большинство фич сериализатора перестают работать, например разрешение ссылок, десериализации иммутабельных типов, атрибутов для заполнения инициализированных объектов и пр..

В остальном, данная тема невероятно огромная и погоня за оптимизацией зачастую не стоит свеч, поэтому я просто оставлю ссылку на документацию.

Заключение

Надеюсь, данная статья останется в ваших закладках и принесет пользу. Пиши конспекты, пей чай, пеки булки.