Chuyển class C# sang JSON!

Dán mã C# (class·record) để nhận JSON mẫu! Hỗ trợ System.Text.Json [JsonPropertyName], Newtonsoft.Json [JsonProperty]. Hữu ích cho tài liệu API và request body thử nghiệm (mock request body).
C#
Kết quả
 

Chuyển class C# sang JSON!

Dán các model C# viết bằng class, record hoặc struct để nhận một tài liệu JSON mẫu theo quy tắc của System.Text.Json và Newtonsoft.Json. Bạn chọn giữa chính sách đặt tên camelCase mà ASP.NET Core dùng mặc định và giữ nguyên tên thuộc tính như đã viết; tên được đặt bằng [JsonPropertyName] hoặc [JsonProperty] luôn được ưu tiên.

Dùng nó để đưa mẫu cho frontend hay đối tác bên ngoài từ model request/response của Web API, để điền example cho Swagger (Swashbuckle), hoặc để chuẩn bị body cho integration test với HttpClient.

Cách sử dụng

  1. Dán mã nguồn model. using, namespace, constructor và method có thể để nguyên.
  2. Chọn Quy tắc đặt tên: camelCase (mặc định của ASP.NET Core) cho dự án Web API thông thường, hoặc Giữ nguyên tên thuộc tính nếu bạn đặt PropertyNamingPolicy = null hay dựa vào mặc định của Newtonsoft.
  3. Khi Kiểu gốc để Tự động, kiểu đầu tiên không được model nào khác tham chiếu sẽ thành gốc; đổi trong danh sách nếu cần.
  4. Sao chép JSON vào example của Swagger, file .http hoặc body request trong xUnit. Các lựa chọn option được lưu trong URL.

Ví dụ

Đầu vào (C#)
public class InventoryItem
{
    public Guid Id { get; set; }
    public string SKU { get; set; } = "";
    [JsonPropertyName("stock_qty")]
    public int StockQuantity { get; set; }
    public StockState State { get; set; } = StockState.InStock;
    public DateTimeOffset UpdatedAt { get; set; }
    public List<string> Barcodes { get; set; } = new();
    [JsonIgnore]
    public string WarehouseNote { get; set; } = "";
    private int _version;
}

public enum StockState { InStock, LowStock, OutOfStock }
Đầu ra (JSON · camelCase)
{
  "id": "00000000-0000-0000-0000-000000000000",
  "sku": "",
  "stock_qty": 0,
  "state": 0,
  "updatedAt": "1970-01-01T00:00:00+00:00",
  "barcodes": [
    ""
  ]
}

Với chính sách camelCase, tên viết hoa toàn bộ như SKU thành sku, khớp với JsonNamingPolicy.CamelCase của System.Text.Json, còn [JsonPropertyName("stock_qty")] giữ tên của nó bất kể chính sách. WarehouseNote ([JsonIgnore]) và field private _version bị loại ra. Enum State không có string converter nên hiện 0, giá trị số của initializer StockState.InStock.

Tính năng hỗ trợ

  • Attribute đổi tên: [JsonPropertyName] của System.Text.Json, [JsonProperty] của Newtonsoft, và [DataMember(Name = ...)].
  • Chỉ bao gồm property và field public, cùng các member không public được đánh dấu [JsonInclude]. static, const, [JsonIgnore] và [IgnoreDataMember] bị loại; ignore có điều kiện như Condition = WhenWritingNull vẫn được giữ.
  • Hỗ trợ positional record (record Customer(long Id, string Name)) và target [property: JsonPropertyName(...)].
  • Computed property dạng expression-bodied (=> ...) được đưa vào, giống như System.Text.Json sẽ serialize chúng.
  • Enum được ghi dưới dạng số, như mặc định của System.Text.Json và Newtonsoft (kể cả giá trị tường minh như = 10). Khi có [JsonConverter(typeof(JsonStringEnumConverter))] (hoặc StringEnumConverter của Newtonsoft) trên enum hay property, hoặc [JsonStringEnumMemberName] / [EnumMember(Value = ...)] trên member, chuỗi tên sẽ được dùng thay thế.
  • Ngày giờ và ID: DateTime → 1970-01-01T00:00:00, DateTimeOffset → 1970-01-01T00:00:00+00:00, DateOnly → 1970-01-01, TimeOnly/TimeSpan → 00:00:00, Guid → GUID toàn số 0.
  • int?/Nullable<T> dùng kiểu bên trong, List<T>/IEnumerable<T>/mảng có một phần tử, Dictionary<int, V> dùng key "0", còn object, JsonElement và JObject thành null.
  • Initializer dạng literal (= 1.5, = "KRW") được dùng làm giá trị mẫu.

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

Khớp example của Swashbuckle với response thật

DTO trộn [JsonPropertyName] với cách đặt tên mặc định khiến example tự sinh của Swagger UI dễ bị hiểu sai. Dùng output này trong ISchemaFilter hoặc comment XML <example> để tài liệu và response dùng chung một bộ key.

Chuyển từ Newtonsoft sang System.Text.Json

Đổi qua lại Quy tắc đặt tên trên cùng một model để xem trước cách viết hoa/thường của key thay đổi thế nào sau khi migrate.

Kiểm tra contract giữa client Unity/MAUI và server

Khi client và server giữ hai bản model riêng, hãy tạo JSON từ mỗi bên rồi so sánh để nhanh chóng phát hiện tên key lệch nhau.

Lưu ý và giới hạn

  • JsonStringEnumConverter đăng ký toàn cục bằng AddJsonOptions trong Program.cs không hiện ra trong code model, nên enum vẫn ra dạng số. Muốn thấy tên, hãy thêm [JsonConverter(typeof(JsonStringEnumConverter))] vào khai báo enum trước khi dán.
  • Kiểu tham chiếu nullable như string? nhận giá trị mẫu theo kiểu, không phải null.
  • Các attribute [JsonConverter] tùy biến khác ngoài enum string converter, DefaultIgnoreCondition trong JsonSerializerOptions, và chính sách snake_case (JsonNamingPolicy.SnakeCaseLower) không được áp dụng.
  • Đa hình qua [JsonPolymorphic]/[JsonDerivedType] không được hỗ trợ; chỉ kiểu cơ sở đã khai báo được tạo ra.

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

Khi nào dùng từng lựa chọn của Quy tắc đặt tên?

ASP.NET Core Web API dùng JsonSerializerDefaults.Web, tức camelCase. Một console app gọi JsonSerializer.Serialize không kèm option, hoặc thiết lập mặc định của Newtonsoft.Json, giữ nguyên tên thuộc tính, nên ở đó hãy chọn Giữ nguyên tên thuộc tính.

Vì sao computed property như public string FullName => ... lại xuất hiện?

Cả System.Text.Json và Newtonsoft.Json đều serialize property public có getter, nên computed property cũng có mặt trong response. Thêm [JsonIgnore] nếu bạn không muốn xuất chúng ra.

[JsonPropertyName] trên tham số positional của record không đổi tên key lúc runtime.

Khi không có target, compiler chỉ áp attribute cho tham số constructor. Công cụ này nhận ra cả hai dạng, nhưng để đổi tên property khi serialize một cách chắc chắn, hãy viết [property: JsonPropertyName("...")].

Vì sao giá trị DateTime không có Z?

DateTime với DateTimeKind.Unspecified được serialize không kèm offset. Nếu cần offset UTC tường minh, DateTimeOffset cho ra dạng +00:00.