System.Text.Json 中的來源產生模式

來源產生可用於兩種模式： 元數據型 和 串行化優化。 本文說明不同的模式。

如需瞭解如何使用源生成模式的資訊，請參閱在 System.Text.Json 中使用源生成的方式。

中繼資料型模式

你可以利用原始碼產生，將中繼資料收集流程從執行時移到編譯時。 在編譯期間，會收集中繼資料，並產生原始程式碼檔案。 產生的原始程式碼檔案會自動編譯為應用程式不可或缺的一部分。 此技術省去執行時的元資料收集，提升序列化與反序列化的效能。

源碼生成所帶來的效能提升可以是非常顯著的。 例如，測試結果已顯示減少高達 40% 或以上的啟動時間、減少私人記憶體、增加輸送量速度 (在序列化最佳化模式下)，以及縮減應用程式大小。

非私人會員與製造商

根據預設，反射模式和原始碼產生模式在序列化合約中都僅包含 public 屬性和欄位。

從 .NET 11 開始，原始碼產生支援你用 [JsonInclude] 屬性明確標記的成員。 該成員可以是 private、 、 internal或 protected。 它也支援以 internal 標記的屬性上的 private、protected 和 [JsonInclude] 存取子。 原始碼產生也支援標記為 [JsonConstructor] 的不可存取建構器。

在 .NET 11 中，產生的存取器使用 UnsafeAccessorAttribute。

僅限 init 的屬性，其原始碼產生的 setter 只有在 JSON 承載資料包含該屬性時才會執行。 payload 省略的僅限 init 的屬性，會保留其屬性初始設定式中的值。

在 .NET 10 及更早版本中，原始碼產生有以下限制：

• 原始碼產生不支援 private 或 protected 成員或存取子。 如果你將這樣的成員標記為 [JsonInclude]，序列化器會在執行時拋出 a NotSupportedException 。
• 原始碼產生僅支援 internal 成員和存取子，前提是它們可供在相同組件中產生的 JsonSerializerContext 存取。
• Source 產生不支援那些無法被生成上下文存取的建構子，即使你用 [JsonConstructor]標記 。

已知問題

如需有關來源產生其他已知問題的資訊，請參閱 dotnet/runtime 存放庫中標示 "source-generator" 的 GitHub 問題。

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

JsonSerializer 有許多功能可自訂序列化的輸出，例如命名原則和保留參考。 支援這些功能會造成一些效能額外負荷。 來源產生可以藉由產生直接使用 Utf8JsonWriter 的最佳化程式碼，改善序列化效能。

串行化優化模式會發出快速路徑串行化方法，但不會發出串行化元數據。 快速路徑串行化在可以執行的動作中受到限制;它不支援異步串行化或任何還原串行化模式。

此外，優化程式代碼不支援所有支援的串行化功能 JsonSerializer 。 序列化程式會偵測是否可以使用最佳化程式碼，並在指定不支援的選項時，回復為預設序列化程式碼。 例如，JsonNumberHandling.AllowReadingFromString 不適用於撰寫，因此指定這個選項不會導致回復為預設程式碼。

下表顯示快速路徑序列化支援 JsonSerializerOptions 中的哪些選項：

(不支援下列選項，因為其只適用於 還原序列化：PropertyNameCaseInsensitive、ReadCommentHandling 和 UnknownTypeHandling。)

下表顯示快速路徑序列化支援哪些屬性：

如果為類型指定了不支援的選項或屬性，則串行化程式會回復為 元數據模式，假設來源產生器已設定為產生元數據。 在此情況下，串行化該類型時不會使用優化的程式碼，但可能會用於其他類型。 因此，請務必使用您的選項和工作負載來執行效能測試，以判斷您實際可從序列化-最佳化模式獲得多少好處。 此外，回退到 JsonSerializer 代碼的能力需要 元數據模式。 如果您只選取序列化-最佳化模式，序列化可能會因必須回復至 JsonSerializer 程式碼的型別或選項而失敗。

另請參閱

• .NET 中的 JSON 序列化和還原序列化 - 概觀
• 如何使用程式庫