Share via

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

  • 發行項

來源產生可用於兩種模式：中繼資料型和序列化最佳化。 本文說明不同的模式。

如需如何使用來源產生模式的資訊，請參閱如何在 System.Text.Json 中使用來源產生 (機器翻譯)。

中繼資料型模式

您可以使用來源產生，將中繼資料收集流程從執行階段移至編譯時期。 在編譯期間，會收集中繼資料，並產生原始程式碼檔案。 產生的原始程式碼檔案會自動編譯為應用程式不可或缺的一部分。 這項技術會消除執行階段中繼資料集合，這可改善序列化和還原序列化的效能。

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

已知問題

在任一序列化模式中，預設僅支援 public 屬性和欄位。 不過，反映模式支援使用private存取子，而來源產生模式則不支援。 例如，您可以將 JsonInclude 屬性套用至具有 private setter 或 getter 的屬性，而且該屬性會以反映模式序列化。 來源產生模式僅支援 public 屬性的 public 或 internal 存取子。 如果您在非公用存取子上設定 [JsonInclude] 並選擇來源產生模式，則會在執行階段擲回 NotSupportedException。

在任一序列化模式中，預設僅支援 public 屬性和欄位。 不過，反映模式支援使用 private 成員和 private 存取子，而來源產生模式則不支援。 例如，如果您將 JsonInclude 屬性套用至 private 屬性或具有 private setter 或 getter 的屬性，該屬性會以反映模式序列化。 來源產生模式僅支援 public 屬性的 public 或 internal 成員和 public 或 internal 存取子。 如果您在 private 成員或存取子上設定 [JsonInclude] 並選擇來源產生模式，則會在執行階段擲回 NotSupportedException。

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

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

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

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

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

序列化選項 支援快速路徑
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

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

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

屬性 支援快速路徑
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

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

另請參閱