JSON sang C#

Đề xuất Liên quan

Giới thiệu về JSON sang C#: Chuyển đổi dữ liệu JSON thành lớp C# POCO có thể biên dịch

Trường hợp sử dụng

• ASP.NET Core Web API: Chuyển đổi JSON mẫu trong tài liệu OpenAPI/Swagger thành lớp DTO, kết hợp với ràng buộc mô hình [FromBody] để nhận yêu cầu từ frontend
• ASP.NET Core MVC: Chuyển đổi nội dung yêu cầu form/JSON thành Model kiểu mạnh, kết hợp với xác thực tự động ModelState
• Giải tuần tự hóa Newtonsoft.Json: Chuyển đổi JSON phản hồi từ giao diện bên thứ ba thành lớp POCO với [JsonProperty], không cần ánh xạ trường thủ công
• Kịch bản hiệu năng cao System.Text.Json: Chuyển đổi JSON thành kiểu record hoặc thuộc tính init-only, kết hợp với JsonSerializer.Deserialize<T> để cải thiện tốc độ khởi động
• Script game Unity: Chuyển đổi JSON trả về từ API mạng (dữ liệu người chơi, cấu hình màn chơi, vật phẩm cửa hàng, bảng xếp hạng) thành mô hình dữ liệu ScriptableObject có thể tuần tự hóa
• Ứng dụng đa nền tảng .NET MAUI: Chuyển đổi JSON từ API backend thành lớp Model, sử dụng trong ràng buộc dữ liệu XAML, chia sẻ mô hình nghiệp vụ trên iOS/Android/Windows
• Blazor Server / WebAssembly: Chuyển đổi JSON từ API thành tham số thành phần/mô hình máy chủ kiểu mạnh, kết hợp với @inject HttpClient để tiêu thụ kiểu chia sẻ frontend/backend
• Entity Framework Core: Chuyển đổi tài liệu JSON xuất từ cơ sở dữ liệu thành lớp thực thể, làm lớp cơ sở tham chiếu cho di chuyển mô hình EF Core, kết hợp với các chú thích dữ liệu như [Key]/[Required]
• Azure Functions / AWS Lambda: Chuyển đổi JSON từ sự kiện kích hoạt Event Grid/SNS/API Gateway/Cosmos DB thành tham số sự kiện kiểu mạnh, đơn giản hóa chữ ký hàm serverless
• Giao tiếp thời gian thực SignalR: Chuyển đổi tin nhắn JSON được đẩy từ máy chủ (trò chuyện, thông báo, giá thị trường, dữ liệu IoT) thành kiểu C#, tiêu thụ kiểu mạnh trong phương thức Hub
• Hợp đồng giao tiếp vi dịch vụ: Chuyển đổi mẫu yêu cầu/phản hồi JSON của RPC giữa các dịch vụ (gRPC-Web/HTTP/WCF) thành lớp C#, làm định nghĩa hợp đồng chia sẻ giữa nhiều nhóm
• Tải tệp cấu hình: Chuyển đổi cấu trúc con appsettings.json thành lớp mẫu Options (ví dụ MyOptions : IOptions<MyOptions> kết hợp với IConfiguration.Bind)
• Chuẩn bị dữ liệu kiểm thử: Chuyển đổi fixture JSON thành lớp C#, sau đó giải tuần tự hóa bằng Newtonsoft/System.Text.Json làm động lực kiểm thử đơn vị, kết hợp với xUnit/NUnit/MSTest
• Phân tích dữ liệu trình thu thập dữ liệu web: Chuyển đổi dữ liệu JSON thu thập bằng HtmlAgilityPack/AngleSharp/PuppeteerSharp thành lớp C#, tránh thiếu trường do truy cập động JObject
• Viết tài liệu API: Đưa ví dụ lớp C# vào định nghĩa schema trong tài liệu Swagger/OpenAPI, ReDoc, Knife4j, Swagger UI để cải thiện khả năng đọc của tài liệu
• Hợp tác đánh giá mã: Chuyển đổi JSON phản hồi API trực tiếp thành POCO dễ đọc, thuận tiện cho việc thảo luận về đặt tên trường, lựa chọn kiểu, sử dụng chú thích trong Code Review
• Tái cấu trúc dự án cũ: Tái cấu trúc truy cập động dựa trên JObject/Dictionary<string, object> thành truy cập kiểu mạnh dựa trên POCO, cải thiện kiểm tra kiểu tại thời gian biên dịch và khả năng bảo trì
• Đào tạo và huấn luyện: Chuyển đổi JSON mẫu thành POCO trong khóa học C#, đào tạo nhập môn .NET để trình diễn mô hình hóa hướng đối tượng, bộ truy cập thuộc tính, nguyên tắc tuần tự hóa

Cách Sử dụng

1. Dán nội dung JSON vào trình soạn thảo bên trái, hoặc nhấp nút tải lên để chọn tệp .json/.txt, hoặc nhấp nút ví dụ để tải dữ liệu có sẵn
2. Đợi 400ms để tự động chuyển đổi, bên phải sẽ hiển thị mã lớp C# POCO được tạo
3. Nếu có lỗi định dạng JSON, có thể nhấp nút "Sửa JSON" để tự động sửa các vấn đề cú pháp phổ biến rồi chuyển đổi lại
4. Nhấp nút "Sao chép" để sao chép một lớp vào bộ nhớ đệm dán vào Visual Studio/Rider/VS Code, hoặc nhấp "Tải xuống" để lưu dưới dạng tệp .cs

Tính năng

• Tạo hoàn toàn cục bộ trên trình duyệt: Phân tích JSON và tạo mã C# đều được thực hiện trong trình duyệt thông qua JavaScript + quicktype-core, dữ liệu đầu vào không được tải lên bất kỳ máy chủ nào
• Hai dạng POCO + record: Mặc định tạo lớp POCO có thể tuần tự hóa, chuyển đổi sang kiểu record C# 9+ chỉ với một cú nhấp chuột, phù hợp với phong cách mã hóa .NET hiện đại
• Chú thích Newtonsoft [JsonProperty]: Tự động thêm [JsonProperty("khóa gốc")] cho mỗi trường, tương thích với hành vi mặc định của Newtonsoft.Json, tên trường PascalCase không ảnh hưởng đến việc giải tuần tự hóa
• Tự động tách đối tượng lồng nhau: Các đối tượng JSON lồng nhau sẽ được tạo đệ quy thành các lớp C# độc lập, đặt tên theo quy tắc viết hoa chữ cái đầu của tên trường (ví dụ address → Address), tránh xung đột kiểu
• Tự động mở rộng List generic: Mảng JSON tự động chuyển thành List<T>, T được suy luận tự động từ phần tử đầu tiên của mảng (["a","b"] → List<string>, [{...}] → List<Item>)
• Tự động suy luận Nullable<T>: Trường có giá trị null trong JSON tự động được đánh dấu là Nullable<T> (ví dụ long? / string? / bool?), tránh ngoại lệ tham chiếu null tại thời gian biên dịch
• Đặt tên trường PascalCase: Đầu vào snake_case tự động chuyển thành PascalCase (ví dụ user_name → UserName), đồng thời chú thích [JsonProperty] giữ nguyên khóa gốc để đảm bảo tương thích giải tuần tự hóa
• Ánh xạ kiểu giá trị phong phú: string→string, integer→long, float→double, bool→bool, array→List<T>, null→Nullable<T>
• Mẫu .cs hoàn chỉnh: Tự động tạo tệp C# tiêu chuẩn bao gồm using System.Collections.Generic; + namespace + public class + trường + thuộc tính, có thể biên dịch trực tiếp
• Sao chép và tải xuống: Sao chép một lớp vào bộ nhớ đệm hoặc tải xuống dưới dạng tệp .cs chỉ với một cú nhấp chuột, kéo thả trực tiếp vào Visual Studio / Rider / VS Code để sử dụng
• Sửa lỗi JSON một cú nhấp: Tự động sửa các lỗi định dạng phổ biến như dấu phẩy đuôi, dấu nháy đơn, thiếu dấu nháy, sau khi sửa thành công tiếp tục tạo mã C#
• Lịch sử cục bộ: Tự động lưu đầu vào gần nhất dựa trên localStorage, có thể khôi phục nhanh chóng sau khi làm mới trang hoặc vô tình đóng để tiếp tục chỉnh sửa

Ví dụ mã

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

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

    // POCO do công cụ tạo:
    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) Gọi API lấy chuỗi JSON
        var json = await _http.GetStringAsync($"https://api.example.com/users/{userId}");

        // 2) Giải tuần tự hóa thành POCO do công cụ tạo
        //    Nội bộ tự động ánh xạ JSON snake_case theo các chú thích như [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 do công cụ tạo (mặc định sử dụng 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");
        }

        // Logic nghiệp vụ: lưu đơn hàng
        // var order = OrderService.Create(request);

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

/*
 * Phụ thuộc .csproj tương ứng:
 * <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;

// Công cụ mặc định tạo POCO class; có thể thủ công thay đổi thành kiểu record (đối tượng truyền dữ liệu bất biến) như sau:
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 hoàn thành HTTP + giải tuần tự hóa trong một dòng
        var user = await _http.GetFromJsonAsync<User>(
            $"https://api.example.com/users/{userId}");

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

/*
 * Phụ thuộc .csproj tương ứng (System.Text.Json được tích hợp sẵn, không cần cài đặt thêm):
 * <TargetFramework>net7.0</TargetFramework>
 *
 * Nếu dự án là .NET 7+ và muốn tương thích với cú pháp Newtonsoft [JsonProperty],
 * có thể thêm vào Program.cs:
 *   builder.Services.AddControllers()
 *       .AddNewtonsoftJson(options =>
 *       {
 *           options.SerializerSettings.ContractResolver =
 *               new Newtonsoft.Json.Serialization.DefaultContractResolver();
 *       });
 */

Best Practices

Câu hỏi Thường gặp

Xử lý sự cố

Thuật ngữ

POCO (Plain Old CLR Object)

Viết tắt của "Đối tượng CLR thông thường" trong C#/.NET, các ràng buộc là: hàm tạo mặc định công khai + trường private + thuộc tính công khai { get; set; } + không phụ thuộc khung. Những gì công cụ này tạo ra là POCO tiêu chuẩn.

record

Kiểu đối tượng truyền dữ liệu bất biến được giới thiệu trong C# 9+, sử dụng đẳng thức giá trị thay vì đẳng thức tham chiếu. Sau khi tạo trong công cụ này có thể thủ công thay đổi thành record, phù hợp cho các kịch bản như DTO, mô hình phản hồi API, cấu hình bất biến.

[JsonProperty]

Thuộc tính ánh xạ trường của Newtonsoft.Json. Công cụ này mặc định thêm [JsonProperty("khóa gốc")] cho mỗi trường, đảm bảo tên trường PascalCase có thể giải tuần tự hóa chính xác JSON snake_case.

Newtonsoft.Json

Còn gọi là Json.NET, là thư viện JSON phổ biến nhất trong hệ sinh thái .NET. Có hệ sinh thái phong phú nhất và khả năng tương thích tốt nhất, được hỗ trợ bởi hầu hết các dự án .NET. Được sử dụng mặc định trước ASP.NET Core 3.0, sau 3.0 được thay thế bằng System.Text.Json, nhưng vẫn có thể tiếp tục tương thích thông qua gói NuGet.

System.Text.Json

Thư viện JSON hiệu năng cao được tích hợp sẵn trong .NET Core 3.0+. Khởi động nhanh, chiếm dụng bộ nhớ thấp, thân thiện với AOT, bao gồm [JsonPropertyName] (tương ứng với [JsonProperty] của Newtonsoft) và chính sách đặt tên tùy chỉnh JsonNamingPolicy.

Nullable<T>

Kiểu trong C# chỉ định rằng kiểu giá trị có thể là null (ví dụ long? / bool?). Công cụ này tự động suy luận trường null trong JSON thành Nullable<T> để tránh ngoại lệ tham chiếu null tại thời gian biên dịch.

List<T>

Kiểu danh sách generic trong khung tập hợp .NET. Công cụ này tự động chuyển đổi mảng JSON thành List<T>, T được suy luận tự động từ phần tử đầu tiên của mảng (ví dụ ["a"] → List<string>).

namespace

Từ khóa không gian tên trong C# để tổ chức các lớp, tương tự như package trong Java. Mã do công cụ này tạo ra mặc định không có namespace, có thể thêm thủ công (ví dụ namespace MyApp.Models).

ASP.NET Core

Khung web nguồn mở đa nền tảng của Microsoft. Các lớp POCO do công cụ này tạo ra có thể được sử dụng trực tiếp trong các kịch bản như ràng buộc mô hình ASP.NET Core Controller [FromBody], Minimal API, tham số thành phần Blazor.

Unity

Công cụ game phổ biến nhất thế giới, ngôn ngữ script là C#. Các lớp POCO do công cụ này tạo ra có thể được sử dụng để phân tích phản hồi API mạng Unity, mô hình hóa dữ liệu cấu hình ScriptableObject.

Snake_case → PascalCase

Chuyển đổi quy tắc đặt tên trường. Chuyển đổi đặt tên snake_case (ví dụ user_name, created_at) thành đặt tên PascalCase (ví dụ UserName, CreatedAt), tuân thủ quy phạm đặt tên chính thức của .NET.

quicktype-core

Thư viện tạo kiểu JSON đa ngôn ngữ nguồn mở (dự án quicktype) mà công cụ này phụ thuộc cơ bản, hỗ trợ hơn mười ngôn ngữ bao gồm C#, Java, TypeScript, Rust, Go, Swift, v.v., thực thi trên trình duyệt dựa trên TypeScript + WebAssembly.

.NET MAUI

Khung UI đa nền tảng của Microsoft (.NET Multi-platform App UI), mã C# có thể chia sẻ trên iOS/Android/Windows/macOS. POCO do công cụ này tạo ra phù hợp làm Model cho ràng buộc dữ liệu XAML trong MAUI.

Blazor

Khung SPA dựa trên WebAssembly của Microsoft, có hai chế độ Server và WebAssembly. Các lớp C# do công cụ này tạo ra có thể được sử dụng cho tham số thành phần Blazor, mô hình phản hồi API kiểu mạnh, nâng cao hiệu quả phát triển toàn ngăn xếp một ngôn ngữ.

HttpClient.GetFromJsonAsync

Phương thức mở rộng .NET 5+/System.Net.Http.Json, hoàn thành HTTP GET + giải tuần tự hóa JSON trong một dòng. Kết hợp với POCO do công cụ này tạo ra có thể đơn giản hóa đáng kể mã client API HTTP.

JsonNamingPolicy

Lớp trong System.Text.Json kiểm soát quy tắc ánh xạ giữa tên trường JSON và tên thuộc tính C# (ví dụ CamelCase, SnakeCaseLower). Newtonsoft.Json thực hiện thông qua chú thích [JsonProperty] hoặc ContractResolver.

IOptions<T>

Giao diện cốt lõi của mẫu Options trong .NET, liên kết cấu trúc con appsettings.json với lớp kiểu mạnh. POCO do công cụ này tạo ra có thể kết hợp với IConfiguration.Bind trực tiếp làm triển khai IOptions<T>.

Bảng tra cứu nhanh ánh xạ kiểu JSON sang kiểu C#

Công cụ tự động suy luận kiểu .NET/C# tương ứng dựa trên kiểu giá trị JSON:

Bảng so sánh chú thích Newtonsoft.Json và System.Text.Json

So sánh thuộc tính ánh xạ trường của hai thư viện JSON chính thống trong hệ sinh thái .NET. Công cụ này mặc định tạo [JsonProperty] tương thích Newtonsoft:

Privacy & Security

Tất cả các hoạt động của công cụ chuyển đổi JSON sang C# này được hoàn thành hoàn toàn cục bộ trên trình duyệt của bạn: phân tích JSON, tạo mã C# và tải xuống tệp đều được thực thi ở phía khách hàng thông qua JavaScript + WebAssembly (quicktype-core) của trình duyệt, không gửi nội dung JSON, tệp đã tải lên hoặc mã được tạo đến bất kỳ máy chủ nào qua mạng. Việc tải lên tệp sử dụng API FileReader gốc của trình duyệt để đọc trực tiếp vào bộ nhớ, không đi qua bất kỳ dịch vụ trung gian nào. Không sử dụng theo dõi Cookie, không thu thập dữ liệu đầu vào của người dùng hoặc dữ liệu hành vi sử dụng. Sau khi đóng hoặc làm mới trang, tất cả nội dung đầu vào và đầu ra sẽ tự động bị xóa khỏi bộ nhớ. Phù hợp để xử lý JSON chứa khóa API, mã thông báo, dữ liệu nghiệp vụ nhạy cảm.

Authoritative References

• MicrosoftMicrosoft Learn - Hướng dẫn lập trình C#
• MicrosoftMicrosoft Learn - Tổng quan về System.Text.Json
• NewtonsoftTài liệu chính thức Newtonsoft.Json
• MicrosoftMicrosoft Learn - Ràng buộc mô hình ASP.NET Core Web API
• MicrosoftMicrosoft Learn - Kiểu record C# 9