วางโมเดล C# ที่เขียนด้วย class, record หรือ struct แล้วจะได้ตัวอย่าง JSON ตามกฎของ System.Text.Json และ Newtonsoft.Json เลือกได้ระหว่างนโยบายตั้งชื่อแบบ camelCase ซึ่งเป็นค่าเริ่มต้นของ ASP.NET Core กับการใช้ชื่อพร็อพเพอร์ตีตามที่เขียนไว้ ส่วนชื่อที่กำหนดด้วย [JsonPropertyName] หรือ [JsonProperty] จะมีผลเหนือกว่าเสมอ
ใช้เพื่อส่งตัวอย่างจากโมเดล request/response ของ Web API ให้ทีม frontend หรือพาร์ตเนอร์ภายนอก ใช้เติมตัวอย่างใน Swagger (Swashbuckle) หรือเตรียม body สำหรับ integration test ที่ใช้ HttpClient
using, namespace, constructor หรือเมธอดออกนโยบายการตั้งชื่อ: ใช้ camelCase (ค่าเริ่มต้นของ ASP.NET Core) สำหรับโปรเจกต์ Web API ทั่วไป หรือ ใช้ชื่อพร็อพเพอร์ตีตามเดิม ถ้าคุณตั้ง PropertyNamingPolicy = null หรือใช้ค่าเริ่มต้นของ Newtonsoftชนิดราก เป็น อัตโนมัติ ไทป์แรกที่ไม่มีโมเดลอื่นอ้างถึงจะเป็นราก เปลี่ยนจากรายการได้ถ้าต้องการ.http หรือ request body ของ xUnit ตัวเลือกที่เลือกไว้จะถูกบันทึกใน URLpublic 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 ไม่มี string converter จึงแสดงเป็น 0 ซึ่งเป็นค่าตัวเลขของค่าเริ่มต้น StockState.InStock
[JsonPropertyName] ของ System.Text.Json, [JsonProperty] ของ Newtonsoft และ [DataMember(Name = ...)]public บวกกับสมาชิกที่ไม่ใช่ public แต่ติด [JsonInclude] ส่วน static, const, [JsonIgnore] และ [IgnoreDataMember] จะถูกตัดออก แต่การ ignore แบบมีเงื่อนไขอย่าง Condition = WhenWritingNull ยังคงแสดงอยู่record Customer(long Id, string Name)) และการระบุเป้าหมาย [property: JsonPropertyName(...)]=> ...) ถูกรวมไว้ด้วย เหมือนที่ System.Text.Json serialize จริง= 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> เพื่อให้เอกสารกับ response ใช้คีย์ชุดเดียวกัน
สลับ นโยบายการตั้งชื่อ ไปมาบนโมเดลเดียวกันเพื่อดูล่วงหน้าว่าตัวพิมพ์ของคีย์จะเปลี่ยนอย่างไรหลังย้าย
เมื่อไคลเอนต์และเซิร์ฟเวอร์ต่างก็มีสำเนาโมเดลของตัวเอง ให้สร้าง JSON จากทั้งสองฝั่งแล้วเทียบกัน จะเห็นชื่อคีย์ที่ไม่ตรงกันได้อย่างรวดเร็ว
JsonStringEnumConverter ที่ลงทะเบียนแบบ global ด้วย AddJsonOptions ใน Program.cs มองไม่เห็นจากโค้ดโมเดล enum จึงยังออกมาเป็นตัวเลข ถ้าอยากเห็นเป็นชื่อ ให้เพิ่ม [JsonConverter(typeof(JsonStringEnumConverter))] ที่การประกาศ enum ก่อนวางstring? จะได้ค่าตัวอย่างตามไทป์ ไม่ใช่ null[JsonConverter] แบบกำหนดเองอื่นนอกจาก enum string converter, DefaultIgnoreCondition ใน JsonSerializerOptions และนโยบาย snake_case (JsonNamingPolicy.SnakeCaseLower) จะไม่ถูกนำมาใช้[JsonPolymorphic]/[JsonDerivedType] จะสร้างเฉพาะ base type ที่ประกาศไว้นโยบายการตั้งชื่อ เมื่อไร?ASP.NET Core Web API ใช้ JsonSerializerDefaults.Web ซึ่งเป็น camelCase ส่วนแอป console ที่เรียก JsonSerializer.Serialize โดยไม่ส่ง options หรือ Newtonsoft.Json ที่ใช้ค่าเริ่มต้น จะคงชื่อพร็อพเพอร์ตีไว้ กรณีนั้นให้เลือก ใช้ชื่อพร็อพเพอร์ตีตามเดิม
public string FullName => ... ถึงโผล่มา?ทั้ง System.Text.Json และ Newtonsoft.Json serialize พร็อพเพอร์ตี public ที่มี getter ดังนั้นพร็อพเพอร์ตีคำนวณก็จะอยู่ใน response ด้วย ถ้าไม่ต้องการให้ส่งออกไป ให้ใส่ [JsonIgnore]
[JsonPropertyName] บนพารามิเตอร์แบบ positional ของ record แล้วตอนรันจริงคีย์ไม่เปลี่ยนชื่อถ้าไม่ระบุเป้าหมาย คอมไพเลอร์จะใช้ attribute กับพารามิเตอร์ของ constructor เท่านั้น เครื่องมือนี้รู้จักทั้งสองแบบ แต่ถ้าต้องการให้พร็อพเพอร์ตีที่ถูก serialize เปลี่ยนชื่อแน่นอน ให้เขียน [property: JsonPropertyName("...")]
DateTime ไม่มี Z ต่อท้าย?DateTime ที่เป็น DateTimeKind.Unspecified จะถูก serialize โดยไม่มี offset ถ้าต้องการ offset UTC ที่ชัดเจน DateTimeOffset จะให้รูปแบบ +00:00