JSON в C#

Похожие

Введение в JSON в C#: Преобразование данных JSON в компилируемые классы C# POCO

Варианты использования

• ASP.NET Core Web API: преобразование примера JSON в документации OpenAPI/Swagger в классы DTO, в сочетании с привязкой модели [FromBody] для получения запросов от frontend
• ASP.NET Core MVC: преобразование тела запроса формы/JSON в Model строгого типа, в сочетании с автоматической проверкой ModelState
• Десериализация Newtonsoft.Json: преобразование JSON ответа стороннего интерфейса в классы POCO с [JsonProperty], не требуется ручное сопоставление полей
• Высокопроизводительные сценарии System.Text.Json: преобразование JSON в тип record или init-only свойства, в сочетании с JsonSerializer.Deserialize<T> для повышения скорости запуска
• Скрипты игр Unity: преобразование JSON, возвращаемого сетевым API (данные игрока, конфигурация уровня, товары магазина, рейтинг), в сериализуемые модели данных ScriptableObject
• Кроссплатформенные приложения .NET MAUI: преобразование JSON от бэкенд API в классы Model, использование в привязке данных XAML, совместное использование бизнес-модели на iOS/Android/Windows
• Blazor Server / WebAssembly: преобразование JSON от API в параметры компонентов/серверные модели строгого типа, в сочетании с @inject HttpClient для потребления общих типов frontend/backend
• Entity Framework Core: преобразование документов JSON, экспортированных из базы данных, в классы сущностей, использование в качестве базовых ссылочных классов для миграций моделей EF Core, в сочетании с аннотациями данных, такими как [Key]/[Required]
• Azure Functions / AWS Lambda: преобразование JSON событий триггеров Event Grid/SNS/API Gateway/Cosmos DB в параметры событий строгого типа, упрощение сигнатур бессерверных функций
• Общение в реальном времени SignalR: преобразование JSON-сообщений, отправляемых сервером (чат, уведомления, котировки, данные IoT), в типы C#, потребление строгого типа в методах Hub
• Контракты интерфейсов микросервисов: преобразование примеров JSON запросов/ответов RPC между сервисами (gRPC-Web/HTTP/WCF) в классы C#, использование в качестве определений общих контрактов между несколькими командами
• Загрузка конфигурационных файлов: преобразование подструктуры appsettings.json в классы шаблона Options (например MyOptions : IOptions<MyOptions> в сочетании с IConfiguration.Bind)
• Подготовка тестовых данных: преобразование фикстур JSON в классы C#, затем десериализация с помощью Newtonsoft/System.Text.Json в качестве драйвера модульных тестов, в сочетании с xUnit/NUnit/MSTest
• Парсинг данных краулера: преобразование данных JSON, собранных HtmlAgilityPack/AngleSharp/PuppeteerSharp, в классы C#, избежание пропуска полей при динамическом доступе JObject
• Написание документации API: включение примеров классов C# в определения schema в документации Swagger/OpenAPI, ReDoc, Knife4j, Swagger UI для повышения читаемости документации
• Сотрудничество при ревью кода: прямое преобразование JSON ответа API в удобочитаемые POCO, удобство обсуждения именования полей, выбора типов, использования аннотаций во время Code Review
• Рефакторинг старых проектов: рефакторинг динамического доступа на основе JObject/Dictionary<string, object> в доступ строгого типа на основе POCO, повышение проверки типов во время компиляции и поддерживаемости
• Обучение и тренировка: преобразование примера JSON в POCO на курсах C#, вводном обучении .NET для демонстрации объектно-ориентированного моделирования, аксессоров свойств, принципов сериализации

Как использовать

1. Вставьте содержимое JSON в редактор слева, или нажмите кнопку загрузки для выбора файла .json/.txt, или нажмите кнопку примера для загрузки встроенных данных
2. Подождите 400 мс для автоматического преобразования, справа отобразится сгенерированный код класса C# POCO
3. Если есть ошибки формата JSON, можно нажать кнопку «Исправить JSON» для автоматического исправления распространенных синтаксических проблем перед повторным преобразованием
4. Нажмите кнопку «Копировать» для копирования отдельного класса в буфер обмена и вставки в Visual Studio/Rider/VS Code, или нажмите «Загрузить» для сохранения в виде файла .cs

Функции

• Чистая локальная генерация в браузере: парсинг JSON и генерация кода C# полностью выполняются в браузере через JavaScript + quicktype-core, входные данные не загружаются на какие-либо серверы
• Две формы POCO + record: по умолчанию генерируются сериализуемые классы POCO, переключение на тип record C# 9+ в один клик, соответствие современному стилю кодирования .NET
• Аннотации Newtonsoft [JsonProperty]: автоматическое добавление [JsonProperty("исходный ключ")] для каждого поля, совместимость с поведением по умолчанию Newtonsoft.Json, имена полей PascalCase не влияют на десериализацию
• Автоматическое разделение вложенных объектов: вложенные объекты JSON рекурсивно генерируют независимые классы C#, именование по правилу заглавной первой буквы имени поля (например address → Address), избежание конфликтов типов
• Автоматическое развертывание обобщений List: массивы JSON автоматически преобразуются в List<T>, T автоматически выводится из первого элемента массива (["a","b"] → List<string>, [{...}] → List<Item>)
• Автоматический вывод Nullable<T>: поля со значением null в JSON автоматически помечаются как Nullable<T> (например long? / string? / bool?), предотвращение исключений нулевой ссылки во время компиляции
• Именование полей PascalCase: вход snake_case автоматически преобразуется в PascalCase (например user_name → UserName), при этом аннотация [JsonProperty] сохраняет исходный ключ для обеспечения совместимости десериализации
• Богатое соответствие типов значений: string→string, integer→long, float→double, bool→bool, array→List<T>, null→Nullable<T>
• Полный шаблон .cs: автоматическая генерация стандартного файла C#, содержащего using System.Collections.Generic; + namespace + public class + поля + свойства, с возможностью прямой компиляции
• Копирование и загрузка: копирование отдельного класса в буфер обмена или загрузка в виде файла .cs одним кликом, напрямую перетаскивание в Visual Studio / Rider / VS Code для использования
• Исправление ошибок JSON одним кликом: автоматическое исправление распространенных ошибок форматирования, таких как конечные запятые, одинарные кавычки, отсутствующие кавычки, после успешного исправления продолжение генерации кода C#
• Локальная история: автоматическое сохранение последних вводов на основе localStorage, быстрое восстановление после обновления или случайного закрытия страницы для продолжения редактирования

Примеры кода

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Threading.Tasks;

public class ApiClient
{
    private static readonly HttpClient _http = new HttpClient();

    // POCO, сгенерированный инструментом:
    public class User
    {
        [JsonProperty("id")]
        public long Id { get; set; }

        [JsonProperty("name")]
        public string Name { get; set; }

        [JsonProperty("email")]
        public string Email { get; set; }

        [JsonProperty("is_active")]
        public bool? IsActive { get; set; }
    }

    public static async Task<User> GetUserAsync(int userId)
    {
        // 1) Вызов API для получения строки JSON
        var json = await _http.GetStringAsync($"https://api.example.com/users/{userId}");

        // 2) Десериализация в POCO, сгенерированный инструментом
        //    Внутреннее автоматическое сопоставление JSON snake_case по аннотациям, таким как [JsonProperty("id")]
        var user = JsonConvert.DeserializeObject<User>(json);

        Console.WriteLine($"User: {user.Name} ({user.Email})");
        return user;
    }
}

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;

// POCO, сгенерированный инструментом (по умолчанию использует Newtonsoft [JsonProperty]):
public class CreateOrderRequest
{
    [Newtonsoft.Json.JsonProperty("user_id")]
    public long UserId { get; set; }

    [Newtonsoft.Json.JsonProperty("items")]
    public List<OrderItem> Items { get; set; }
}

public class OrderItem
{
    [Newtonsoft.Json.JsonProperty("product_id")]
    public long ProductId { get; set; }

    [Newtonsoft.Json.JsonProperty("quantity")]
    public long Quantity { get; set; }
}

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    [HttpPost]
    public IActionResult Create([FromBody] CreateOrderRequest request)
    {
        if (request == null || request.Items == null || !request.Items.Any())
        {
            return BadRequest("Items cannot be empty");
        }

        // Бизнес-логика: сохранение заказа
        // var order = OrderService.Create(request);

        return Ok(new { order_id = 12345, status = "created" });
    }
}

/*
 * Соответствующие зависимости .csproj:
 * <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="7.0.0" />
 * <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
 */

using System.Net.Http.Json;
using System.Text.Json.Serialization;
using System.Threading.Tasks;

// Инструмент по умолчанию генерирует POCO class; можно вручную изменить на тип record (неизменяемый объект передачи данных) следующим образом:
public record User
{
    [JsonPropertyName("id")]
    public long Id { get; init; }

    [JsonPropertyName("name")]
    public string Name { get; init; }

    [JsonPropertyName("email")]
    public string Email { get; init; }

    [JsonPropertyName("is_active")]
    public bool? IsActive { get; init; }
}

public class ApiClient
{
    private static readonly HttpClient _http = new HttpClient();

    public static async Task<User> GetUserAsync(int userId)
    {
        // System.Text.Json: GetFromJsonAsync завершает HTTP + десериализацию в одну строку
        var user = await _http.GetFromJsonAsync<User>(
            $"https://api.example.com/users/{userId}");

        System.Console.WriteLine($"User: {user.Name} ({user.Email})");
        return user;
    }
}

/*
 * Соответствующие зависимости .csproj (System.Text.Json встроен, дополнительная установка не требуется):
 * <TargetFramework>net7.0</TargetFramework>
 *
 * Если проект .NET 7+ и нужно совместимость с синтаксисом Newtonsoft [JsonProperty],
 * можно добавить в Program.cs:
 *   builder.Services.AddControllers()
 *       .AddNewtonsoftJson(options =>
 *       {
 *           options.SerializerSettings.ContractResolver =
 *               new Newtonsoft.Json.Serialization.DefaultContractResolver();
 *       });
 */

Best Practices

Часто задаваемые вопросы

Устранение неполадок

Глоссарий

POCO (Plain Old CLR Object)

Аббревиатура «обычного CLR-объекта» в C#/.NET, ограничения: открытый конструктор по умолчанию + private поля + открытые свойства { get; set; } + отсутствие зависимостей от фреймворка. То, что генерирует этот инструмент, — стандартный POCO.

record

Неизменяемый тип объекта передачи данных, представленный в C# 9+, использует равенство значений, а не равенство ссылок. После генерации в этом инструменте можно вручную изменить на record, подходит для сценариев, таких как DTO, модели ответов API, неизменяемая конфигурация.

[JsonProperty]

Атрибут сопоставления полей Newtonsoft.Json. Этот инструмент по умолчанию добавляет [JsonProperty("исходный ключ")] для каждого поля, гарантируя, что имена полей PascalCase могут правильно десериализовать JSON в snake_case.

Newtonsoft.Json

Также известный как Json.NET, самая популярная библиотека JSON в экосистеме .NET. Имеет самую богатую экосистему и лучшую совместимость, поддерживается практически всеми проектами .NET. Использовался по умолчанию до ASP.NET Core 3.0, после 3.0 был заменен на System.Text.Json, но по-прежнему может быть совместим через пакет NuGet.

System.Text.Json

Высокопроизводительная библиотека JSON, встроенная в .NET Core 3.0+. Быстрый запуск, низкое потребление памяти, дружелюбна к AOT, включает [JsonPropertyName] (соответствует [JsonProperty] Newtonsoft) и настраиваемую политику именования JsonNamingPolicy.

Nullable<T>

Тип в C#, указывающий, что тип значения может быть null (например long? / bool?). Этот инструмент автоматически выводит поля null в JSON как Nullable<T>, чтобы избежать исключений нулевой ссылки во время компиляции.

List<T>

Обобщенный тип списка в фреймворке коллекций .NET. Этот инструмент автоматически преобразует массивы JSON в List<T>, T автоматически выводится из первого элемента массива (например ["a"] → List<string>).

namespace

Ключевое слово пространства имен в C# для организации классов, аналогично package в Java. Код, сгенерированный этим инструментом, по умолчанию не имеет namespace, можно добавить вручную (например namespace MyApp.Models).

ASP.NET Core

Открытый кроссплатформенный веб-фреймворк Microsoft. Классы POCO, сгенерированные этим инструментом, могут напрямую использоваться в сценариях, таких как привязка модели [FromBody] ASP.NET Core Controller, Minimal API, параметры компонентов Blazor.

Unity

Самый популярный в мире игровой движок, язык скриптов — C#. Классы POCO, сгенерированные этим инструментом, могут использоваться для парсинга ответов сетевого API Unity, моделирования данных конфигурации ScriptableObject.

Snake_case → PascalCase

Преобразование правил именования полей. Преобразование именования snake_case (например user_name, created_at) в именование PascalCase (например UserName, CreatedAt), соответствие официальным правилам именования .NET.

quicktype-core

Базовая зависимость этого инструмента — открытая многоязычная библиотека генерации типов JSON (проект quicktype), поддерживающая более десяти языков, включая C#, Java, TypeScript, Rust, Go, Swift и т.д., выполняется в браузере на основе TypeScript + WebAssembly.

.NET MAUI

Кроссплатформенный UI-фреймворк Microsoft (.NET Multi-platform App UI), код C# может совместно использоваться на iOS/Android/Windows/macOS. POCO, сгенерированные этим инструментом, подходят в качестве Model для привязки данных XAML в MAUI.

Blazor

SPA-фреймворк Microsoft на основе WebAssembly, имеет два режима: Server и WebAssembly. Классы C#, сгенерированные этим инструментом, могут использоваться для параметров компонентов Blazor, моделей ответов API строгого типа, повышения эффективности полностековой разработки на одном языке.

HttpClient.GetFromJsonAsync

Метод расширения .NET 5+/System.Net.Http.Json, завершает HTTP GET + десериализацию JSON в одну строку. В сочетании с POCO, сгенерированными этим инструментом, может значительно упростить код клиента HTTP API.

JsonNamingPolicy

Класс в System.Text.Json, управляющий правилами сопоставления между именами полей JSON и именами свойств C# (например CamelCase, SnakeCaseLower). Newtonsoft.Json реализуется через аннотацию [JsonProperty] или ContractResolver.

IOptions<T>

Основной интерфейс шаблона Options в .NET, связывает подструктуру appsettings.json с классом строгого типа. POCO, сгенерированные этим инструментом, в сочетании с IConfiguration.Bind могут напрямую использоваться как реализация IOptions<T>.

Таблица быстрого сопоставления типов JSON с типами C#

Инструмент автоматически выводит соответствующие типы .NET/C# на основе типов значений JSON:

Таблица сравнения аннотаций Newtonsoft.Json и System.Text.Json

Сравнение атрибутов сопоставления полей двух основных библиотек JSON в экосистеме .NET. Этот инструмент по умолчанию генерирует [JsonProperty], совместимый с Newtonsoft:

Privacy & Security

Все операции этого инструмента JSON в C# полностью выполняются локально в вашем браузере: парсинг JSON, генерация кода C# и загрузка файлов — все выполняется на стороне клиента через JavaScript + WebAssembly (quicktype-core) браузера, содержимое JSON, загруженные файлы или сгенерированный код не отправляются на какие-либо серверы по сети. Загрузка файлов использует собственный API FileReader браузера для прямого чтения в память, не проходит через какие-либо промежуточные сервисы. Не используется отслеживание Cookie, не собираются данные пользовательского ввода или данные поведения при использовании. После закрытия или обновления страницы все содержимое ввода и вывода автоматически удаляется из памяти. Подходит для обработки JSON, содержащего ключи API, токены, чувствительные бизнес-данные.

Authoritative References

• MicrosoftMicrosoft Learn - Руководство по программированию на C#
• MicrosoftMicrosoft Learn - Обзор System.Text.Json
• NewtonsoftОфициальная документация Newtonsoft.Json
• MicrosoftMicrosoft Learn - Привязка моделей ASP.NET Core Web API
• MicrosoftMicrosoft Learn - Тип record C# 9