JSON إلى كلاس C#

ما هو تحويل JSON إلى C#؟

تحويل JSON إلى C# هو عملية توليد تعريفات كلاسات C# ذات أنواع محددة من بيانات JSON. عندما يتلقى تطبيق .NET بيانات JSON من واجهة API أو ملف إعداد أو طابور رسائل، يحتاج إلى كلاسات C# لإلغاء تسلسل تلك البيانات إلى كائنات. كتابة هذه الكلاسات يدويًا أمر مضنٍ وعرضة للأخطاء، لا سيما عندما يحتوي JSON على كائنات متداخلة ومصفوفات وأنواع مختلطة.

يفحص مولّد كلاسات JSON إلى C# البنية والقيم في JSON، ويستنتج نوع C# المناسب لكل حقل، وينتج تعريفات الكلاسات مع مُحصِّلات الخصائص وضوابطها وسمات التسلسل. تتبع المخرجات اتفاقيات تسمية .NET: أسماء الخصائص بصيغة PascalCase، وسمات JsonPropertyName لربطها بمفاتيح JSON الأصلية بصيغة camelCase أو snake_case، والاستخدام الصحيح لـ List'<'T'>' للمصفوفات.

هذا التحويل شائع بشكل خاص في واجهات ASP.NET Core البرمجية وAzure Functions وأي خدمة .NET تستهلك بيانات JSON خارجية. بدلًا من استخدام dynamic أو Dictionary'<'string, object'>'، تمنحك الكلاسات ذات الأنواع المحددة السلامة في وقت التصريف ودعم IntelliSense والحماية من الأخطاء الإملائية في أسماء الحقول التي لن تظهر عادةً إلا في وقت التشغيل. الصق JSON في هذه الأداة واحصل على كلاسات C# جاهزة للاستخدام فورًا.

لماذا تستخدم مولّد JSON إلى C#؟

كتابة كلاسات نماذج C# يدويًا من عينات JSON تستغرق وقتًا وتُدخل أخطاء بشرية. يتولى المولّد الأجزاء المتكررة حتى تتفرغ للمنطق التجاري.

حالات استخدام تحويل JSON إلى C#

مرجع تعيين أنواع JSON إلى C#

كل نوع قيمة JSON يتعيّن إلى نوع C# محدد. يحلل المولّد القيم الفعلية لاختيار النوع الأدق. فمثلًا، رقم JSON بلا فاصلة عشرية يصبح int، بينما 3.14 يصبح double. تُنتج قيم null النوع object? (نوع مرجعي قابل للإلغاء) لأن النوع الفعلي لا يمكن استنتاجه من null وحده.

System.Text.Json مقابل Newtonsoft.Json

يوفر .NET مكتبتين رئيسيتين لتسلسل JSON. تستخدم الكلاسات المولّدة من هذه الأداة سمات System.Text.Json (JsonPropertyName)، وهو الخيار المدمج منذ .NET Core 3.0. إذا كان مشروعك يستخدم Newtonsoft.Json، يمكنك استبدال السمات.

أمثلة برمجية

توضح هذه الأمثلة كيفية تعريف كلاسات C# المولّدة من JSON واستخدامها، بالاستعانة بكلتا مكتبتي التسلسل الرئيسيتين، إضافةً إلى كيفية أتمتة التوليد من سطر الأوامر.

using System.Text.Json;

var json = """{"id": 1, "name": "Alice", "active": true}""";
var user = JsonSerializer.Deserialize<User>(json);
Console.WriteLine(user.Name); // → "Alice"

public class User
{
    [JsonPropertyName("id")]
    public int Id { get; set; }

    [JsonPropertyName("name")]
    public string Name { get; set; }

    [JsonPropertyName("active")]
    public bool Active { get; set; }
}

using Newtonsoft.Json;

var json = @"{""id"": 1, ""name"": ""Alice"", ""scores"": [98, 85]}";
var user = JsonConvert.DeserializeObject<User>(json);
Console.WriteLine(user.Scores[0]); // → 98

public class User
{
    [JsonProperty("id")]
    public int Id { get; set; }

    [JsonProperty("name")]
    public string Name { get; set; }

    [JsonProperty("scores")]
    public List<int> Scores { get; set; }
}

// Install: npm install -g quicktype
// Generate C# classes from JSON:
// quicktype --lang csharp --src data.json --out Models.cs

// From stdin:
// echo '{"id": 1, "name": "Alice"}' | quicktype --lang csharp

// Output:
// public class Root
// {
//     [JsonPropertyName("id")]
//     public int Id { get; set; }
//
//     [JsonPropertyName("name")]
//     public string Name { get; set; }
// }

import json

def json_to_csharp(data: dict, class_name: str = "Root") -> str:
    lines = [f"public class {class_name}", "{"]
    type_map = {str: "string", int: "int", float: "double", bool: "bool"}

    for key, value in data.items():
        cs_type = type_map.get(type(value), "object")
        prop = key[0].upper() + key[1:]  # PascalCase
        lines.append(f'    [JsonPropertyName("{key}")]')
        lines.append(f'    public {cs_type} {prop} {{ get; set; }}')
        lines.append('')
    lines.append("}")
    return "\n".join(lines)

data = json.loads('{"id": 1, "name": "Alice", "active": true}')
print(json_to_csharp(data))

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