共用方式為

System.Text.Json 中的反映與來源產生

  • 發行項

本文說明反映與來源產生之間的差異，因為其與 System.Text.Json 序列化有關。 其也提供如何為您的案例選擇最佳方法的指引。

中繼資料集合

若要序列化或還原序列化型別，JsonSerializer 需要如何存取型別成員的相關資訊。 JsonSerializer 需要下列資訊：

  • 如何存取屬性 getter 和用於序列化的欄位。
  • 如何存取建構函式、屬性 setter 和用於還原序列化的欄位。
  • 關於哪些屬性已用來自訂序列化或還原序列化的資訊。
  • 來自 JsonSerializerOptions 的執行階段設定。

這項資訊稱為「中繼資料」。

反映

JsonSerializer 預設使用 反映，在執行階段收集中繼資料。 當 JsonSerializer 第一次必須序列化或還原序列化型別時，它會收集並快取此中繼資料。 中繼資料收集流程需要一段時間並使用記憶體。

來源產生

作為替代方式，System.Text.Json 也可以使用 C# 來源產生功能來改善效能、減少私人記憶體用量，以及輔助組件調整，以降低應用程式大小。 此外，特定反映 API 不能用於原生 AOT 應用程式，因此您必須對這些應用程式使用來源產生。

來源產生可用於兩種模式：

  • 中繼資料型模式

    在編譯期間，System.Text.Json 會收集序列化所需的資訊，並產生原始程式碼檔案，以填入所要求類型的 JSON 合約中繼資料。

  • 序列化最佳化 (快速路徑) 模式

    JsonSerializer 自訂序列化輸出的功能 (例如命名原則和參考保留) 會帶來效能額外負荷。 在序列化 - 最佳化模式中，System.Text.Json 會產生直接使用 Utf8JsonWriter 的最佳化序列化程序碼。 此最佳化或「快速路徑」程式碼會增加序列化輸送量。

    目前無法使用快速路徑「還原串行化」。 如需詳細資訊，請參閱 dotnet/執行階段問題 55043。

System.Text.Json 的來源產生需要 C# 9.0 或更新版本。

功能比較

根據每個模式提供的下列優點，選擇反映或來源產生模式：

優點 反映 來源產生
(中繼資料型模式)		 來源產生
(序列化-最佳化模式)
編碼更簡單。 ✔️ ❌ ❌
偵錯更簡單。 ❌ ✔️ ✔️
支援非公用成員。 ✔️ ✔️* ✔️*
支援所有可用的序列化自訂。 ✔️ ❌† ❌†
減少啟動時間。 ❌ ✔️ ✔️
減少私人記憶體使用量。 ❌ ✔️ ✔️
消除執行階段反映。 ❌ ✔️ ✔️
促進修剪安全的應用程式大小縮減。 ❌ ✔️ ✔️
增加序列化輸送量。 ❌ ❌ ✔️

* 來源產生器支援一些非公用成員，例如相同組件中的內部類型。 † 使用合約自訂 API 可以修改來源產生的合約。

優點 反映 來源產生
(中繼資料型模式)		 來源產生
(序列化-最佳化模式)
編碼更簡單。 ✔️ ❌ ❌
偵錯更簡單。 ❌ ❌ ✔️
支援非公用存取子。 ✔️ ❌ ❌
支援必要的屬性。 ✔️ ❌ ❌
支援僅限 init 的屬性。 ✔️ ❌ ❌
減少啟動時間。 ❌ ✔️ ✔️
減少私人記憶體使用量。 ❌ ✔️ ✔️
消除執行階段反映。 ❌ ✔️ ✔️
促進修剪安全的應用程式大小縮減。 ❌ ✔️ ✔️
增加序列化輸送量。 ❌ ❌ ✔️