Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
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ı nasıl kullanacağınız hakkında bilgi için System.Text.Json'da kaynak oluşturmayı kullanma bölümüne bakın.
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, çalışma zamanı meta veri toplamayı ortadan kaldırarak serileştirme ve deserleştirme performansını geliştirir.
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.
Genel olmayan üyeler ve oluşturucular
Varsayılan olarak, hem yansıma modu hem de kaynak oluşturma modu yalnızca public serileştirme sözleşmesindeki özellikleri ve alanları içerir.
.NET 11'den başlayarak, kaynak oluşturma [JsonInclude] özniteliğiyle açıkça işaretlediğiniz üyeleri destekler. Üye internal, protected veya private olabilir. Ayrıca, private ile işaretlediğiniz özelliklerde [JsonInclude], internal ve protected erişimcilerini de destekler. Kaynak oluşturma, [JsonConstructor] ile işaretlenmiş erişilemez oluşturucuları da destekler.
.NET 11'de oluşturulan erişimciler UnsafeAccessorAttribute kullanır.
Kaynak tarafından oluşturulan, yalnızca init için olan bir ayarlayıcı, yalnızca JSON yükü bu özelliği içerdiğinde çalışır. Yükte yer verilmeyen bir init-only özellik, özellik başlatıcısındaki değerini korur.
.NET 10 ve önceki sürümlerde, kaynak oluşturma aşağıdaki sınırlamalara sahiptir:
- Kaynak oluşturma,
protectedüyelerini veyaprivateerişimcilerini desteklemez. Böyle bir üyeyi[JsonInclude]ile işaretlerseniz, serileştirici çalışma zamanında bir NotSupportedException fırlatır. - Kaynak oluşturma, üyeleri ve erişimcileri yalnızca aynı derlemede oluşturulan JsonSerializerContext için erişilebilir olduklarında destekler
internal. - Kaynak oluşturma,
[JsonConstructor]ile işaretleseniz bile oluşturulan bağlam tarafından erişilemeyen oluşturucuları desteklemez.
Bilinen sorunlar
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
JsonSerializer serileştirme çıkışını özelleştiren birçok özelliğe sahiptir, örneğin adlandırma ilkeleri ve başvuruları koruma. 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.
Serileştirme-iyileştirme modu hızlı yol serileştirme yöntemlerini yayar ancak serileştirme meta verilerini yaymaz. Hızlı yol serileştirmesi yapabilecekleri ile sınırlıdır; zaman uyumsuz serileştirmeyi veya herhangi bir çözme işlem modunu desteklemez.
Ayrıca iyileştirilmiş kod, JsonSerializer tarafından desteklenen tüm serileştirme özelliklerini 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 deşifre etmeye uygulandıkları için desteklenmemektedir: PropertyNameCaseInsensitive, ReadCommentHandling, ve 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 JsonSerializermeta veri 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.