Tukar kelas C# kepada JSON!

Tampal kod C# (class·record) dan dapatkan contoh JSON! Menyokong System.Text.Json [JsonPropertyName], Newtonsoft.Json [JsonProperty]. Berguna untuk dokumentasi API dan badan permintaan ujian (mock request body).
C#
Hasil
 

Tukar kelas C# kepada JSON!

Tampal model C# yang dibina daripada class, record atau struct dan dapatkan contoh dokumen JSON yang mengikut peraturan System.Text.Json dan Newtonsoft.Json. Pilih antara dasar penamaan camelCase yang digunakan ASP.NET Core secara lalai atau nama property seperti yang ditulis; nama yang ditetapkan dengan [JsonPropertyName] atau [JsonProperty] sentiasa diutamakan.

Gunakannya untuk memberi sampel kepada pasukan frontend atau rakan kongsi luar berdasarkan model request/response Web API, untuk mengisi contoh Swagger (Swashbuckle), atau untuk menyediakan body bagi ujian integrasi HttpClient.

Cara menggunakan

  1. Tampal kod sumber model. using, namespace, constructor dan method boleh dibiarkan.
  2. Pilih Dasar penamaan: camelCase (lalai ASP.NET Core) untuk projek Web API biasa, atau Nama sifat seperti asal jika anda menetapkan PropertyNamingPolicy = null atau bergantung pada tetapan lalai Newtonsoft.
  3. Apabila Jenis akar ialah Automatik, jenis pertama yang tidak dirujuk oleh model lain menjadi akar; tukar daripada senarai jika perlu.
  4. Salin JSON ke dalam contoh Swagger, fail .http atau body request xUnit. Pilihan opsyen anda disimpan dalam URL.

Contoh

Input (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 }
Output (JSON · camelCase)
{
  "id": "00000000-0000-0000-0000-000000000000",
  "sku": "",
  "stock_qty": 0,
  "state": 0,
  "updatedAt": "1970-01-01T00:00:00+00:00",
  "barcodes": [
    ""
  ]
}

Di bawah dasar camelCase, nama huruf besar semua seperti SKU menjadi sku, sama seperti JsonNamingPolicy.CamelCase dalam System.Text.Json, manakala [JsonPropertyName("stock_qty")] mengekalkan namanya tanpa mengira dasar. WarehouseNote ([JsonIgnore]) dan field private _version tidak dimasukkan. Enum State tiada string converter, jadi ia memaparkan 0, iaitu nilai nombor bagi initializer StockState.InStock.

Ciri yang disokong

  • Attribute penamaan semula: [JsonPropertyName] System.Text.Json, [JsonProperty] Newtonsoft dan [DataMember(Name = ...)].
  • Hanya property dan field public dimasukkan, serta ahli bukan public yang ditanda [JsonInclude]. static, const, [JsonIgnore] dan [IgnoreDataMember] dikecualikan; ignore bersyarat seperti Condition = WhenWritingNull dikekalkan.
  • Positional record (record Customer(long Id, string Name)) dan sasaran [property: JsonPropertyName(...)] disokong.
  • Computed property berbentuk expression-bodied (=> ...) dimasukkan, sama seperti System.Text.Json akan men-serialize-kannya.
  • Enum ditulis sebagai nombor, seperti tingkah laku lalai System.Text.Json dan Newtonsoft (termasuk nilai eksplisit seperti = 10). Dengan [JsonConverter(typeof(JsonStringEnumConverter))] (atau StringEnumConverter Newtonsoft) pada enum atau property, atau [JsonStringEnumMemberName] / [EnumMember(Value = ...)] pada ahli, string nama digunakan.
  • Tarikh dan 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 yang semuanya sifar.
  • int?/Nullable<T> menggunakan jenis dalamannya, List<T>/IEnumerable<T>/array mendapat satu elemen, Dictionary<int, V> menggunakan kunci "0", dan object, JsonElement serta JObject menjadi null.
  • Initializer literal (= 1.5, = "KRW") digunakan sebagai nilai sampel.

Kes penggunaan

Menyelaraskan contoh Swashbuckle dengan response sebenar

DTO yang mencampurkan [JsonPropertyName] dengan penamaan lalai menyebabkan contoh yang dijana Swagger UI mudah disalah baca. Gunakan output ini dalam ISchemaFilter atau komen XML <example> supaya dokumentasi dan response berkongsi kunci yang sama.

Berpindah daripada Newtonsoft ke System.Text.Json

Tukar Dasar penamaan berulang kali pada model yang sama untuk melihat bagaimana huruf besar kecil kunci berubah selepas migrasi.

Menyemak kontrak antara klien Unity/MAUI dan server

Apabila klien dan server menyimpan salinan model masing-masing, jana JSON daripada setiap pihak dan bandingkan untuk mengesan nama kunci yang tidak sepadan dengan cepat.

Nota dan had

  • JsonStringEnumConverter yang didaftarkan secara global dengan AddJsonOptions dalam Program.cs tidak kelihatan dalam kod model, jadi enum tetap keluar sebagai nombor. Untuk melihat nama, tambah [JsonConverter(typeof(JsonStringEnumConverter))] pada deklarasi enum sebelum menampal.
  • Jenis rujukan nullable seperti string? mendapat sampel mengikut jenisnya, bukan null.
  • Attribute [JsonConverter] tersuai selain string converter untuk enum, DefaultIgnoreCondition dalam JsonSerializerOptions, dan dasar snake_case (JsonNamingPolicy.SnakeCaseLower) tidak digunakan.
  • Polimorfisme melalui [JsonPolymorphic]/[JsonDerivedType] tidak disokong; hanya jenis asas yang diisytiharkan akan dijana.

Soalan lazim

Bilakah saya patut menggunakan setiap pilihan Dasar penamaan?

ASP.NET Core Web API menggunakan JsonSerializerDefaults.Web, iaitu camelCase. Aplikasi console yang memanggil JsonSerializer.Serialize tanpa opsyen, atau tetapan lalai Newtonsoft.Json, mengekalkan nama property, jadi pilih Nama sifat seperti asal dalam kes itu.

Kenapa computed property seperti public string FullName => ... turut muncul?

System.Text.Json dan Newtonsoft.Json kedua-duanya men-serialize-kan property public yang mempunyai getter, jadi computed property juga akan masuk ke dalam response. Tambah [JsonIgnore] jika anda tidak mahu ia dieksport.

[JsonPropertyName] pada parameter positional record tidak menukar nama kunci semasa runtime.

Tanpa sasaran, compiler hanya menggunakan attribute itu pada parameter constructor. Alat ini mengenali kedua-dua bentuk, tetapi untuk menukar nama property yang di-serialize dengan pasti, tulis [property: JsonPropertyName("...")].

Kenapa tiada Z pada nilai DateTime?

DateTime dengan DateTimeKind.Unspecified di-serialize tanpa offset. Jika anda memerlukan offset UTC yang eksplisit, DateTimeOffset menghasilkan bentuk +00:00.