Share via

'da kaynak oluşturma modları System.Text.Json

  • Makale

Kaynak oluşturma iki modda kullanılabilir: meta veri tabanlı ve serileştirme iyileştirme. Bu makalede farklı modlar açıklanmaktadır.

Kaynak oluşturma modlarını kullanma hakkında bilgi için bkz . 'de System.Text.Jsonkaynak oluşturmayı kullanma.

Meta veri tabanlı mod

Meta veri toplama işlemini çalışma zamanından derleme zamanına taşımak için kaynak oluşturmayı kullanabilirsiniz. Derleme sırasında meta veriler toplanır ve kaynak kod dosyaları oluşturulur. Oluşturulan kaynak kodu dosyaları otomatik olarak uygulamanın ayrılmaz bir parçası olarak derlenir. Bu teknik, hem seri hale getirme hem de seri durumdan çıkarma performansını geliştiren çalışma zamanı meta veri koleksiyonunu ortadan kaldırır.

Kaynak oluşturma tarafından sağlanan performans iyileştirmeleri önemli olabilir. Örneğin, test sonuçları %40'a kadar veya daha fazla başlatma süresi azaltma, özel bellek azaltma, aktarım hızı artışı (serileştirme iyileştirme modunda) ve uygulama boyutunu azaltma göstermiştir.

Bilinen sorunlar

Her iki serileştirme modunda da varsayılan olarak yalnızca public özellikler ve alanlar desteklenir. Ancak yansıma modu erişimci kullanımını privatedesteklerken kaynak oluşturma modu desteklemez. Örneğin, JsonInclude özniteliğini ayarlayıcı veya alıcısı olan bir private özelliğe uygulayabilirsiniz ve yansıma modunda seri hale getirilir. Kaynak oluşturma modu yalnızca public veya internal özelliklerin public erişimcilerini destekler. Genel olmayan erişimcileri ayarlar [JsonInclude] ve kaynak oluşturma modunu seçerseniz, çalışma zamanında bir NotSupportedException oluşturulur.

Her iki serileştirme modunda da varsayılan olarak yalnızca public özellikler ve alanlar desteklenir. Ancak yansıma modu üyelerin private ve privateerişimcilerin kullanımını desteklerken kaynak oluşturma modu desteklemez. Örneğin, JsonInclude özniteliğini bir private özelliğe veya ayarlayıcı veya alıcısı olan bir private özelliğe uygularsanız, yansıma modunda seri hale getirilir. Kaynak oluşturma modu yalnızca public özelliklerin internal üyelerini ve public veya internal erişimcilerini public destekler. Üyeleri veya erişimcileri ayarlar [JsonInclude]private ve kaynak oluşturma modunu seçerseniz, çalışma zamanında bir NotSupportedException oluşturulur.

Kaynak oluşturmayla ilgili diğer bilinen sorunlar hakkında bilgi için dotnet/runtime deposundaki "source-generator" etiketli GitHub sorunlarına bakın.

Serileştirme-iyileştirme (hızlı yol) modu

JsonSerializeradlandırma ilkeleri ve başvuruları koruma gibi serileştirme çıkışını özelleştiren birçok özelliğe sahiptir. Tüm bu özellikler için destek, bazı performans ek yüklerine neden olur. Kaynak oluşturma, doğrudan kullanan Utf8JsonWriter iyileştirilmiş kod oluşturarak serileştirme performansını geliştirebilir.

İyileştirilmiş kod, destekleyen tüm serileştirme özelliklerini JsonSerializer desteklemez. Seri hale getirici, iyileştirilmiş kodun kullanılıp kullanılamayacağını algılar ve desteklenmeyen seçenekler belirtilirse varsayılan serileştirme koduna geri döner. Örneğin, JsonNumberHandling.AllowReadingFromString yazma için geçerli değildir, bu nedenle bu seçeneğin belirtilmesi varsayılan koda geri dönüşe neden olmaz.

Aşağıdaki tabloda, hızlı yol serileştirme tarafından hangi seçeneklerin JsonSerializerOptions desteklendiği gösterilmektedir:

Seri hale getirme seçeneği Hızlı yol için desteklenir
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

(Aşağıdaki seçenekler yalnızca serileştirmeyi kaldırmaya uygulandığından desteklenmez: PropertyNameCaseInsensitive, ReadCommentHandlingve UnknownTypeHandling.)

Aşağıdaki tabloda, hangi özniteliklerin hızlı yol serileştirme tarafından desteklendiği gösterilmektedir:

Öznitelik Hızlı yol için desteklenir
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

Bir tür için desteklenmeyen bir seçenek veya öznitelik belirtilirse, kaynak oluşturucunun meta veri oluşturmak üzere yapılandırıldığı varsayılarak seri hale getirici meta veri moduna geri döner. Bu durumda, iyileştirilmiş kod bu tür serileştirilirken kullanılmaz, ancak diğer türler için kullanılabilir. Bu nedenle, serileştirme-iyileştirme modundan ne kadar avantaj elde edebilirsiniz belirlemek için seçeneklerinizle ve iş yüklerinizle performans testi yapmanız önemlidir. Ayrıca, koda geri dönebilmek için JsonSerializer meta veri toplama modu gerekir. Yalnızca serileştirme-iyileştirme modunu seçerseniz, koda JsonSerializer geri dönmesi gereken türler veya seçenekler için serileştirme başarısız olabilir.

Ayrıca bkz.