實用指南

JSON 轉 C# 類別產生器 — 使用指南與技術原理

將 JSON 資料即時轉換為強型別 C# 類別,支援 JsonPropertyName 特性、可空參考以及優雅的 取得/設定 程式碼。

開啟工具

概覽

REST API、雲端事件、設定與遙測資料都以 JSON 為主要格式。將樣本轉為強型別 C# 類別能帶來編譯期安全、清楚的 IntelliSense、容易維護的領域模型,以及更穩定的重構體驗。透過 JsonPropertyName 保留原始鍵名,也能在跨團隊協作時快速交付一致的資料契約。

核心概念

JSON → C# 型別對應

字串轉成 字串 或 DateTime(符合 ISO-8601 時),整數對應 long,帶小數的數值對應 double,布林對應 bool,物件拆成專屬類別,陣列生成 清單<T>。偵測到 null 就標記為可空欄位,若啟用 可為空 參考便自動加上 ?,混合陣列則降級為 清單<object> 以完整描述載荷。

類別建置流程

解析器遞迴掃描 JSON,為每一種物件形狀建立可重用的簽名。屬性名稱統一轉成 PascalCase 並避開 C# 保留字;結構相同的物件共用一份類別,陣列也重用推論出的元素型別。工具還會輸出類別數、屬性數與陣列數,方便快速掌握資料模型的複雜度。

JsonPropertyName 與序列化

系統.文字.Json 依 JsonPropertyName 對應欄位,因此生成程式碼時可選擇保留每個 JSON 鍵。如此一來 snake_case 內容仍可透過 PascalCase 屬性操作。由於輸出為 partial class,你能在自己的檔案裡加入驗證、轉換器或領域註解,而不用修改生成檔。

可空參考策略

啟用 可為空 後,只要樣本出現 null,不論是 bool、long、double 等值型別,或 字串、清單<T>、巢狀類別等參考型別都會自動加上 ?。這符合 C# 8 之後的最佳實務,讓編譯器在接近可空欄位時即時警示,避免執行階段 NullReferenceException。

功能亮點

強型別輸出

智慧推斷 C# 型別、建立巢狀類別並維持 PascalCase 規範,同時保留原始 JSON 鍵名。

JsonPropertyName 支援

可選擇為屬性輸出 JsonPropertyName,確保 snake_case 內容能正確反序列化。

可空感知

樣本出現 null 時自動加上 ?,讓可空參考在編譯期就能被追蹤。

即時統計

顯示類別、屬性與陣列數,快速掌握資料模型的規模與複雜度。

常見問題

什麼是 JSON 到 C# 類別產生,為什麼它有用?

JSON 到 C# 類別產生可以從 JSON 資料結構自動建立強型別 C# 類別。這在處理 .NET 應用程式中的 API、設定檔或資料序列化時至關重要。產生器建立具有正確型別、可空支援和 JsonPropertyName 屬性的適當 C# 類別,而不是手動編寫類別或使用動態型別,從而節省數小時的開發時間並減少錯誤。

產生器如何處理不同的 JSON 資料型別?

產生器將 JSON 型別對應到適當的 C# 型別:字串變為 字串 或 DateTime(對於 ISO-8601 日期),整數對應到 long,浮點數對應到 double,布林值對應到 bool,物件變為專用類別,陣列變為 清單<T>。空值將屬性標記為可空(啟用可空引用時帶有 ? 後綴)。混合陣列使用 清單<object> 來保留異構資料。

什麼是 JsonPropertyName 屬性,何時應該使用它們?

JsonPropertyName 屬性允許 C# 屬性使用 PascalCase 命名(C# 慣例),而 JSON 使用不同的命名(如 snake_case 或 camelCase)。該屬性在序列化/反序列化期間保留原始 JSON 鍵名。當您的 JSON 使用非 PascalCase 鍵但您希望在程式碼中使用慣用的 C# 屬性名時,請啟用此選項。

什麼是可空引用支援,為什麼要啟用它?

可空引用型別(C# 8.0+)在引用型別可以為 null 時新增 ?,啟用編譯時 null 檢查。啟用後,當 JSON 樣本包含 null 值時,產生器會在屬性後附加 ?。這有助於防止 NullReferenceException 錯誤,使可選欄位顯式,並遵循現代 C# 的 null 安全最佳實踐。

產生後我可以修改產生的類別嗎?

可以,產生器預設建立部分類別(或啟用時),允許您在單獨的檔案中擴展它們而無需修改產生的程式碼。您可以新增自訂方法、驗證邏輯、特定領域的屬性或實作介面。這種分離保持產生的程式碼整潔,並在 JSON 結構變更時安全地重新產生類別。

相關文件

JSON 轉 C# 類別產生器

返回工具頁面,立即使用相關功能。

開啟工具