الصق نماذج C# المبنية بـ class أو record أو struct لتحصل على مستند JSON نموذجي يتبع قواعد System.Text.Json وNewtonsoft.Json. اختر بين سياسة التسمية camelCase التي يعتمدها ASP.NET Core افتراضيًا وبين أسماء الخصائص كما كُتبت؛ وتبقى الأسماء المحددة عبر [JsonPropertyName] أو [JsonProperty] هي الغالبة دائمًا.
استخدمه لتسليم عيّنة من نماذج طلبات واستجابات Web API إلى فريق الواجهة الأمامية أو إلى شريك خارجي، أو لملء أمثلة Swagger (Swashbuckle)، أو لتجهيز أجسام الطلبات لاختبارات التكامل باستخدام HttpClient.
using وnamespace والـ constructors والدوال.سياسة التسمية: camelCase (الافتراضي في ASP.NET Core) لمشاريع Web API القياسية، أو أسماء الخصائص كما هي إن كنت تضبط PropertyNamingPolicy = null أو تعتمد على إعدادات Newtonsoft الافتراضية.النوع الجذري على تلقائي، يصبح أول نوع لا يشير إليه أي نموذج آخر هو الجذر؛ وغيّره من القائمة عند الحاجة..http أو جسم طلب في xUnit. تُحفظ اختياراتك في الرابط.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 }{
"id": "00000000-0000-0000-0000-000000000000",
"sku": "",
"stock_qty": 0,
"state": 0,
"updatedAt": "1970-01-01T00:00:00+00:00",
"barcodes": [
""
]
}مع سياسة camelCase يصبح الاسم المكتوب بأحرف كبيرة بالكامل مثل SKU على شكل sku، تمامًا كما في JsonNamingPolicy.CamelCase الخاصة بـ System.Text.Json، بينما يحتفظ [JsonPropertyName("stock_qty")] باسمه أيًّا كانت السياسة. يُستبعد WarehouseNote ([JsonIgnore]) والحقل private المسمّى _version. ولا يملك الـ enum المسمّى State محوّلًا نصيًا، فيظهر 0، وهي القيمة الرقمية لقيمته الابتدائية StockState.InStock.
[JsonPropertyName] في System.Text.Json، و[JsonProperty] في Newtonsoft، و[DataMember(Name = ...)].public، إضافة إلى الأعضاء غير العامة المعلَّمة بـ [JsonInclude]. تُستبعد static وconst و[JsonIgnore] و[IgnoreDataMember]؛ أما التجاهل المشروط مثل Condition = WhenWritingNull فيُبقي الحقل.record Customer(long Id, string Name)) وأهداف [property: JsonPropertyName(...)].=> ...)، كما كان System.Text.Json سيُسلسِلها.= 10). ومع [JsonConverter(typeof(JsonStringEnumConverter))] (أو StringEnumConverter في Newtonsoft) على الـ enum أو الخاصية، أو [JsonStringEnumMemberName] / [EnumMember(Value = ...)] على الأعضاء، يُستخدم الاسم كسلسلة نصية بدلًا من ذلك.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 كله أصفار.int?/Nullable<T> تستخدم النوع الداخلي، وList<T>/IEnumerable<T>/المصفوفات تحصل على عنصر واحد، وDictionary<int, V> يستخدم المفتاح "0"، أما object وJsonElement وJObject فتصبح null.= 1.5، = "KRW") قيمًا نموذجية.كائنات DTO التي تخلط [JsonPropertyName] مع التسمية الافتراضية تجعل الأمثلة التي يولّدها Swagger UI عرضة لسوء الفهم. استخدم هذا الناتج في ISchemaFilter أو في تعليق XML من نوع <example> حتى تتشارك الوثائق والاستجابة المفاتيح نفسها.
بدّل سياسة التسمية ذهابًا وإيابًا على النموذج نفسه لتعاين كيف تتغير حالة أحرف المفاتيح بعد الترحيل.
عندما يحتفظ العميل والخادم بنسختين منفصلتين من النموذج، ولّد JSON من كل جانب وقارن بينهما لتكتشف اختلاف أسماء المفاتيح بسرعة.
JsonStringEnumConverter المسجَّل عامًّا عبر AddJsonOptions في Program.cs غير مرئي في كود النموذج، لذا تظل الـ enums تظهر كأرقام. لرؤية الأسماء، أضف [JsonConverter(typeof(JsonStringEnumConverter))] إلى تعريف الـ enum قبل اللصق.string? تحصل على عيّنة من نوعها لا على null.[JsonConverter] المخصصة غير محوّل الـ enum النصي، ولا DefaultIgnoreCondition في JsonSerializerOptions، ولا سياسات snake_case (JsonNamingPolicy.SnakeCaseLower).[JsonPolymorphic]/[JsonDerivedType] غير مدعوم؛ ولا يُولَّد إلا النوع الأساسي المُعلَن.سياسة التسمية؟يستخدم ASP.NET Core Web API الإعداد JsonSerializerDefaults.Web، وهو camelCase. أما تطبيق console يستدعي JsonSerializer.Serialize دون خيارات، أو إعدادات Newtonsoft.Json الافتراضية، فيُبقي أسماء الخصائص كما هي، لذا اختر هناك أسماء الخصائص كما هي.
public string FullName => ...؟يُسلسِل كلٌّ من System.Text.Json وNewtonsoft.Json الخصائص العامة التي لها getter، لذا تنتهي الخصائص المحسوبة في الاستجابات هي الأخرى. أضف [JsonIgnore] إن لم ترد تصديرها.
[JsonPropertyName] على المعامل الموضعي في record لا يغيّر اسم المفتاح وقت التشغيل.دون تحديد هدف، يطبّق المترجم السمة على معامل الـ constructor فقط. تتعرّف هذه الأداة على الصيغتين، لكن لإعادة تسمية الخاصية المُسلسَلة بشكل موثوق اكتب [property: JsonPropertyName("...")].
Z في قيم DateTime؟الـ DateTime ذو DateTimeKind.Unspecified يُسلسَل دون إزاحة. إن كنت تحتاج إلى إزاحة UTC صريحة، فإن DateTimeOffset يُنتج الصيغة +00:00.