C# کلاسز کو JSON میں تبدیل کریں!

C# (class·record) کوڈ ڈالیں اور مثالی JSON حاصل کریں! System.Text.Json [JsonPropertyName], Newtonsoft.Json [JsonProperty] سپورٹ۔ API دستاویزات اور ٹیسٹ request body (sample JSON) کے لیے مفید۔
C#
نتیجہ
 

C# کلاسز کو JSON میں تبدیل کریں!

class، record یا struct سے بنے C# ماڈلز پیسٹ کریں اور System.Text.Json اور Newtonsoft.Json کے قواعد پر مبنی مثالی JSON document حاصل کریں۔ ASP.NET Core کی بطور ڈیفالٹ استعمال ہونے والی camelCase naming policy اور جیسے لکھے گئے ویسے property ناموں میں سے انتخاب کریں؛ [JsonPropertyName] یا [JsonProperty] سے رکھے گئے نام ہمیشہ جیتتے ہیں۔

اسے Web API کے request/response ماڈلز سے فرنٹ اینڈ یا بیرونی partner کو نمونہ دینے، Swagger (Swashbuckle) مثالیں بھرنے، یا HttpClient integration ٹیسٹس کے لیے bodies تیار کرنے میں استعمال کریں۔

استعمال کا طریقہ

  1. ماڈل کا source پیسٹ کریں۔ using، namespace، constructors اور methods رہ سکتے ہیں۔
  2. نام رکھنے کی پالیسی چنیں: معیاری Web API پروجیکٹس کے لیے camelCase (ASP.NET Core ڈیفالٹ)، یا اگر آپ PropertyNamingPolicy = null سیٹ کرتے ہیں یا Newtonsoft کے defaults پر چلتے ہیں تو پراپرٹی کے نام جوں کے توں۔
  3. روٹ ٹائپ کو خودکار پر رکھنے سے جس پہلی type کا کوئی دوسرا ماڈل حوالہ نہ دے وہ root بنتی ہے؛ ضرورت ہو تو فہرست سے بدلیں۔
  4. JSON کو Swagger example، .http فائل یا xUnit request body میں کاپی کریں۔ آپ کے options کے انتخاب URL میں محفوظ رہتے ہیں۔

مثال

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

camelCase policy کے تحت SKU جیسا مکمل بڑے حروف والا نام sku بنتا ہے، جو System.Text.Json کے JsonNamingPolicy.CamelCase سے میل کھاتا ہے، جبکہ [JsonPropertyName("stock_qty")] policy سے قطع نظر اپنا نام رکھتا ہے۔ WarehouseNote ([JsonIgnore]) اور private فیلڈ _version چھوڑ دیے جاتے ہیں۔ enum State پر کوئی string converter نہیں، اس لیے یہ اپنے initializer StockState.InStock کی عددی value 0 دکھاتا ہے۔

معاون خصوصیات

  • نام بدلنے والے attributes: System.Text.Json کا [JsonPropertyName]، Newtonsoft کا [JsonProperty]، اور [DataMember(Name = ...)]۔
  • صرف public properties اور فیلڈز شامل ہوتے ہیں، اور [JsonInclude] والے غیر public members بھی۔ static، const، [JsonIgnore] اور [IgnoreDataMember] خارج ہوتے ہیں؛ Condition = WhenWritingNull جیسے شرطی ignores والے رکھے جاتے ہیں۔
  • positional records (record Customer(long Id, string Name)) اور [property: JsonPropertyName(...)] targets سپورٹ ہیں۔
  • expression-bodied computed properties (=> ...) شامل ہوتی ہیں، جیسے System.Text.Json انہیں serialize کرتا۔
  • enums نمبروں کی صورت میں لکھے جاتے ہیں، جیسا System.Text.Json اور Newtonsoft بطور ڈیفالٹ کرتے ہیں (= 10 جیسی واضح values سمیت)۔ enum یا property پر [JsonConverter(typeof(JsonStringEnumConverter))] (یا Newtonsoft کا StringEnumConverter) ہو، یا members پر [JsonStringEnumMemberName] / [EnumMember(Value = ...)] ہو، تو اس کے بجائے نام والی string استعمال ہوتی ہے۔
  • تاریخیں اور IDs: 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> اندرونی type استعمال کرتے ہیں، List<T>/IEnumerable<T>/arrays کو ایک element ملتا ہے، Dictionary<int, V> میں "0" key استعمال ہوتی ہے، اور object، JsonElement اور JObject بنتے ہیں null۔
  • literal initializers (= 1.5، = "KRW") نمونہ values کے طور پر استعمال ہوتے ہیں۔

استعمال کے کیس

Swashbuckle مثالوں کو اصل responses سے ملانا

جو DTOs، [JsonPropertyName] کو ڈیفالٹ naming کے ساتھ ملاتے ہیں ان سے Swagger UI کی بنائی گئی مثالیں غلط سمجھی جانا آسان ہے۔ اس آؤٹ پٹ کو ISchemaFilter یا XML <example> comment میں استعمال کریں تاکہ docs اور response ایک جیسی keys رکھیں۔

Newtonsoft سے System.Text.Json پر منتقلی

ایک ہی ماڈل پر نام رکھنے کی پالیسی آگے پیچھے بدل کر پہلے سے دیکھ لیں کہ منتقلی کے بعد keys کا casing کیسے بدلتا ہے۔

Unity/MAUI client اور سرور کے درمیان معاہدہ جانچنا

جب client اور سرور ماڈل کی الگ الگ کاپیاں رکھتے ہوں تو key ناموں کی عدم مطابقت جلدی پکڑنے کے لیے دونوں طرف سے JSON بنا کر موازنہ کریں۔

نوٹس اور حدود

  • Program.cs میں AddJsonOptions سے global طور پر رجسٹر کیا گیا JsonStringEnumConverter ماڈل کوڈ میں نظر نہیں آتا، اس لیے enums پھر بھی نمبروں کی صورت میں آتے ہیں۔ نام دیکھنے کے لیے پیسٹ کرنے سے پہلے enum declaration پر [JsonConverter(typeof(JsonStringEnumConverter))] لگائیں۔
  • string? جیسی nullable reference types کو null نہیں بلکہ typed نمونہ ملتا ہے۔
  • enum string converter کے علاوہ custom [JsonConverter] attributes، JsonSerializerOptions کا DefaultIgnoreCondition، اور snake_case policies (JsonNamingPolicy.SnakeCaseLower) لاگو نہیں ہوتیں۔
  • [JsonPolymorphic]/[JsonDerivedType] کے ذریعے polymorphism سپورٹ نہیں؛ صرف ڈکلیئر کی گئی base type بنتی ہے۔

عام سوالات

نام رکھنے کی پالیسی کا ہر option کب استعمال کروں؟

ASP.NET Core Web API، JsonSerializerDefaults.Web استعمال کرتی ہے، جو camelCase ہے۔ options کے بغیر JsonSerializer.Serialize کال کرنے والی console ایپ، یا ڈیفالٹ Newtonsoft.Json settings، property نام برقرار رکھتی ہیں، اس لیے وہاں پراپرٹی کے نام جوں کے توں چنیں۔

public string FullName => ... جیسی computed property کیوں نظر آتی ہے؟

System.Text.Json اور Newtonsoft.Json دونوں getter والی public properties کو serialize کرتے ہیں، اس لیے computed properties بھی responses میں پہنچ جاتی ہیں۔ اگر آپ انہیں باہر نہیں بھیجنا چاہتے تو [JsonIgnore] لگائیں۔

record کے positional parameter پر [JsonPropertyName] runtime پر key کا نام نہیں بدلتا۔

target کے بغیر compiler یہ attribute صرف constructor parameter پر لگاتا ہے۔ یہ ٹول دونوں شکلیں پہچانتا ہے، لیکن serialize ہونے والی property کا نام یقینی طور پر بدلنے کے لیے [property: JsonPropertyName("...")] لکھیں۔

DateTime values پر Z کیوں نہیں ہوتا؟

DateTimeKind.Unspecified والا DateTime بغیر offset کے serialize ہوتا ہے۔ اگر آپ کو واضح UTC offset چاہیے تو DateTimeOffset، +00:00 والی شکل دیتا ہے۔