Birleşim türlerini System.Text.Json ile serileştirme

.NET 11'den başlayarak C JsonSerializer# 15 birleşim türlerini destekler. Bir union, tanımında durum türlerinden birini içerir. JsonSerializer etkin harf durumu değerini yazar ve geri okuyabilir.

Birleşim değerlerini seri hale getirme ve seri durumdan çıkarma

Durumları farklı JSON belirteç türlerine sahip olan bir birleşim tanımlayın:

public union Payload(int, string, Message);
public sealed record Message(string Text);

Birleşimi serileştirmek ve seri durumdan çıkarmak için JsonSerializer kullanın:

Payload payload = new Message("Ready");
string json = JsonSerializer.Serialize(payload);
Payload copy = JsonSerializer.Deserialize<Payload>(json);

Serileştirilmiş JSON, sarmalayıcı veya ayırt edici yerine etkin durum değerini içerir:

{"Text":"Ready"}

Varsayılan olarak, seri hale getirici gelen JSON'ı belirteç türüne göre sınıflandırır. Önceki birleşimde, bir JSON numarası öğesini seçer int, bir JSON dizesi seçer stringve bir JSON nesnesi öğesini seçer Message.

ile JsonSerializerOptions.Web, JSON int dizesinden de okunabilir. Hem int hem de string durumu, ardından Payload dize belirteci türünü üstlenir. Serileştirici, iki durumdan herhangi birini ayrıştırmadan önce belirsizlik durumunda bile "25%" fırlatır JsonException. Dizeleri web varsayılanlarını kullanarak okumak için, harf durumunu belirleyen özel bir sınıflandırıcı sağlayın.

Aynı JSON belirteç türüne sahip durumları ayırt etme

Belirteç sınıflandırması, her ikisi de JSON nesnesi olarak serileştirilen iki durumu ayırt edemez. Nesne durumlarını özellik adlarına göre sınıflandırmak için uygulayın JsonUnionAttribute ve seçin JsonUnionTypeStructuralClassifier :

[JsonUnion(TypeClassifier = typeof(JsonUnionTypeStructuralClassifier))]
public union Pet(Dog, Cat);
public sealed record Dog(string Name, string Breed);
public sealed record Cat(string Name, int Lives);

Burada, JsonUnionAttribute mevcut Pet birleşim için bir sınıflandırıcı seçer; bunu sıradan bir türe uygulamak bu türü birleşime dönüştürmez.

Sınıflandırıcı, yük Lives içerdiğinde Dog seçer ve Breed içerdiğinde Cat seçer:

Pet pet = JsonSerializer.Deserialize<Pet>(
    """{"Name":"Rex","Breed":"Husky"}""");

JSON nesneleri için yapısal sınıflandırıcı, uyumlu nesne durumları kümesiyle başlar ve tanıdığı kök düzeyi özellik adlarını okudukça bu kümeyi daraltır. Gerekli özellikler, bulunmadıklarında durumları kaldırır. JsonUnmappedMemberHandling.Disallow, veri yükü olay kaydının tanımlamadığı bir özellik içerdiğinde olay kaydını kaldırır. Sınıflandırma yalnızca tek bir durum kaldığında başarılı sayılır.

Yapısal sınıflandırıcı özellik değerlerini, iç içe nesneleri, dize içeriğini veya dizi öğelerini incelemez. Şu sonuçları aklınızda bulundurun:

  • Geriye hiç aday bırakmayan veya birden fazla aday bırakan bir yük, JsonException fırlatır.
  • Sınıflandırıcı oluşturulduğunda çakışan veya gölgelenen nesne sözleşmeleri reddedilebilir.
  • Aynı JSON belirteci türünü kullanan nesne dışı birden çok durum desteklenmez. Örneğin, Guid ve string her ikisi de JSON dizelerini kullanır.
  • Sade nesne durumu, bir sözlük, JsonObject veya POCO olmayan nesne biçimindeki başka bir durumla karıştırılamaz.
  • İç içe birleşim durumları ve polimorfik durumlar desteklenmez.
  • ReferenceHandler.Preserve desteklenmez.
  • Büyük/küçük harf durumlarını ayırt edemeyen bir yapılandırma, serileştirici sınıflandırıcıyı oluştururken NotSupportedException oluşturur.

Birleşimleri veya kapalı hiyerarşileri seçme

Kontrol etmediğiniz, ayırt edici içermeyen bir JSON biçimini korumanız gerektiğinde veya durumların farklı JSON yapıları olduğunda bir birleşim kullanın. Örneğin, Payload'nin int ve string durumları JSON belirteci türüne göre ayırt edilebilir. Ancak gibi Pet(Dog, Cat)nesne durumlarında, özellik adlarında yapılan değişiklikler yapısal sınıflandırıcının seçtiği durumu etkileyebilir.

Türleri ve JSON sözleşmesini denetlediğinizde, çıkarımlı polimorfizme sahip kapalı bir hiyerarşi , nesne olaylarını bunun yerine bir ayrımcıyla tanımlayabilir:

[JsonPolymorphic(InferClosedTypePolymorphism = true)]
public closed record Event;
public sealed record Created(int Id) : Event;
public sealed record Deleted(int Id) : Event;

JsonSerializer.Serialize<Event>(new Created(42)) {"$type":"Created","Id":42} yazar. Türetilmiş her iki tür de Id öğesini bildirir, ancak ayırt edici, durumu özelliklerinden bağımsız olarak belirler. Bu, özellikler değiştikçe büyük/küçük harf seçimini daha tutarlı hale getirir. Birleşim türlerinden farklı olarak, türetilen türlerin ortak bir temel sınıfı paylaşması gerekir ve çıkarımsal polimorfizmi açıkça etkinleştirmeniz gerekir; closed değiştiricisi tek başına bir ayırıcı eklemez.

Özel sınıflandırıcı sağlama

Varsayılan belirteç sınıflandırması veya yerleşik JsonUnionTypeStructuralClassifier gereksinimlerinizi karşılamadığında, JsonTypeClassifierFactory sınıfından türetin. Özel sınıflandırıcı, birleşim olayı seçmek için diğer yapısal kuralları kullanabilir. Fabrikayı şu konumlardan birine kaydedin:

Bir sınıflandırıcı, geçerli JSON değerini okur ve JsonTypeClassifierContext.UnionCases öğesindeki durum türlerinden birini döndürür. Seri hale getirici önce sözleşme temsilcisini, ardından birleşim başına fabrikayı, seçenekler düzeyindeki fabrikaları ve yerleşik belirteç sınıflandırmasını denetler.

Belirsiz birleşimler için, bir sınıflandırıcı oluşturma zamanında yapılandırılmadığı sürece kaynak oluşturucu bir tanılama bildirir.

Null ve varsayılan birleşim değerlerini işleme

Birleşim türü, null atanabilir durum türleri bildirebilir. JSON null boş değer alabilen ilk durumu seçer. Birleşimde null olabilen bir seçenek yoksa, JSON null varsayılan birleşim değerini oluşturur. Derleyicinin oluşturduğu bir struct union için varsayılan değerin etkin bir durumu yoktur ve JSON’da null olarak serileştirilir.

Birleşim sözleşmelerini özelleştirme

Gelişmiş senaryolar için birleşim meta verilerini JsonTypeInfo aracılığıyla özelleştirin. Bir JsonTypeInfo.Kind union'ının değeri JsonTypeInfoKind.Union'dir. Sözleşmesi şu özellikleri ortaya çıkarır:

JsonTypeInfo öğesini değiştirme hakkında daha fazla bilgi için JSON sözleşmesini özelleştirme bölümüne bakın.

Ayrıca bakınız