حوّل JSON إلى class بلغة C#!

أدخل JSON لتوليد كود class بلغة C# بما في ذلك الكائنات المتداخلة! يدعم System.Text.Json [JsonPropertyName], .NET, ASP.NET Core.
JSON
النتيجة
 

حوّل JSON إلى class بلغة C#!

حوّل JSON إلى أصناف C# لـ System.Text.Json. تُحوَّل أسماء الخصائص إلى PascalCase، وتحمل كل خاصية سمة [JsonPropertyName] لترتبط بالمفتاح الأصلي تمامًا.

يوفّر عليك عناء النسخ والكتابة اليدوية لنماذج الطلبات والاستجابات في ASP.NET Core، ولأنواع استدعاءات HttpClient.GetFromJsonAsync<T>() إلى الـ APIs الخارجية، ولأصناف البيانات في تطبيقات Unity أو MAUI.

طريقة الاستخدام

  1. الصق استجابة JSON أو ملف إعدادات.
  2. أدخل اسم الصنف الجذري في اسم النوع (مثلًا PaymentResult).
  3. ضع الأصناف المولَّدة في ملف .cs وأضف الـ namespace الخاص بك.
  4. استخدمها مع JsonSerializer.Deserialize<PaymentResult>(json) أو GetFromJsonAsync<PaymentResult>(url).

مثال

المدخلات (JSON)
{
  "paymentId": "pay_8f2k",
  "amount": 15000,
  "currency": "KRW",
  "approved": true,
  "approvedAt": "2024-05-01T12:30:00Z",
  "card": { "issuer": "VISA", "last4": "4242" },
  "metadata": null
}
المخرجات (C# · System.Text.Json)
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;

public class PaymentResult
{
    [JsonPropertyName("paymentId")]
    public string PaymentId { get; set; } = string.Empty;

    [JsonPropertyName("amount")]
    public int Amount { get; set; }

    [JsonPropertyName("currency")]
    public string Currency { get; set; } = string.Empty;

    [JsonPropertyName("approved")]
    public bool Approved { get; set; }

    [JsonPropertyName("approvedAt")]
    public string ApprovedAt { get; set; } = string.Empty;

    [JsonPropertyName("card")]
    public Card Card { get; set; } = new();

    [JsonPropertyName("metadata")]
    public JsonElement? Metadata { get; set; }
}

public class Card
{
    [JsonPropertyName("issuer")]
    public string Issuer { get; set; } = string.Empty;

    [JsonPropertyName("last4")]
    public string Last4 { get; set; } = string.Empty;
}

لكل خاصية [JsonPropertyName]، فيتطابق paymentId ↔ PaymentId بغض النظر عن قواعد حالة الأحرف. قيمة metadata دائمًا null، فنوعها مجهول وتصبح JsonElement?. وتحصل الخصائص النصية والكائنية على القيم الابتدائية string.Empty / new() كي يُترجَم الكود دون تحذيرات nullable.

الميزات المدعومة

  • [JsonPropertyName("originalKey")] على كل خاصية، مع using System.Text.Json.Serialization;.
  • الأنواع: string، وint، وlong للأعداد الصحيحة التي تتجاوز 32 بت، وdouble للأعداد العشرية، وbool، وList<T> للمصفوفات.
  • القيم ذات الأنواع المختلطة أو المجهولة تصبح JsonElement، مع إضافة using System.Text.Json;.
  • الخصائص الغائبة في بعض العناصر أو التي تحوي null تصبح قابلة لـ null (int?، string?).
  • تحصل الخصائص المطلوبة على القيم الابتدائية = string.Empty; أو = new(); لتجنّب تحذير مراجع nullable CS8618.
  • لا تسمح C# بخاصية تحمل اسم صنفها نفسه، لذا تحصل على اللاحقة Value (مثل RootValue).
  • المصفوفة على المستوى الأعلى تُنتج تعليقًا // Root: List<RootItem> وصنف العنصر.

حالات الاستخدام

استدعاء APIs خارجية عبر HttpClient

حوّل استجابة نموذجية من API للدفع أو تتبّع الشحنات واستخدمها نوعًا في await http.GetFromJsonAsync<PaymentResult>(url)، بدلًا من استخراج الحقول واحدًا تلو الآخر من JsonDocument.

نماذج payload الـ webhooks في ASP.NET Core

ولّد أصنافًا من الـ payload الذي ترسله إليك خدمة خارجية واستقبلها كمعامل [FromBody]، فيعمل ربط النماذج والتحقق كالمعتاد.

ملفات appsettings وبيانات الألعاب

تثبيت بنية ملف بيانات JSON يقرؤه تطبيق Unity أو تطبيق console في أصناف يعني أن أي تغيير في ملف البيانات يظهر فورًا كخطأ في فك التسلسل.

ملاحظات وقيود

  • لا يُولَّد ناتج لـ Newtonsoft.Json ([JsonProperty]). إن كنت تستخدم Json.NET، فبدّل السمات إلى [JsonProperty("key")].
  • تبقى سلاسل التاريخ string. لقيم ISO 8601 يكفي تغيير النوع إلى DateTime أو DateTimeOffset ليحلّلها System.Text.Json.
  • تفترض new() المستهدفة النوع وstring? وجود C# 9+ مع تفعيل سياق nullable (الافتراضي منذ .NET 6).
  • لا يُولَّد record ولا required. للنماذج غير القابلة للتغيير، غيّر { get; set; } إلى { get; init; }.
  • تأتي كل الأصناف في كتلة واحدة؛ قسّم الملفات والـ namespaces بنفسك.

الأسئلة الشائعة

لماذا تُضاف [JsonPropertyName] حتى لو كان المفتاح مطابقًا أصلًا؟

يميّز System.Text.Json حالة الأحرف افتراضيًا. في مشاريع console أو worker دون JsonSerializerOptions مخصصة، لن يرتبط paymentId بـ PaymentId، لذا تُكتب السمة دائمًا لتعمل أيًّا كانت الإعدادات.

كيف أقرأ خاصية من نوع JsonElement?؟

تحقق من ValueKind، ثم استخدم GetString() أو GetInt32() أو Deserialize<T>(). وما إن تعرف النوع الحقيقي، فاستبدال JsonElement به هو الخيار الأنظف.

هل يمكنني إبقاء أسماء الخصائص بصيغة camelCase؟

يتبع الناتج اصطلاح PascalCase في C#. المفتاح الأصلي موجود في [JsonPropertyName]، لذا يمكنك إعادة تسمية الخصائص بحرية ما دامت السمة باقية.

هل يعمل مع JsonUtility في Unity؟

لا يتعامل JsonUtility إلا مع الحقول العامة في أصناف [Serializable]، لا مع الخصائص، ويتجاهل [JsonPropertyName]. في Unity استخدم الناتج مع حزمة Newtonsoft.Json أو مع System.Text.Json بدلًا من ذلك.