JSON na C#

Powiązane Rekomendacje

Wprowadzenie do JSON na C#: Konwertowanie danych JSON na kompilowalne klasy C# POCO

Przypadki użycia

• ASP.NET Core Web API: konwertowanie przykładowego JSON w dokumentacji OpenAPI/Swagger na klasy DTO, w połączeniu z wiązaniem modelu [FromBody] do odbierania żądań z frontendu
• ASP.NET Core MVC: konwertowanie treści żądania formularza/JSON na Model silnego typu, w połączeniu z automatyczną walidacją ModelState
• Deserializacja Newtonsoft.Json: konwertowanie JSON odpowiedzi interfejsu trzeciego na klasy POCO z [JsonProperty], nie wymaga ręcznego mapowania pól
• Wysokowydajne scenariusze System.Text.Json: konwertowanie JSON na typ record lub właściwości init-only, w połączeniu z JsonSerializer.Deserialize<T> w celu zwiększenia szybkości uruchamiania
• Skrypty gier Unity: konwertowanie JSON zwracanego przez API sieciowe (dane gracza, konfiguracja poziomu, przedmioty sklepu, ranking) na serializowalne modele danych ScriptableObject
• Aplikacje międzyplatformowe .NET MAUI: konwertowanie JSON z backend API na klasy Model, użycie w wiązaniu danych XAML, współdzielenie modelu biznesowego na iOS/Android/Windows
• Blazor Server / WebAssembly: konwertowanie JSON z API na parametry komponentów/serwerowe modele silnego typu, w połączeniu z @inject HttpClient do konsumpcji wspólnych typów frontend/backend
• Entity Framework Core: konwertowanie dokumentów JSON wyeksportowanych z bazy danych na klasy encji, użycie jako podstawowych klas referencyjnych dla migracji modeli EF Core, w połączeniu z adnotacjami danych, takimi jak [Key]/[Required]
• Azure Functions / AWS Lambda: konwertowanie JSON zdarzeń wyzwalaczy Event Grid/SNS/API Gateway/Cosmos DB na parametry zdarzeń silnego typu, uproszczenie sygnatur bezserwerowych funkcji
• Komunikacja w czasie rzeczywistym SignalR: konwertowanie komunikatów JSON wysyłanych przez serwer (czat, powiadomienia, notowania, dane IoT) na typy C#, konsumpcja silnego typu w metodach Hub
• Kontrakty interfejsów mikrousług: konwertowanie przykładowych JSON żądań/odpowiedzi RPC między usługami (gRPC-Web/HTTP/WCF) na klasy C#, użycie jako definicji wspólnych kontraktów między wieloma zespołami
• Ładowanie plików konfiguracyjnych: konwertowanie podstruktury appsettings.json na klasy szablonu Options (np. MyOptions : IOptions<MyOptions> w połączeniu z IConfiguration.Bind)
• Przygotowanie danych testowych: konwertowanie fixture JSON na klasy C#, następnie deserializacja za pomocą Newtonsoft/System.Text.Json jako sterownika testów jednostkowych, w połączeniu z xUnit/NUnit/MSTest
• Parsowanie danych crawlera: konwertowanie danych JSON zebranych przez HtmlAgilityPack/AngleSharp/PuppeteerSharp na klasy C#, unikanie pomijania pól przy dynamicznym dostępie JObject
• Pisanie dokumentacji API: włączanie przykładów klas C# do definicji schema w dokumentacji Swagger/OpenAPI, ReDoc, Knife4j, Swagger UI w celu zwiększenia czytelności dokumentacji
• Współpraca przy przeglądzie kodu: bezpośrednie konwertowanie JSON odpowiedzi API na czytelne POCO, ułatwienie dyskusji na temat nazewnictwa pól, wyboru typów, użycia adnotacji podczas Code Review
• Refaktoryzacja starych projektów: refaktoryzacja dynamicznego dostępu opartego na JObject/Dictionary<string, object> na dostęp silnego typu opartego na POCO, zwiększenie kontroli typów podczas kompilacji i utrzymywalności
• Edukacja i szkolenia: konwertowanie przykładowego JSON na POCO na kursach C#, szkoleniach wprowadzających .NET do demonstrowania modelowania obiektowego, akcesorów właściwości, zasad serializacji

Jak Używać

1. Wklej zawartość JSON w edytor po lewej stronie, lub kliknij przycisk przesyłania, aby wybrać plik .json/.txt, lub kliknij przycisk przykładu, aby załadować wbudowane dane
2. Poczekaj 400 ms na automatyczną konwersję, po prawej stronie wyświetli się wygenerowany kod klasy C# POCO
3. Jeśli występują błędy formatu JSON, możesz kliknąć przycisk «Napraw JSON», aby automatycznie naprawić typowe problemy składniowe przed ponowną konwersją
4. Kliknij przycisk «Kopiuj», aby skopiować pojedynczą klasę do schowka i wkleić do Visual Studio/Rider/VS Code, lub kliknij «Pobierz», aby zapisać jako plik .cs

Funkcje

• Czyste lokalne generowanie w przeglądarce: parsowanie JSON i generowanie kodu C# odbywa się całkowicie w przeglądarce przez JavaScript + quicktype-core, dane wejściowe nie są wysyłane na żadne serwery
• Dwie formy POCO + record: domyślnie generowane są serializowalne klasy POCO, przełączanie na typ record C# 9+ jednym kliknięciem, zgodne z nowoczesnym stylem kodowania .NET
• Adnotacje Newtonsoft [JsonProperty]: automatyczne dodawanie [JsonProperty("oryginalny klucz")] dla każdego pola, kompatybilność z domyślnym zachowaniem Newtonsoft.Json, nazwy pól PascalCase nie wpływają na deserializację
• Automatyczny podział zagnieżdżonych obiektów: zagnieżdżone obiekty JSON rekurencyjnie generują niezależne klasy C#, nazewnictwo według reguły wielkiej litery na początku nazwy pola (np. address → Address), unikanie konfliktów typów
• Automatyczne rozwijanie generyków List: tablice JSON automatycznie konwertowane na List<T>, T automatycznie wnioskowane z pierwszego elementu tablicy (["a","b"] → List<string>, [{...}] → List<Item>)
• Automatyczne wnioskowanie Nullable<T>: pola z wartością null w JSON automatycznie oznaczane jako Nullable<T> (np. long? / string? / bool?), zapobieganie wyjątkom odwołania null podczas kompilacji
• Nazewnictwo pól PascalCase: wejście snake_case automatycznie konwertowane na PascalCase (np. user_name → UserName), jednocześnie adnotacja [JsonProperty] zachowuje oryginalny klucz dla zapewnienia kompatybilności deserializacji
• Bogate mapowanie typów wartości: string→string, integer→long, float→double, bool→bool, array→List<T>, null→Nullable<T>
• Pełny szablon .cs: automatyczne generowanie standardowego pliku C# zawierającego using System.Collections.Generic; + namespace + public class + pola + właściwości, możliwość bezpośredniej kompilacji
• Kopiowanie i pobieranie: kopiowanie pojedynczej klasy do schowka lub pobieranie jako plik .cs jednym kliknięciem, bezpośrednie przeciąganie do Visual Studio / Rider / VS Code do użycia
• Naprawa błędów JSON jednym kliknięciem: automatyczne naprawianie typowych błędów formatowania, takich jak końcowe przecinki, pojedyncze cudzysłowy, brakujące cudzysłowy, po pomyślnej naprawie kontynuacja generowania kodu C#
• Lokalna historia: automatyczne zapisywanie ostatnich wejść na podstawie localStorage, szybkie przywracanie po odświeżeniu lub przypadkowym zamknięciu strony w celu kontynuacji edycji

Przykłady kodu

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

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

    // POCO wygenerowany przez narzędzie:
    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) Wywołanie API w celu pobrania ciągu JSON
        var json = await _http.GetStringAsync($"https://api.example.com/users/{userId}");

        // 2) Deserializacja do POCO wygenerowanego przez narzędzie
        //    Wewnętrzne automatyczne mapowanie JSON snake_case według adnotacji, takich jak [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 wygenerowany przez narzędzie (domyślnie używa 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");
        }

        // Logika biznesowa: zapis zamówienia
        // var order = OrderService.Create(request);

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

/*
 * Odpowiednie zależności .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;

// Narzędzie domyślnie generuje POCO class; można ręcznie zmienić na typ record (niezmienny obiekt przekazywania danych) w następujący sposób:
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 kończy HTTP + deserializację w jednej linii
        var user = await _http.GetFromJsonAsync<User>(
            $"https://api.example.com/users/{userId}");

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

/*
 * Odpowiednie zależności .csproj (System.Text.Json jest wbudowany, dodatkowa instalacja nie jest wymagana):
 * <TargetFramework>net7.0</TargetFramework>
 *
 * Jeśli projekt jest .NET 7+ i potrzebna jest kompatybilność ze składnią Newtonsoft [JsonProperty],
 * można dodać w Program.cs:
 *   builder.Services.AddControllers()
 *       .AddNewtonsoftJson(options =>
 *       {
 *           options.SerializerSettings.ContractResolver =
 *               new Newtonsoft.Json.Serialization.DefaultContractResolver();
 *       });
 */

Best Practices

Często Zadawane Pytania

Rozwiązywanie problemów

Słownik

POCO (Plain Old CLR Object)

Skrót od «zwykłego obiektu CLR» w C#/.NET, ograniczenia: publiczny konstruktor domyślny + pola private + publiczne właściwości { get; set; } + brak zależności od frameworka. To, co generuje to narzędzie, to standardowy POCO.

record

Niezmienny typ obiektu przekazywania danych wprowadzony w C# 9+, używa równości wartości zamiast równości odwołań. Po wygenerowaniu w tym narzędziu można ręcznie zmienić na record, odpowiedni dla scenariuszy, takich jak DTO, modele odpowiedzi API, niezmienna konfiguracja.

[JsonProperty]

Atrybut mapowania pól Newtonsoft.Json. To narzędzie domyślnie dodaje [JsonProperty("oryginalny klucz")] dla każdego pola, zapewniając, że nazwy pól PascalCase mogą poprawnie deserializować JSON w snake_case.

Newtonsoft.Json

Znany również jako Json.NET, najpopularniejsza biblioteka JSON w ekosystemie .NET. Ma najbogatszy ekosystem i najlepszą kompatybilność, obsługiwana przez praktycznie wszystkie projekty .NET. Używana domyślnie przed ASP.NET Core 3.0, po 3.0 została zastąpiona przez System.Text.Json, ale nadal może być kompatybilna przez pakiet NuGet.

System.Text.Json

Wysokowydajna biblioteka JSON wbudowana w .NET Core 3.0+. Szybkie uruchamianie, niskie zużycie pamięci, przyjazna dla AOT, zawiera [JsonPropertyName] (odpowiadający [JsonProperty] Newtonsoft) i niestandardową politykę nazewnictwa JsonNamingPolicy.

Nullable<T>

Typ w C# wskazujący, że typ wartości może być null (np. long? / bool?). To narzędzie automatycznie wnioskuje pola null w JSON jako Nullable<T>, aby uniknąć wyjątków odwołania null podczas kompilacji.

List<T>

Generyczny typ listy w frameworku kolekcji .NET. To narzędzie automatycznie konwertuje tablice JSON na List<T>, T jest automatycznie wnioskowane z pierwszego elementu tablicy (np. ["a"] → List<string>).

namespace

Słowo kluczowe przestrzeni nazw w C# do organizowania klas, podobne do package w Javie. Kod wygenerowany przez to narzędzie domyślnie nie ma namespace, można dodać ręcznie (np. namespace MyApp.Models).

ASP.NET Core

Otwarty międzyplatformowy framework webowy Microsoft. Klasy POCO wygenerowane przez to narzędzie mogą być bezpośrednio używane w scenariuszach, takich jak wiązanie modelu [FromBody] ASP.NET Core Controller, Minimal API, parametry komponentów Blazor.

Unity

Najpopularniejszy silnik gier na świecie, język skryptów to C#. Klasy POCO wygenerowane przez to narzędzie mogą być używane do parsowania odpowiedzi API sieciowego Unity, modelowania danych konfiguracyjnych ScriptableObject.

Snake_case → PascalCase

Konwersja reguł nazewnictwa pól. Konwertowanie nazewnictwa snake_case (np. user_name, created_at) na nazewnictwo PascalCase (np. UserName, CreatedAt), zgodnie z oficjalnymi regułami nazewnictwa .NET.

quicktype-core

Podstawowa zależność tego narzędzia — otwarta wielojęzyczna biblioteka generowania typów JSON (projekt quicktype), obsługująca ponad dziesięć języków, w tym C#, Java, TypeScript, Rust, Go, Swift itp., wykonywana w przeglądarce na podstawie TypeScript + WebAssembly.

.NET MAUI

Międzyplatformowy framework UI Microsoft (.NET Multi-platform App UI), kod C# może być współdzielony na iOS/Android/Windows/macOS. POCO wygenerowane przez to narzędzie są odpowiednie jako Model dla wiązania danych XAML w MAUI.

Blazor

Framework SPA Microsoft oparty na WebAssembly, ma dwa tryby: Server i WebAssembly. Klasy C# wygenerowane przez to narzędzie mogą być używane do parametrów komponentów Blazor, modeli odpowiedzi API silnego typu, zwiększania efektywności tworzenia pełnego stosu w jednym języku.

HttpClient.GetFromJsonAsync

Metoda rozszerzająca .NET 5+/System.Net.Http.Json, kończy HTTP GET + deserializację JSON w jednej linii. W połączeniu z POCO wygenerowanymi przez to narzędzie może znacznie uprościć kod klienta API HTTP.

JsonNamingPolicy

Klasa w System.Text.Json sterująca regułami mapowania między nazwami pól JSON a nazwami właściwości C# (np. CamelCase, SnakeCaseLower). Newtonsoft.Json jest implementowany przez adnotację [JsonProperty] lub ContractResolver.

IOptions<T>

Główny interfejs szablonu Options w .NET, wiąże podstrukturę appsettings.json z klasą silnego typu. POCO wygenerowane przez to narzędzie w połączeniu z IConfiguration.Bind mogą być bezpośrednio używane jako implementacja IOptions<T>.

Tabela szybkiego odniesienia mapowania typów JSON na typy C#

Narzędzie automatycznie wnioskuje odpowiednie typy .NET/C# na podstawie typów wartości JSON:

Tabela porównawcza adnotacji Newtonsoft.Json i System.Text.Json

Porównanie atrybutów mapowania pól dwóch głównych bibliotek JSON w ekosystemie .NET. To narzędzie domyślnie generuje [JsonProperty] kompatybilny z Newtonsoft:

Privacy & Security

Wszystkie operacje tego narzędzia JSON na C# są całkowicie wykonywane lokalnie w Twojej przeglądarce: parsowanie JSON, generowanie kodu C# i pobieranie plików — wszystko jest wykonywane po stronie klienta przez JavaScript + WebAssembly (quicktype-core) przeglądarki, zawartość JSON, przesłane pliki lub wygenerowany kod nie są wysyłane na żadne serwery przez sieć. Przesyłanie plików używa natywnego API FileReader przeglądarki do bezpośredniego odczytu do pamięci, nie przechodzi przez żadne usługi pośrednie. Nie używa śledzenia Cookie, nie zbiera danych wejściowych użytkownika ani danych zachowań podczas użytkowania. Po zamknięciu lub odświeżeniu strony cała zawartość wejścia i wyjścia jest automatycznie usuwana z pamięci. Odpowiednie do przetwarzania JSON zawierającego klucze API, tokeny, wrażliwe dane biznesowe.

Authoritative References

• MicrosoftMicrosoft Learn - Przewodnik po programowaniu w C#
• MicrosoftMicrosoft Learn - Przegląd System.Text.Json
• NewtonsoftOficjalna dokumentacja Newtonsoft.Json
• MicrosoftMicrosoft Learn - Wiązanie modeli ASP.NET Core Web API
• MicrosoftMicrosoft Learn - Typ record C# 9