أوضاع POCO وRecord والتعليقات
تُعدّ Plain Old CLR Objects أو POCOs المخرجات الأكثر مرونة في C#: خصائص عامة مع وصول { get; set; } ومُنشئ بدون معاملات وتوافق كامل مع System.Text.Json وNewtonsoft.Json. هذه المخرجات الافتراضية وتعمل عبر جميع إصدارات .NET.
تقدّم records في C# 9+ بديلًا مختصرًا لكائنات نقل البيانات غير القابلة للتغيير. يولّد تصريح record الموضعي تلقائيًا مُنشئًا أساسيًا وخصائص init-only ومساواة هيكلية وطريقة deconstruct. مثالية لنماذج استجابات API وكائنات قيمة النطاق.
يضيف وضع التعليق [JsonPropertyName("key")] من System.Text.Json أو [JsonProperty("key")] من Newtonsoft.Json لكل خاصية حتى تُعيَّن أسماء الخصائص بصيغة PascalCase في C# بشكل صحيح إلى مفاتيح JSON بصيغة camelCase. تُنتَج أنواع المراجع القابلة للقيمة الفارغة (string? وT?) عندما يغيب حقل في بعض الكائنات.
تعيين الأنواع واصطلاحات التسمية
سلاسل JSON تُحوَّل إلى string والأعداد الصحيحة إلى int (أو long للقيم الكبيرة) والكسور العشرية إلى double والقيم المنطقية إلى bool والحقول الفارغة فقط إلى object? والمصفوفات إلى List<T>. تولّد الكائنات المتداخلة أصنافها المسمّاة الخاصة.
تُحوَّل مفاتيح JSON تلقائيًا إلى أسماء خصائص PascalCase في C# وفق إرشادات Microsoft: مفاتيح camelCase مثل "firstName" تصبح "FirstName" ومفاتيح snake_case مثل "first_name" كذلك ومفاتيح kebab-case مثل "first-name" أيضًا. يُحفَظ المفتاح الأصلي في سمة [JsonPropertyName].
تصريح الفضاء الاسمي هو "MyApp.Models" افتراضيًا لكنه قابل للتهيئة. تُضاف توجيهة using لـ System.Collections.Generic عند وجود خصائص List<T>. المخرجات ملف .cs واحد يحتوي على جميع الأصناف بترتيب التبعيات.
سير عمل تطوير .NET
أكثر مسارات العمل شيوعًا هو نمذجة REST API تابعة لجهة خارجية. الصق استجابة JSON نموذجية واختر وضع تعليق System.Text.Json وأدرج الملف المولّد في مشروعك. الأصناف قابلة للاستخدام فورًا مع HttpClient.GetFromJsonAsync<T>().
تستفيد مشاريع ASP.NET Core Web API من نماذج طلب واستجابة مكتوبة بالأنواع بشكل جيد. يولّد المحوّل أصنافًا تعمل مباشرةً كمعاملات إجراء المتحكم ([FromBody]) وأنواع الإرجاع.
تبدأ ترحيلات Entity Framework Core من أصناف كيان C#. وإن كان المولّد لا يستطيع إضافة سمات EF تلقائيًا فإن مخرجات POCO توفّر نقطة بداية متينة يمكنك تزيينها بـ [Table] و[Key] وخصائص التنقل.