Newtonsoft.Json для C# (.NET): полное руководство с примерами

Что такое Newtonsoft.Json и зачем он нужен?

Newtonsoft.Json (часто называемый просто Json.NET) — это самая популярная и мощная библиотека для работы с форматом JSON в экосистеме .NET. Она предоставляет разработчикам на C# высокопроизводительные и гибкие инструменты для сериализации (преобразования объектов C# в JSON-строку) и десериализации (преобразования JSON-строки обратно в объекты C#).

Зачем она нужна? JSON (JavaScript Object Notation) стал стандартом де-факто для обмена данными между веб-серверами и клиентами, в конфигурационных файлах, в API и базах данных (например, NoSQL). Newtonsoft.Json позволяет:

• Легко интегрироваться с любыми REST API — отправлять и получать данные в формате JSON.
• Работать с конфигурациями — читать и записывать JSON-файлы настроек.
• Управлять сложными структурами — поддерживает вложенные объекты, массивы, словари и динамические типы.
• Настраивать процесс сериализации — с помощью атрибутов и настроек (контракты, игнорирование свойств, форматирование дат и т.д.).

Установка Newtonsoft.Json

В отличие от Python (где используется pip install) или Node.js (npm install), в экосистеме .NET используется менеджер пакетов NuGet. Установить библиотеку можно несколькими способами:

Способ 1: Через консоль диспетчера пакетов (Visual Studio)

Откройте Сервис → Диспетчер пакетов NuGet → Консоль диспетчера пакетов и выполните команду:

Install-Package Newtonsoft.Json

Способ 2: Через .NET CLI (кросс-платформенный)

Если вы используете .NET Core / .NET 5+ и работаете из терминала, выполните:

dotnet add package Newtonsoft.Json

Способ 3: Через интерфейс Visual Studio

Кликните правой кнопкой мыши по проекту → «Управление пакетами NuGet» → на вкладке «Обзор» найдите Newtonsoft.Json и нажмите «Установить».

После установки добавьте в начало файла с кодом директиву using Newtonsoft.Json;.

Быстрый старт: пример кода

Давайте сразу посмотрим, как работает библиотека, на простом примере. Предположим, у нас есть класс Person:

using System;
using Newtonsoft.Json;

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

class Program
{
    static void Main()
    {
        // 1. Создаем объект
        var person = new Person
        {
            Name = "Анна",
            Age = 30,
            Email = "anna@example.com"
        };

        // 2. Сериализация: объект -> JSON
        string json = JsonConvert.SerializeObject(person, Formatting.Indented);
        Console.WriteLine("Сериализованный JSON:");
        Console.WriteLine(json);

        // 3. Десериализация: JSON -> объект
        string jsonInput = @"{'Name':'Иван','Age':25,'Email':'ivan@example.com'}";
        Person deserializedPerson = JsonConvert.DeserializeObject<Person>(jsonInput);
        Console.WriteLine($"\nДесериализованный объект: {deserializedPerson.Name}, {deserializedPerson.Age}");
    }
}

Вывод:

Сериализованный JSON:
{
  "Name": "Анна",
  "Age": 30,
  "Email": "anna@example.com"
}

Десериализованный объект: Иван, 25

Основные методы и функции Newtonsoft.Json

Ниже приведены 10 ключевых методов/функций библиотеки с подробным описанием и примерами.

1. JsonConvert.SerializeObject()

Что делает: Преобразует объект .NET в строку JSON.

Параметры:

• value (object) — объект для сериализации.
• formatting (Nullable<Formatting>) — форматирование вывода (None — в одну строку, Indented — с отступами).
• settings (JsonSerializerSettings) — дополнительные настройки (игнорирование null, обработка циклических ссылок и т.д.).

Пример:

var data = new { Name = "Тест", Value = 42 };
string json = JsonConvert.SerializeObject(data, Formatting.Indented);
Console.WriteLine(json);
// Вывод:
// {
//   "Name": "Тест",
//   "Value": 42
// }

2. JsonConvert.DeserializeObject<T>()

Что делает: Преобразует строку JSON в объект указанного типа T.

Параметры:

• value (string) — JSON-строка.
• settings (JsonSerializerSettings) — настройки десериализации.

Пример:

string json = "{'Name':'Мария','Age':28}";
var person = JsonConvert.DeserializeObject<Person>(json);
Console.WriteLine(person.Name); // Мария

3. JObject.Parse()

Что делает: Разбирает строку JSON в динамический объект JObject (из LINQ to JSON). Позволяет обращаться к полям без создания классов.

Параметры:

• json (string) — JSON-строка.

Пример:

string json = "{'product':'Laptop','price':1200}";
JObject obj = JObject.Parse(json);
string product = (string)obj["product"];
int price = (int)obj["price"];
Console.WriteLine($"{product}: ${price}"); // Laptop: $1200

4. JArray.Parse()

Что делает: Разбирает строку JSON, содержащую массив, в объект JArray.

Параметры:

• json (string) — JSON-строка с массивом.

Пример:

string jsonArray = "[1, 2, 3, 4, 5]";
JArray array = JArray.Parse(jsonArray);
foreach (var item in array)
{
    Console.WriteLine((int)item);
}
// Вывод: 1 2 3 4 5

5. JsonConvert.DeserializeObject<dynamic>()

Что делает: Десериализует JSON в динамический объект (без строгой типизации). Удобно для работы с неизвестной структурой.

Параметры:

• value (string) — JSON-строка.

Пример:

string json = "{'name':'Динамик','value':99.9}";
dynamic dyn = JsonConvert.DeserializeObject(json);
Console.WriteLine(dyn.name);  // Динамик
Console.WriteLine(dyn.value); // 99.9

6. JsonConvert.SerializeXmlNode()

Что делает: Преобразует XML-узел (XmlNode) в JSON-строку. Полезно для конвертации между форматами.

Параметры:

• node (XmlNode) — XML-узел.
• formatting (Formatting) — форматирование.
• omitRootObject (bool) — опускать ли корневой объект.

Пример:

XmlDocument doc = new XmlDocument();
doc.LoadXml("<root><item id='1'>Значение</item></root>");
string json = JsonConvert.SerializeXmlNode(doc);
Console.WriteLine(json);
// Вывод: {"root":{"item":{"@id":"1","#text":"Значение"}}}

7. JsonConvert.DeserializeXmlNode()

Что делает: Преобразует JSON-строку обратно в XML-документ.

Параметры:

• value (string) — JSON-строка.
• deserializeRootElementName (string) — имя корневого элемента.
• writeArrayAttribute (bool) — добавлять ли атрибут массива.

Пример:

string json = "{'root':{'item':'data'}}";
XmlDocument doc = JsonConvert.DeserializeXmlNode(json);
Console.WriteLine(doc.OuterXml);
// Вывод: <root><item>data</item></root>

8. JsonSerializerSettings (класс настроек)

Что делает: Позволяет тонко настроить процесс сериализации/десериализации: игнорировать null, управлять форматированием дат, обрабатывать циклические ссылки и т.д.

Основные свойства:

• NullValueHandling — игнорировать ли null-поля.
• DateFormatString — формат даты.
• ReferenceLoopHandling — обработка циклических ссылок.
• ContractResolver — кастомный резольвер контрактов.

Пример:

var settings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
    Formatting = Formatting.Indented
};

var obj = new { Name = "Тест", Value = (object)null };
string json = JsonConvert.SerializeObject(obj, settings);
Console.WriteLine(json);
// Вывод: {"Name":"Тест"} — поле Value пропущено

9. JsonPropertyAttribute (атрибут)

Что делает: Позволяет изменить имя свойства при сериализации/десериализации, задать порядок или указать значение по умолчанию.

Параметры:

• PropertyName — новое имя в JSON.
• Order — порядок следования.
• NullValueHandling — обработка null для конкретного поля.

Пример:

public class User
{
    [JsonProperty("user_name")]
    public string Name { get; set; }

    [JsonProperty("user_age")]
    public int Age { get; set; }
}

// Сериализация выдаст: {"user_name":"Анна","user_age":30}

10. JsonIgnoreAttribute (атрибут)

Что делает: Указывает, что свойство должно быть проигнорировано при сериализации/десериализации.

Пример:

public class Account
{
    public string Username { get; set; }
    [JsonIgnore]
    public string Password { get; set; } // Не попадет в JSON
}

var acc = new Account { Username = "user1", Password = "secret" };
string json = JsonConvert.SerializeObject(acc);
Console.WriteLine(json); // {"Username":"user1"}

Реальный практический пример использования

Представьте, что мы пишем консольное приложение, которое получает данные о погоде от внешнего API (например, OpenWeatherMap) в формате JSON и выводит текущую температуру. Мы не хотим создавать полный класс для ответа, поэтому используем JObject.

using System;
using System.Net.Http;
using Newtonsoft.Json.Linq;

class WeatherApp
{
    static async System.Threading.Tasks.Task Main()
    {
        string apiKey = "ВАШ_API_КЛЮЧ";
        string city = "Moscow";
        string url = $"https://api.open