Geçiş:Newtonsoft.JsonSystem.Text.Json

  • Makale

Bu makalede'den Newtonsoft.Json 'e System.Text.Jsonnasıl geçiş yapılacağını gösterir.

Ad alanı, System.Text.Json JavaScript Nesne Gösterimi'ne (JSON) serileştirme ve seri durumdan çıkarma işlevleri sağlar. Kitaplık System.Text.Json , .NET Core 3.1 ve sonraki sürümleri için çalışma zamanına dahil edilir. Diğer hedef çerçeveler için NuGet paketini yükleyin System.Text.Json . Paket aşağıdakileri destekler:

  • .NET Standard 2.0 ve sonraki sürümleri
  • .NET Framework 4.7.2 ve sonraki sürümleri
  • .NET Core 2.0, 2.1 ve 2.2

System.Text.Json öncelikle performans, güvenlik ve standartların uyumluluğuna odaklanır. Varsayılan davranışta bazı önemli farklılıklara sahiptir ve ile Newtonsoft.Jsonözellik eşliğine sahip olmayı hedeflemez. Bazı senaryolarda şu System.Text.Json anda yerleşik işlevsellik yoktur, ancak önerilen geçici çözümler vardır. Diğer senaryolarda geçici çözümler pratik değildir.

En sık istenen özellikleri eklemeye yatırım yapıyoruz. Uygulamanız eksik bir özelliğe bağlıysa, senaryonuza yönelik desteğin eklenip eklenmediğini öğrenmek için dotnet/runtime GitHub deposunda bir sorun bildirin.

Bu makalenin çoğu API'nin nasıl kullanılacağıyla JsonSerializer ilgili olmakla birlikte , (Belge Nesne Modeli'ni veya DOM'yi temsil eder) Utf8JsonReaderve Utf8JsonWriter türlerini kullanma JsonDocument yönergelerini de içerir.

Visual Basic'te kullanamazsınız Utf8JsonReader, bu da özel dönüştürücüler yazabileceğiniz anlamına gelir. Burada sunulan geçici çözümlerin çoğu için özel dönüştürücüler yazmanız gerekir. C# dilinde özel bir dönüştürücü yazabilir ve bunu bir Visual Basic projesine kaydedebilirsiniz. Daha fazla bilgi için bkz . Visual Basic desteği.

Farklılıklar tablosu

Aşağıdaki tabloda özellikler ve System.Text.Json eşdeğerler listelenmiştirNewtonsoft.Json. Eşdeğerler aşağıdaki kategorilere ayrılır:

  • ✔️ Yerleşik işlevsellik tarafından desteklenir. 'den System.Text.Json benzer davranışlar almak için bir öznitelik veya genel seçenek kullanılması gerekebilir.
  • ⚠️ Desteklenmez, ancak geçici çözüm mümkündür. Geçici çözümler, işlevsellikle Newtonsoft.Json tam eşlik sağlayabilen özel dönüştürücülerdir. Bunlardan bazıları için örnek kod örnek olarak sağlanır. Bu Newtonsoft.Json özelliklere güveniyorsanız, geçiş için .NET nesne modellerinizde veya diğer kod değişikliklerinizde değişiklik yapılması gerekir.
  • ❌ Desteklenmez ve geçici çözüm pratik veya mümkün değildir. Bu Newtonsoft.Json özelliklere güveniyorsanız, önemli değişiklikler olmadan geçiş mümkün olmayacaktır.
Newtonsoft.Json özelliği System.Text.Json Eşdeğer
Varsayılan olarak büyük/küçük harfe duyarlı olmayan seri durumdan çıkarma ✔️ PropertyNameCaseInsensitive genel ayarı
Camel-case özellik adları ✔️ PropertyNamingPolicy genel ayarı
Snake-case özellik adları ✔️ Yılan olayı adlandırma ilkesi
En az karakter kaçışı ✔️ Katı karakter kaçışı, yapılandırılabilir
NullValueHandling.Ignore genel ayar ✔️ DefaultIgnoreCondition genel seçeneği
Açıklamalara izin ver ✔️ ReadCommentHandling genel ayarı
Sondaki virgüllere izin ver ✔️ AllowTrailingCommas genel ayarı
Özel dönüştürücü kaydı ✔️ Öncelik sırası farklıdır
Varsayılan maksimum derinlik 64, yapılandırılabilir ✔️ Varsayılan maksimum derinlik 64, yapılandırılabilir
PreserveReferencesHandling genel ayar ✔️ ReferenceHandling genel ayarı
Tırnak içindeki sayıları seri hale getirme veya seri durumdan çıkarma ✔️ NumberHandling genel ayarı, [JsonNumberHandling] özniteliği
Sabit sınıflar ve yapılar için seri durumdan çıkarma ✔️ JsonConstructor, C# 9 Kayıtları
Alanlar için destek ✔️ IncludeFields genel ayarı, [JsonInclude] özniteliği
DefaultValueHandling genel ayar ✔️ DefaultIgnoreCondition genel ayarı
NullValueHandling ayarı açık [JsonProperty] ✔️ JsonIgnore özniteliği
DefaultValueHandling ayarı açık [JsonProperty] ✔️ JsonIgnore özniteliği
Dize olmayan anahtarla seri durumdan çıkarma Dictionary ✔️ Desteklenen
Ortak olmayan özellik ayarlayıcıları ve alıcıları için destek ✔️ JsonInclude özniteliği
[JsonConstructor] özniteliği ✔️ [JsonConstructor] özniteliği
ReferenceLoopHandling genel ayar ✔️ ReferenceHandling genel ayarı
Geri Çağırmalar ✔️ Geri
NaN, Infinity, -Infinity ✔️ Desteklenen
Required özniteliğinde [JsonProperty] ayarı ✔️ [JsonRequired] özniteliği ve C# gerekli değiştirici
DefaultContractResolver özellikleri yoksaymak için ✔️ DefaultJsonTypeInfoResolver sınıfı
Polimorfik serileştirme ✔️ [JsonDerivedType] özniteliği
Polimorfik seri durumdan çıkarma ✔️ [JsonDerivedType] özniteliğinde tür ayırıcısı
Dize sabit listesi değerini seri durumdan çıkarma ✔️ Dize sabit listesi değerlerini seri durumdan çıkarma
MissingMemberHandling genel ayar ✔️ Eksik üyeleri işleme
Özellikleri ayarlayıcılar olmadan doldurma ✔️ Özellikleri ayarlayıcılar olmadan doldurma
ObjectCreationHandling genel ayar ✔️ Özellikleri değiştirmek yerine yeniden kullanma
Çok çeşitli türler için destek ⚠️ Bazı türler özel dönüştürücüler gerektirir
Çıkarsanan türü özelliklere seri durumdan çıkarma object ⚠️ Desteklenmez, geçici çözüm, örnek
JSON null değişmez değerini null atanamayan değer türlerine seri durumdan çıkarma ⚠️ Desteklenmez, geçici çözüm, örnek
DateTimeZoneHandling, DateFormatString ayarlar ⚠️ Desteklenmez, geçici çözüm, örnek
JsonConvert.PopulateObject Yöntem ⚠️ Desteklenmez, geçici çözüm
System.Runtime.Serialization Öznitelik desteği ⚠️ Desteklenmez, geçici çözüm, örnek
JsonObjectAttribute ⚠️ Desteklenmez, geçici çözüm
Tırnak işaretleri olmadan özellik adlarına izin ver ❌Tasarım tarafından desteklenmez
Dize değerleri çevresinde tek tırnak işaretine izin ver ❌Tasarım tarafından desteklenmez
Dize özellikleri için dize olmayan JSON değerlerine izin ver ❌Tasarım tarafından desteklenmez
TypeNameHandling.All genel ayar ❌Tasarım tarafından desteklenmez
Sorgu desteği JsonPath ❌Desteklenmiyor
Yapılandırılabilir sınırlar ❌Desteklenmiyor
Newtonsoft.Json özelliği System.Text.Json Eşdeğer
Varsayılan olarak büyük/küçük harfe duyarlı olmayan seri durumdan çıkarma ✔️ PropertyNameCaseInsensitive genel ayarı
Camel-case özellik adları ✔️ PropertyNamingPolicy genel ayarı
En az karakter kaçışı ✔️ Katı karakter kaçışı, yapılandırılabilir
NullValueHandling.Ignore genel ayar ✔️ DefaultIgnoreCondition genel seçeneği
Açıklamalara izin ver ✔️ ReadCommentHandling genel ayarı
Sondaki virgüllere izin ver ✔️ AllowTrailingCommas genel ayarı
Özel dönüştürücü kaydı ✔️ Öncelik sırası farklıdır
Varsayılan maksimum derinlik 64, yapılandırılabilir ✔️ Varsayılan maksimum derinlik 64, yapılandırılabilir
PreserveReferencesHandling genel ayar ✔️ ReferenceHandling genel ayarı
Tırnak içindeki sayıları seri hale getirme veya seri durumdan çıkarma ✔️ NumberHandling genel ayarı, [JsonNumberHandling] özniteliği
Sabit sınıflar ve yapılar için seri durumdan çıkarma ✔️ JsonConstructor, C# 9 Kayıtları
Alanlar için destek ✔️ IncludeFields genel ayarı, [JsonInclude] özniteliği
DefaultValueHandling genel ayar ✔️ DefaultIgnoreCondition genel ayarı
NullValueHandling ayarı açık [JsonProperty] ✔️ JsonIgnore özniteliği
DefaultValueHandling ayarı açık [JsonProperty] ✔️ JsonIgnore özniteliği
Dize olmayan anahtarla seri durumdan çıkarma Dictionary ✔️ Desteklenen
Ortak olmayan özellik ayarlayıcıları ve alıcıları için destek ✔️ JsonInclude özniteliği
[JsonConstructor] özniteliği ✔️ [JsonConstructor] özniteliği
ReferenceLoopHandling genel ayar ✔️ ReferenceHandling genel ayarı
Geri Çağırmalar ✔️ Geri
NaN, Infinity, -Infinity ✔️ Desteklenen
Required özniteliğinde [JsonProperty] ayarı ✔️ [JsonRequired] özniteliği ve C# gerekli değiştirici
DefaultContractResolver özellikleri yoksaymak için ✔️ DefaultJsonTypeInfoResolver sınıfı
Polimorfik serileştirme ✔️ [JsonDerivedType] özniteliği
Polimorfik seri durumdan çıkarma ✔️ [JsonDerivedType] özniteliğinde tür ayırıcısı
Dize sabit listesi değerini seri durumdan çıkarma ✔️ Dize sabit listesi değerlerini seri durumdan çıkarma
Çok çeşitli türler için destek ⚠️ Bazı türler özel dönüştürücüler gerektirir
Çıkarsanan türü özelliklere seri durumdan çıkarma object ⚠️ Desteklenmez, geçici çözüm, örnek
JSON null değişmez değerini null atanamayan değer türlerine seri durumdan çıkarma ⚠️ Desteklenmez, geçici çözüm, örnek
DateTimeZoneHandling, DateFormatString ayarlar ⚠️ Desteklenmez, geçici çözüm, örnek
JsonConvert.PopulateObject Yöntem ⚠️ Desteklenmez, geçici çözüm
ObjectCreationHandling genel ayar ⚠️ Desteklenmez, geçici çözüm
Ayarlayıcılar olmadan koleksiyonlara ekleme ⚠️ Desteklenmez, geçici çözüm
Snake-case özellik adları ⚠️ Desteklenmez, geçici çözüm
System.Runtime.Serialization Öznitelik desteği ⚠️ Desteklenmez, geçici çözüm, örnek
MissingMemberHandling genel ayar ⚠️ Desteklenmez, geçici çözüm, örnek
JsonObjectAttribute ⚠️ Desteklenmez, geçici çözüm
Tırnak işaretleri olmadan özellik adlarına izin ver ❌Tasarım tarafından desteklenmez
Dize değerleri çevresinde tek tırnak işaretine izin ver ❌Tasarım tarafından desteklenmez
Dize özellikleri için dize olmayan JSON değerlerine izin ver ❌Tasarım tarafından desteklenmez
TypeNameHandling.All genel ayar ❌Tasarım tarafından desteklenmez
Sorgu desteği JsonPath ❌Desteklenmiyor
Yapılandırılabilir sınırlar ❌Desteklenmiyor
Newtonsoft.Json özelliği System.Text.Json Eşdeğer
Varsayılan olarak büyük/küçük harfe duyarlı olmayan seri durumdan çıkarma ✔️ PropertyNameCaseInsensitive genel ayarı
Camel-case özellik adları ✔️ PropertyNamingPolicy genel ayarı
En az karakter kaçışı ✔️ Katı karakter kaçışı, yapılandırılabilir
NullValueHandling.Ignore genel ayar ✔️ DefaultIgnoreCondition genel seçeneği
Açıklamalara izin ver ✔️ ReadCommentHandling genel ayarı
Sondaki virgüllere izin ver ✔️ AllowTrailingCommas genel ayarı
Özel dönüştürücü kaydı ✔️ Öncelik sırası farklıdır
Varsayılan maksimum derinlik 64, yapılandırılabilir ✔️ Varsayılan maksimum derinlik 64, yapılandırılabilir
PreserveReferencesHandling genel ayar ✔️ ReferenceHandling genel ayarı
Tırnak içindeki sayıları seri hale getirme veya seri durumdan çıkarma ✔️ NumberHandling genel ayarı, [JsonNumberHandling] özniteliği
Sabit sınıflar ve yapılar için seri durumdan çıkarma ✔️ JsonConstructor, C# 9 Kayıtları
Alanlar için destek ✔️ IncludeFields genel ayarı, [JsonInclude] özniteliği
DefaultValueHandling genel ayar ✔️ DefaultIgnoreCondition genel ayarı
NullValueHandling ayarı açık [JsonProperty] ✔️ JsonIgnore özniteliği
DefaultValueHandling ayarı açık [JsonProperty] ✔️ JsonIgnore özniteliği
Dize olmayan anahtarla seri durumdan çıkarma Dictionary ✔️ Desteklenen
Ortak olmayan özellik ayarlayıcıları ve alıcıları için destek ✔️ JsonInclude özniteliği
[JsonConstructor] özniteliği ✔️ [JsonConstructor] özniteliği
ReferenceLoopHandling genel ayar ✔️ ReferenceHandling genel ayarı
Geri Çağırmalar ✔️ Geri
NaN, Infinity, -Infinity ✔️ Desteklenen
Dize sabit listesi değerini seri durumdan çıkarma ✔️ Dize sabit listesi değerlerini seri durumdan çıkarma
Çok çeşitli türler için destek ⚠️ Bazı türler özel dönüştürücüler gerektirir
Polimorfik serileştirme ⚠️ Desteklenmez, geçici çözüm, örnek
Polimorfik seri durumdan çıkarma ⚠️ Desteklenmez, geçici çözüm, örnek
Çıkarsanan türü özelliklere seri durumdan çıkarma object ⚠️ Desteklenmez, geçici çözüm, örnek
JSON null değişmez değerini null atanamayan değer türlerine seri durumdan çıkarma ⚠️ Desteklenmez, geçici çözüm, örnek
Required özniteliğinde [JsonProperty] ayarı ⚠️ Desteklenmez, geçici çözüm, örnek
DefaultContractResolver özellikleri yoksaymak için ⚠️ Desteklenmez, geçici çözüm, örnek
DateTimeZoneHandling, DateFormatString ayarlar ⚠️ Desteklenmez, geçici çözüm, örnek
JsonConvert.PopulateObject Yöntem ⚠️ Desteklenmez, geçici çözüm
ObjectCreationHandling genel ayar ⚠️ Desteklenmez, geçici çözüm
Ayarlayıcılar olmadan koleksiyonlara ekleme ⚠️ Desteklenmez, geçici çözüm
Snake-case özellik adları ⚠️ Desteklenmez, geçici çözüm
JsonObjectAttribute ⚠️ Desteklenmez, geçici çözüm
System.Runtime.Serialization Öznitelik desteği ❌Desteklenmiyor
MissingMemberHandling genel ayar ❌Desteklenmiyor
Tırnak işaretleri olmadan özellik adlarına izin ver ❌Tasarım tarafından desteklenmez
Dize değerleri çevresinde tek tırnak işaretine izin ver ❌Tasarım tarafından desteklenmez
Dize özellikleri için dize olmayan JSON değerlerine izin ver ❌Tasarım tarafından desteklenmez
TypeNameHandling.All genel ayar ❌Tasarım tarafından desteklenmez
Sorgu desteği JsonPath ❌Desteklenmiyor
Yapılandırılabilir sınırlar ❌Desteklenmiyor

Bu, kapsamlı bir özellik listesi Newtonsoft.Json değildir. Liste, GitHub sorunlarında veya StackOverflow gönderilerinde istenen senaryoların çoğunu içerir. Burada listelenen ve şu anda örnek kodu olmayan senaryolardan biri için geçici bir çözüm uygularsanız ve çözümünüzü paylaşmak istiyorsanız, bu sayfanın altındaki Geri Bildirim bölümünde Bu sayfa'yı seçin. Bu, bu belgenin GitHub deposunda bir sorun oluşturur ve bu sorunu bu sayfadaki Geri Bildirim bölümünde de listeler.

Varsayılan davranış farklılıkları

System.Text.Json varsayılan olarak katıdır ve arayan adına herhangi bir tahmin veya yorum yapmaktan kaçınarak belirleyici davranışı vurgular. Kitaplık, performans ve güvenlik için kasıtlı olarak bu şekilde tasarlanmıştır. Newtonsoft.Json varsayılan olarak esnektir. Tasarımdaki bu temel fark, varsayılan davranışta aşağıdaki belirli farklılıkların birçoğunun arkasındadır.

Büyük/küçük harfe duyarlı olmayan seri durumdan çıkarma

Seri durumdan çıkarma sırasında, Newtonsoft.Json varsayılan olarak büyük/küçük harfe duyarsız özellik adı eşleştirmesi yapar. Varsayılan System.Text.Json değer büyük/küçük harfe duyarlıdır ve tam eşleşme gerçekleştirdiğinden daha iyi performans sağlar. Büyük/küçük harfe duyarsız eşleştirme yapma hakkında bilgi için bkz . Büyük/küçük harfe duyarsız özellik eşleştirme.

ASP.NET Core kullanarak dolaylı olarak kullanıyorsanız System.Text.Json , gibi Newtonsoft.Jsonbir davranış elde etmek için hiçbir şey yapmanız gerekmez. ASP.NET Core, kullandığında System.Text.Jsoncamel-casing özellik adları ve büyük/küçük harfe duyarsız eşleştirme ayarlarını belirtir.

ASP.NET Core, tırnak içine alınan sayıların varsayılan olarak seri durumdan çıkarılmasına da olanak tanır.

En az karakter kaçışı

Serileştirme sırasında, Newtonsoft.Json karakterlerin onlardan kaçmadan geçmesine izin verme konusunda nispeten izin verilir. Yani, karakterlerin kod noktasının nerede xxxx olduğuyla \uxxxx değiştirmez. Onlardan kaçtığı yerde, karakterden önce bir \ yayarak bunu yapar (örneğin, " olur \"). System.Text.Json , siteler arası betik (XSS) veya bilgilerin açığa çıkması saldırılarına karşı derinlemesine koruma sağlamak için varsayılan olarak daha fazla karakterden kaçar ve bunu altı karakterlik diziyi kullanarak yapar. System.Text.Jsonvarsayılan olarak ASCII olmayan tüm karakterlerden kaçar, bu nedenle içinde Newtonsoft.Jsonkullanıyorsanız StringEscapeHandling.EscapeNonAscii hiçbir şey yapmanıza gerek yoktur. System.Text.Json ayrıca varsayılan olarak HTML'ye duyarlı karakterlerden de kurtulur. Varsayılan System.Text.Json davranışı geçersiz kılma hakkında bilgi için bkz . Karakter kodlamasını özelleştirme.

Açıklamalar

Seri durumdan çıkarma sırasında JSON'daki Newtonsoft.Json açıklamaları varsayılan olarak yoksayar. System.Text.Json RFC 8259 belirtimi bunları içermediğinden, varsayılan olarak açıklamalar için özel durumlar oluşturulur. Açıklamalara izin verme hakkında bilgi için bkz . Açıklamalara ve sondaki virgüllere izin verme.

Sondaki virgüller

Seri durumdan çıkarma sırasında, Newtonsoft.Json sondaki virgülleri varsayılan olarak yoksayar. Ayrıca birden çok sondaki virgülleri (örneğin, [{"Color":"Red"},{"Color":"Green"},,]) yoksayar. System.Text.Json RFC 8259 belirtimi bunlara izin vermediğinden varsayılan olarak sondaki virgüller için özel durumlar oluşturulur. Bunları kabul etme System.Text.Json hakkında bilgi için bkz . Açıklamalara ve sondaki virgüllere izin verme. Birden çok sondaki virgüle izin vermenin bir yolu yoktur.

Dönüştürücü kaydı önceliği

Newtonsoft.Json Özel dönüştürücüler için kayıt önceliği aşağıdaki gibidir:

Bu sıra, koleksiyondaki özel dönüştürücülerin Converters tür düzeyinde bir öznitelik uygulanarak kaydedilen bir dönüştürücü tarafından geçersiz kılındığı anlamına gelir. Bu kayıtların her ikisi de özellik düzeyindeki bir öznitelik tarafından geçersiz kılınıyor.

System.Text.Json Özel dönüştürücüler için kayıt önceliği farklıdır:

  • Özellikte öznitelik
  • Converters Koleksiyon
  • Türdeki öznitelik

Buradaki fark, koleksiyondaki özel dönüştürücülerin Converters tür düzeyinde bir özniteliği geçersiz kılmalarıdır. Bu öncelik sırasının ardındaki amaç, çalışma zamanı değişikliklerini tasarım zamanı seçimlerini geçersiz kılmaktır. Önceliği değiştirmenin hiçbir yolu yoktur.

Özel dönüştürücü kaydı hakkında daha fazla bilgi için bkz . Özel dönüştürücü kaydetme.

Maksimum derinlik

en son sürümü Newtonsoft.Json varsayılan olarak en fazla 64 derinlik sınırına sahiptir. System.Text.Json ayrıca varsayılan sınırı 64'tür ve ayarıyla JsonSerializerOptions.MaxDepthyapılandırılabilir.

ASP.NET Core kullanarak dolaylı olarak kullanıyorsanız System.Text.Json varsayılan maksimum derinlik sınırı 32'dir. Varsayılan değer model bağlama ile aynıdır ve JsonOptions sınıfında ayarlanır.

JSON dizeleri (özellik adları ve dize değerleri)

Seri durumdan çıkarma sırasında, Newtonsoft.Json çift tırnak içine, tek tırnak işaretiyle veya tırnak işareti olmadan özellik adlarını kabul eder. Çift tırnak veya tek tırnak içinde dize değerlerini kabul eder. Örneğin, Newtonsoft.Json aşağıdaki JSON'ı kabul eder:

{
  "name1": "value",
  'name2': "value",
  name3: 'value'
}

System.Text.JsonYalnızca özellik adlarını ve dize değerlerini çift tırnak içinde kabul eder çünkü bu biçim RFC 8259 belirtimi tarafından gereklidir ve geçerli JSON olarak kabul edilen tek biçimdir.

Tek tırnak içine alınmış bir değer, aşağıdaki iletiyi içeren bir JsonException ile sonuçlanır:

''' is an invalid start of a value.

Dize özellikleri için dize olmayan değerler

Newtonsoft.Json , dize türündeki özelliklere seri durumdan çıkarma için sayı veya değişmez değerler true ve falsegibi dize dışı değerleri kabul eder. Aşağıda, aşağıdaki sınıfa başarıyla seri durumdan çıkaran Newtonsoft.Json bir JSON örneği verilmiştir:

{
  "String1": 1,
  "String2": true,
  "String3": false
}

public class ExampleClass
{
    public string String1 { get; set; }
    public string String2 { get; set; }
    public string String3 { get; set; }
}

System.Text.Json dize dışı değerleri dize özelliklerine seri durumdan çıkarmaz. Dize alanı için alınan dize olmayan bir değer, aşağıdaki iletiyle JsonException sonucunu verir:

The JSON value could not be converted to System.String.

JsonSerializer kullanan senaryolar

Aşağıdaki senaryolardan bazıları yerleşik işlevler tarafından desteklenmez, ancak geçici çözümler mümkündür. Geçici çözümler, işlevsellikle Newtonsoft.Json tam eşlik sağlayabilen özel dönüştürücülerdir. Bunlardan bazıları için örnek kod örnek olarak sağlanır. Bu Newtonsoft.Json özelliklere güveniyorsanız, geçiş için .NET nesne modellerinizde veya diğer kod değişikliklerinizde değişiklik yapılması gerekir.

Aşağıdaki senaryolardan bazıları için geçici çözümler pratik veya mümkün değildir. Bu Newtonsoft.Json özelliklere güveniyorsanız, önemli değişiklikler olmadan geçiş mümkün olmayacaktır.

Tırnak içinde numaralara izin verme veya sayı yazma

Newtonsoft.Json JSON dizeleriyle temsil edilen sayıları seri hale getirebilir veya seri durumdan çıkarabilir (tırnak içine alınır). Örneğin, şunu kabul edebilir: {"DegreesCelsius":"23"} yerine {"DegreesCelsius":23}. içinde System.Text.Jsonbu davranışı etkinleştirmek için veya AllowReadingFromStringolarak ayarlayın WriteAsStringJsonSerializerOptions.NumberHandling veya [JsonNumberHandling] özniteliğini kullanın.

ASP.NET Core kullanarak dolaylı olarak kullanıyorsanız System.Text.Json , gibi Newtonsoft.Jsonbir davranış elde etmek için hiçbir şey yapmanız gerekmez. ASP.NET Core, kullandığında System.Text.Jsonweb varsayılanlarını belirtir ve web varsayılanları alıntılanan sayılara izin verir.

Daha fazla bilgi için bkz . Tırnak içinde sayılara izin verme veya bunları yazma.

Seri durumdan çıkarırken kullanılacak oluşturucuyu belirtme

özniteliği, Newtonsoft.Json[JsonConstructor] BIR POCO'ya seri durumdan çıkarılırken hangi oluşturucunun çağrılacağını belirtmenize olanak tanır.

System.Text.Json ayrıca [ JsonConstructor] özniteliğine sahiptir. Daha fazla bilgi için bkz . Sabit türler ve Kayıtlar.

Bir özelliği koşullu olarak yoksayma

Newtonsoft.Json serileştirme veya seri durumdan çıkarmada bir özelliği koşullu olarak yoksaymanın çeşitli yolları vardır:

  • DefaultContractResolver rastgele ölçütlere göre dahil etmek veya yoksaymak için özellikleri seçmenize olanak tanır.
  • üzerindeki NullValueHandlingJsonSerializerSettings ve DefaultValueHandling ayarları, tüm null-değer veya varsayılan değer özelliklerinin yoksayılacağını belirtmenize olanak sağlar.
  • NullValueHandling özniteliğindeki [JsonProperty] ve DefaultValueHandling ayarları, null veya varsayılan değer olarak ayarlandığında yoksayılması gereken tek tek özellikleri belirtmenize olanak sağlar.

System.Text.Json seri hale getirme sırasında özellikleri veya alanları yoksaymak için aşağıdaki yolları sağlar:

Buna ek olarak, .NET 7 ve sonraki sürümlerde JSON sözleşmesini, rastgele ölçütlere göre özellikleri yoksayacak şekilde özelleştirebilirsiniz. Daha fazla bilgi için bkz . Özel sözleşmeler.

Bu seçenekler , çalışma zamanında değerlendirilen rastgele ölçütlere göre seçili özellikleri yoksaymanıza izin vermez .

Genel ve genel olmayan alanlar

Newtonsoft.Json hem alanları hem de özellikleri serileştirebilir ve seri durumdan çıkarabilirsiniz.

içindeSystem.Text.Json, seri hale getirme veya seri durumdan çıkarma sırasında genel alanları eklemek için genel ayarı veya [JsonInclude] özniteliğini kullanınJsonSerializerOptions.IncludeFields. Örnek için bkz . Alanları ekleme.

Nesne başvurularını ve tanıtıcı döngülerini koruma

Varsayılan olarak, Newtonsoft.Json değere göre serileştirir. Örneğin, bir nesne aynı Person nesneye başvuru içeren iki özellik içeriyorsa, bu Person nesnenin özelliklerinin değerleri JSON'da yinelenir.

Newtonsoft.Json, başvuruya JsonSerializerSettings göre seri hale getirmenizi sağlayan bir PreserveReferencesHandling ayara sahiptir:

  • İlk Person nesne için oluşturulan JSON'a bir tanımlayıcı meta verileri eklenir.
  • İkinci Person nesne için oluşturulan JSON, özellik değerleri yerine bu tanımlayıcıya bir başvuru içerir.

Newtonsoft.Json ayrıca özel ReferenceLoopHandling durum oluşturmak yerine döngüsel başvuruları yoksaymanıza olanak tanıyan bir ayarı vardır.

içindeki başvuruları korumak ve döngüsel başvuruları System.Text.Jsonişlemek için olarak PreserveayarlayınJsonSerializerOptions.ReferenceHandler. ayarı ReferenceHandler.Preserve ile Newtonsoft.JsoneşdeğerdirPreserveReferencesHandling = PreserveReferencesHandling.All.

seçeneğine ReferenceHandler.IgnoreCycles benzer bir davranışa Newtonsoft.JsonReferenceLoopHandling.Ignoresahiptir. Bir fark, uygulamanın nesne başvuruyu System.Text.Json yoksaymak yerine başvuru döngülerini JSON belirteci ile null değiştirmesidir. Daha fazla bilgi için bkz . Döngüsel başvuruları yoksayma.

Newtonsoft.JsonReferenceResolver gibi sınıfı da System.Text.Json.Serialization.ReferenceResolver serileştirme ve seri durumdan çıkarma üzerinde başvuruları koruma davranışını tanımlar. Özel davranışı belirtmek için türetilmiş bir sınıf oluşturun. Örnek için bkz . GuidReferenceResolver.

bazı ilgili Newtonsoft.Json özellikler desteklenmez:

Daha fazla bilgi için bkz . Başvuruları koruma ve döngüsel başvuruları işleme.

Dize olmayan anahtar içeren sözlük

System.Text.Json Hem hem de Newtonsoft.Json türünde Dictionary<TKey, TValue>koleksiyonları destekler. Ancak, içinde System.Text.JsonTKey özel bir tür değil, ilkel bir tür olmalıdır. Daha fazla bilgi için bkz . Desteklenen anahtar türleri.

Dikkat

Bir yerine TKeystring seri durumdan Dictionary<TKey, TValue> çıkarma işlemi, tüketen uygulamada güvenlik açığına neden olabilir. Daha fazla bilgi için bkz . dotnet/runtime#4761.

Yerleşik destek olmadan türler

System.Text.Json aşağıdaki türler için yerleşik destek sağlamaz:

Yerleşik desteği olmayan türler için özel dönüştürücüler uygulanabilir.

Polimorfik serileştirme

Newtonsoft.Json otomatik olarak polimorfik serileştirme yapar. .NET 7'den başlayarak özniteliği System.Text.Json aracılığıyla çok biçimli serileştirmeyi JsonDerivedTypeAttribute destekler. Daha fazla bilgi için bkz . Türetilmiş sınıfların özelliklerini seri hale getirme.

Polimorfik seri durumdan çıkarma

Newtonsoft.Json , serileştirme sırasında JSON'a tür adı meta verileri ekleyen bir TypeNameHandling ayara sahiptir. Seri durumdan çıkarırken meta verileri kullanarak polimorfik seri durumdan çıkarma işlemi yapar. .NET 7'den başlayarak, System.Text.Json polimorfik seri durumdan çıkarma gerçekleştirmek için tür ayrıştırıcı bilgilerine dayanır. Bu meta veriler JSON'da yayılır ve ardından seri durumdan çıkarma sırasında temel türe mi yoksa türetilmiş bir türe mi seri durumdan çıkarılmayacağını belirlemek için kullanılır. Daha fazla bilgi için bkz . Türetilmiş sınıfların özelliklerini seri hale getirme.

Eski .NET sürümlerinde polimorfik seri durumdan çıkarmayı desteklemek için Özel dönüştürücüler yazma'daki örneğe benzer bir dönüştürücü oluşturun.

Dize sabit listesi değerlerini seri durumdan çıkarma

Varsayılan olarak, System.Text.Json dize sabit listesi değerlerini seri durumdan çıkarma desteği sunmaz, ancak Newtonsoft.Json bunu destekler. Örneğin, aşağıdaki kod bir JsonExceptionoluşturur:

string json = "{ \"Text\": \"Hello\", \"Enum\": \"Two\" }";
var _ = JsonSerializer.Deserialize<MyObj>(json); // Throws exception.

class MyObj
{
    public string Text { get; set; } = "";
    public MyEnum Enum { get; set; }
}

enum MyEnum
{
    One,
    Two,
    Three
}

Ancak, dönüştürücü kullanarak dize sabit listesi değerlerinin seri durumdan çıkarılabilmesini JsonStringEnumConverter sağlayabilirsiniz. Daha fazla bilgi için bkz . Dize olarak numaralandırmalar.

Nesne özelliklerinin seri durumdan çıkarılması

için seri durumdan ObjectçıkarıldığındaNewtonsoft.Json:

  • JSON yükündeki ilkel değerlerin türünü (dışında null) çıkarsar ve depolanan string, long, double, booleanveya DateTime öğesini kutulanmış nesne olarak döndürür. İlkel değerler , JSON numarası, dize true, , falseveya nullgibi tek JSON değerleridir.
  • JSON yükündeki karmaşık değerler için veya JObjectJArray döndürür. Karmaşık değerler , küme ayraçları ({}) içindeki JSON anahtar-değer çiftlerinin koleksiyonları veya köşeli ayraçlar ([]) içindeki değer listeleridir. Ayraçlar veya köşeli ayraçlar içindeki özellikler ve değerler ek özelliklere veya değerlere sahip olabilir.
  • Yükte null JSON değişmez değeri olduğunda null başvuru döndürür.

System.Text.Jsonolarak seri durumdan Objectçıkarıldığında hem ilkel hem de karmaşık değerler için kutulu JsonElement depolar, örneğin:

  • Bir object özellik.
  • Sözlük object değeri.
  • Bir object dizi değeri.
  • Bir kök object.

Ancak, System.Text.Json yükün içinde JSON değişmez değeri olduğunda null ile aynı Newtonsoft.Json şekilde davranır null ve null başvuru döndürür.

Özellikler için tür çıkarımı uygulamak içinobject, Özel dönüştürücüler yazma'daki örneğe benzer bir dönüştürücü oluşturun.

Null'ı null olmayan türe seri durumdan çıkarma

Newtonsoft.Json aşağıdaki senaryoda bir özel durum oluşturmaz:

  • NullValueHandling , ve olarak Ignoreayarlanır
  • Seri durumdan çıkarma sırasında JSON, boş değer atanamayan bir değer türü için null değer içerir.

Aynı senaryoda, System.Text.Json bir özel durum oluşturur. (içindeki System.Text.Json karşılık gelen null işleme ayarıdır JsonSerializerOptions.IgnoreNullValues = true.)

Hedef türün sahibiyseniz, en iyi geçici çözüm söz konusu özelliğin null atanabilir olmasını sağlamaktır (örneğin, olarak değiştirin intint?).

Başka bir geçici çözüm türü için bir dönüştürücü oluşturmaktır; örneğin, türler için DateTimeOffset null değerleri işleyen aşağıdaki örnek:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class DateTimeOffsetNullHandlingConverter : JsonConverter<DateTimeOffset>
    {
        public override DateTimeOffset Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options) =>
            reader.TokenType == JsonTokenType.Null
                ? default
                : reader.GetDateTimeOffset();

        public override void Write(
            Utf8JsonWriter writer,
            DateTimeOffset dateTimeValue,
            JsonSerializerOptions options) =>
            writer.WriteStringValue(dateTimeValue);
    }
}

Özelliğinde bir öznitelik kullanarak veya dönüştürücüsü koleksiyona ekleyerek bu özel dönüştürücüye Converters kaydedin.

Not: Yukarıdaki dönüştürücü null değerleri varsayılan değerleri belirten POCO'lardan farklıNewtonsoft.Json işler. Örneğin, aşağıdaki kodun hedef nesnenizi temsil ettiği varsayın:

public class WeatherForecastWithDefault
{
    public WeatherForecastWithDefault()
    {
        Date = DateTimeOffset.Parse("2001-01-01");
        Summary = "No summary";
    }
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}

Yukarıdaki dönüştürücü kullanılarak aşağıdaki JSON'un seri durumdan çıkarıldığını varsayalım:

{
  "Date": null,
  "TemperatureCelsius": 25,
  "Summary": null
}

Seri durumdan çıkarma işleminden Date sonra özelliğin 1/1/0001 ()default(DateTimeOffset) değeri vardır; yani oluşturucuda ayarlanan değerin üzerine yazılır. Aynı POCO ve JSON göz önünde bulundurulduğunda seri Newtonsoft.Json durumdan çıkarma özelliğinde 1/1/2001'i Date bırakır.

Sabit sınıflar ve yapılar için seri durumdan çıkarma

Newtonsoft.Json sabit sınıflar ve yapılar için seri durumdan çıkarabilirsiniz çünkü parametreleri olan oluşturucuları kullanabilir.

içinde System.Text.Json, parametreli bir oluşturucunun kullanımını belirtmek için [JsonConstructor] özniteliğini kullanın. C# 9'daki kayıtlar da sabittir ve seri durumdan çıkarma hedefleri olarak desteklenir. Daha fazla bilgi için bkz . Sabit türler ve Kayıtlar.

Gerekli özellikler

içinde Newtonsoft.Jsonözniteliğini ayarlayarak Required bir özelliğin [JsonProperty] gerekli olduğunu belirtirsiniz. Newtonsoft.Json JSON'da gerekli olarak işaretlenmiş bir özellik için değer alınmazsa bir özel durum oluşturur.

.NET 7'den başlayarak, gerekli bir özellikte C# required değiştiricisini JsonRequiredAttribute veya özniteliğini kullanabilirsiniz. System.Text.Json JSON yükü işaretli özellik için bir değer içermiyorsa bir özel durum oluşturur. Daha fazla bilgi için bkz . Gerekli özellikler.

System.Text.Json hedef türün özelliklerinden biri için değer alınmadıysa özel durum oluşturmaz. Örneğin, bir WeatherForecast sınıfınız varsa:

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

Aşağıdaki JSON, hatasız seri durumdan çıkarılır:

{
    "TemperatureCelsius": 25,
    "Summary": "Hot"
}

JSON'da özellik yoksa Date seri durumdan çıkarmanın başarısız olmasını sağlamak için aşağıdaki seçeneklerden birini belirleyin:

Seri durumdan çıkarma tamamlandıktan sonra özellik ayarlanmazsa Date aşağıdaki örnek dönüştürücü kodu bir özel durum oluşturur:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class WeatherForecastRequiredPropertyConverter : JsonConverter<WeatherForecast>
    {
        public override WeatherForecast Read(
            ref Utf8JsonReader reader,
            Type type,
            JsonSerializerOptions options)
        {
            // Don't pass in options when recursively calling Deserialize.
            WeatherForecast forecast = JsonSerializer.Deserialize<WeatherForecast>(ref reader)!;

            // Check for required fields set by values in JSON
            return forecast!.Date == default
                ? throw new JsonException("Required property not received in the JSON")
                : forecast;
        }

        public override void Write(
            Utf8JsonWriter writer,
            WeatherForecast forecast, JsonSerializerOptions options)
        {
            // Don't pass in options when recursively calling Serialize.
            JsonSerializer.Serialize(writer, forecast);
        }
    }
}

Dönüştürücüsü koleksiyona ekleyerek bu özel dönüştürücüyeJsonSerializerOptions.Converters kaydedin.

Dönüştürücüsünün özyinelemeli olarak çağrılması için dönüştürücü bir öznitelik kullanarak değil kullanarak JsonSerializerOptionskaydedilmesi gerekir. Dönüştürücü bir öznitelik kullanarak kaydederseniz, özel dönüştürücü özyinelemeli olarak kendisini çağırır. Sonuç, yığın taşması özel durumuyla biten sonsuz bir döngüdür.

Dönüştürücüsü options nesnesini kullanarak kaydettiğinizde, veya Deserializeöğesini özyinelemeli olarak çağırırken Serialize options nesnesini geçirmeyerek sonsuz bir döngüden kaçının. options nesnesi koleksiyonu içerir Converters . veya Deserializeiçine Serialize geçirirseniz, özel dönüştürücü kendi kendine çağrı yaparak yığın taşması özel durumuyla sonuçlayan sonsuz bir döngü oluşturur. Varsayılan seçenekler uygun değilse, ihtiyacınız olan ayarlarla seçeneklerin yeni bir örneğini oluşturun. Her yeni örnek bağımsız olarak önbelleğe alındığından bu yaklaşım yavaş olacaktır.

Dönüştürülecek sınıfta kaydı kullanabilen JsonConverterAttribute alternatif bir desen vardır. Bu yaklaşımda dönüştürücü kodu, dönüştürülecek Deserialize sınıfından türetilen bir sınıfı çağırırSerialize. Türetilmiş sınıf JsonConverterAttribute buna uygulanmamış. Bu alternatifin aşağıdaki örneğinde:

  • WeatherForecastWithRequiredPropertyConverterAttribute seri durumdan çıkarılacak sınıftır ve JsonConverterAttribute bu sınıfa uygulanmıştır.
  • WeatherForecastWithoutRequiredPropertyConverterAttribute , dönüştürücü özniteliğine sahip olmayan türetilmiş sınıftır.
  • Dönüştürücüdeki kod, sonsuz döngüden kaçınmak için öğesini çağırırSerialize.DeserializeWeatherForecastWithoutRequiredPropertyConverterAttribute Ek nesne örneği oluşturma ve özellik değerlerini kopyalama nedeniyle serileştirmede bu yaklaşımın bir performans maliyeti vardır.

Türleri şunlardır WeatherForecast* :

[JsonConverter(typeof(WeatherForecastRequiredPropertyConverterForAttributeRegistration))]
public class WeatherForecastWithRequiredPropertyConverterAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

public class WeatherForecastWithoutRequiredPropertyConverterAttribute :
    WeatherForecastWithRequiredPropertyConverterAttribute
{
}

Dönüştürücü de şu şekildedir:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class WeatherForecastRequiredPropertyConverterForAttributeRegistration :
        JsonConverter<WeatherForecastWithRequiredPropertyConverterAttribute>
    {
        public override WeatherForecastWithRequiredPropertyConverterAttribute Read(
            ref Utf8JsonReader reader,
            Type type,
            JsonSerializerOptions options)
        {
            // OK to pass in options when recursively calling Deserialize.
            WeatherForecastWithRequiredPropertyConverterAttribute forecast =
                JsonSerializer.Deserialize<WeatherForecastWithoutRequiredPropertyConverterAttribute>(
                    ref reader,
                    options)!;

            // Check for required fields set by values in JSON.
            return forecast!.Date == default
                ? throw new JsonException("Required property not received in the JSON")
                : forecast;
        }

        public override void Write(
            Utf8JsonWriter writer,
            WeatherForecastWithRequiredPropertyConverterAttribute forecast,
            JsonSerializerOptions options)
        {
            var weatherForecastWithoutConverterAttributeOnClass =
                new WeatherForecastWithoutRequiredPropertyConverterAttribute
                {
                    Date = forecast.Date,
                    TemperatureCelsius = forecast.TemperatureCelsius,
                    Summary = forecast.Summary
                };

            // OK to pass in options when recursively calling Serialize.
            JsonSerializer.Serialize(
                writer,
                weatherForecastWithoutConverterAttributeOnClass,
                options);
        }
    }
}

[JsonIgnore] gibi öznitelikleri veya özel kodlayıcılar gibi farklı seçenekleri işlemeniz gerekiyorsa gerekli özellikler dönüştürücüsü ek mantık gerektirir. Ayrıca örnek kod, oluşturucuda varsayılan değerin ayarlandığı özellikleri işlemez. Ve bu yaklaşım aşağıdaki senaryolar arasında ayrım yapmaz:

  • JSON'da bir özellik eksik.
  • JSON'da null atanamayan bir tür için bir özellik vardır, ancak değer türü için varsayılan değerdir; örneğin, bir intiçin sıfır.
  • JSON'da null değer türü için bir özellik var, ancak değer null.

Not

ASP.NET Core denetleyicisinden kullanıyorsanızSystem.Text.Json, dönüştürücü uygulamak yerine model sınıfının özelliklerinde bir System.Text.Json öznitelik kullanabilirsiniz[Required].

Tarih biçimini belirtme

Newtonsoft.Jsonve DateTimeOffset türlerinin özelliklerinin nasıl serileştirilip seri durumdan DateTime çıkarıldığını denetlemek için çeşitli yollar sağlar:

  • Ayar DateTimeZoneHandling , tüm DateTime değerleri UTC tarihleri olarak seri hale getirmek için kullanılabilir.
  • Ayar DateFormatString ve DateTime dönüştürücüler, tarih dizelerinin biçimini özelleştirmek için kullanılabilir.

System.Text.Json RFC 3339 profili de dahil olmak üzere ISO 8601-1:2019'ı destekler. Bu biçim yaygın olarak benimsenmiş, net değildir ve gidiş dönüşleri hassas bir şekilde yapar. Başka bir biçim kullanmak için özel bir dönüştürücü oluşturun. Örneğin, aşağıdaki dönüştürücüler, saat dilimi uzaklığı (veya gibi /Date(1590863400000-0700)//Date(1590863400000)/değerler) ile veya olmadan Unix dönem biçimini kullanan JSON'ı seri hale getirip seri durumdan çıkartır:

sealed class UnixEpochDateTimeOffsetConverter : JsonConverter<DateTimeOffset>
{
    static readonly DateTimeOffset s_epoch = new(1970, 1, 1, 0, 0, 0, TimeSpan.Zero);
    static readonly Regex s_regex = new("^/Date\\(([+-]*\\d+)([+-])(\\d{2})(\\d{2})\\)/$", RegexOptions.CultureInvariant);

    public override DateTimeOffset Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        string formatted = reader.GetString()!;
        Match match = s_regex.Match(formatted);

        if (
                !match.Success
                || !long.TryParse(match.Groups[1].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime)
                || !int.TryParse(match.Groups[3].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out int hours)
                || !int.TryParse(match.Groups[4].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out int minutes))
        {
            throw new JsonException();
        }

        int sign = match.Groups[2].Value[0] == '+' ? 1 : -1;
        TimeSpan utcOffset = new(hours * sign, minutes * sign, 0);

        return s_epoch.AddMilliseconds(unixTime).ToOffset(utcOffset);
    }

    public override void Write(Utf8JsonWriter writer, DateTimeOffset value, JsonSerializerOptions options)
    {
        long unixTime = Convert.ToInt64((value - s_epoch).TotalMilliseconds);
        TimeSpan utcOffset = value.Offset;

        string formatted = string.Create(CultureInfo.InvariantCulture, $"/Date({unixTime}{(utcOffset >= TimeSpan.Zero ? "+" : "-")}{utcOffset:hhmm})/");

        writer.WriteStringValue(formatted);
    }
}

sealed class UnixEpochDateTimeConverter : JsonConverter<DateTime>
{
    static readonly DateTime s_epoch = new(1970, 1, 1, 0, 0, 0);
    static readonly Regex s_regex = new("^/Date\\(([+-]*\\d+)\\)/$", RegexOptions.CultureInvariant);

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        string formatted = reader.GetString()!;
        Match match = s_regex.Match(formatted);

        if (
                !match.Success
                || !long.TryParse(match.Groups[1].Value, System.Globalization.NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime))
        {
            throw new JsonException();
        }

        return s_epoch.AddMilliseconds(unixTime);
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        long unixTime = Convert.ToInt64((value - s_epoch).TotalMilliseconds);

        string formatted = string.Create(CultureInfo.InvariantCulture, $"/Date({unixTime})/");
        writer.WriteStringValue(formatted);
    }
}

Daha fazla bilgi için, içindeki DateTime ve DateTimeOffset desteğine System.Text.Jsonbakın.

Geri Çağırmalar

Newtonsoft.Json serileştirme veya seri durumdan çıkarma işleminin birkaç noktasında özel kod yürütmenize olanak tanır:

  • OnDeserializing (bir nesnenin seri durumdan çıkarılmasına başlarken)
  • OnDeserialized (bir nesnenin seri durumdan çıkarılması tamamlandığında)
  • OnSerializing (bir nesneyi serileştirmeye başlarken)
  • OnSerialized (bir nesneyi seri hale getirme tamamlandığında)

System.Text.Json serileştirme ve seri durumdan çıkarma sırasında aynı bildirimleri kullanıma sunar. Bunları kullanmak için ad alanından aşağıdaki arabirimlerden System.Text.Json.Serialization birini veya daha fazlasını uygulayın:

Aşağıda null bir özelliği denetleyebilen ve serileştirme ile seri durumdan çıkarmanın başında ve sonunda iletiler yazan bir örnek verilmiştir:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace Callbacks
{
    public class WeatherForecast : 
        IJsonOnDeserializing, IJsonOnDeserialized, 
        IJsonOnSerializing, IJsonOnSerialized
    {
        public DateTime Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }

        void IJsonOnDeserializing.OnDeserializing() => Console.WriteLine("\nBegin deserializing");
        void IJsonOnDeserialized.OnDeserialized()
        {
            Validate();
            Console.WriteLine("Finished deserializing");
        }
        void IJsonOnSerializing.OnSerializing()
        {
            Console.WriteLine("Begin serializing");
            Validate();
        }
        void IJsonOnSerialized.OnSerialized() => Console.WriteLine("Finished serializing");

        private void Validate()
        {
            if (Summary is null)
            {
                Console.WriteLine("The 'Summary' property is 'null'.");
            }
        }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
            };

            string jsonString = JsonSerializer.Serialize(weatherForecast);
            Console.WriteLine(jsonString);

            weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString);
            Console.WriteLine($"Date={weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius={weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary={weatherForecast?.Summary}");
        }
    }
}
// output:
//Begin serializing
//The 'Summary' property is 'null'.
//Finished serializing
//{"Date":"2019-08-01T00:00:00","TemperatureCelsius":25,"Summary":null}

//Begin deserializing
//The 'Summary' property is 'null'.
//Finished deserializing
//Date=8/1/2019 12:00:00 AM
//TemperatureCelsius = 25
//Summary=

Kodun OnDeserializing yeni POCO örneğine erişimi yoktur. Seri durumdan çıkarmanın başlangıcında yeni POCO örneğini işlemek için bu kodu POCO oluşturucusunda yerleştirin.

Ortak olmayan özellik ayarlayıcıları ve alıcıları

Newtonsoft.Json özniteliği aracılığıyla JsonProperty özel ve iç özellik ayarlayıcılarını ve alıcılarını kullanabilir.

System.Text.Json[JsonInclude] özniteliği aracılığıyla özel ve iç özellik ayarlayıcılarını ve alıcıları destekler. Örnek kod için bkz . Ortak olmayan özellik erişimcileri.

Varolan nesneleri doldurma

JsonConvert.PopulateObject içindeki Newtonsoft.Json yöntemi, JSON belgesini yeni bir örnek oluşturmak yerine mevcut bir sınıf örneğine seri durumdan çıkartır. System.Text.Json her zaman varsayılan genel parametresiz oluşturucuyu kullanarak hedef türün yeni bir örneğini oluşturur. Özel dönüştürücüler var olan bir örneğe seri durumdan çıkarılabilir.

Özellikleri değiştirmek yerine yeniden kullanma

.NET 8'den başlayarak, System.Text.Json başlatılan özellikleri değiştirmek yerine yeniden kullanma desteğine sahiptir. API teklifinde okuyabileceğiniz bazı davranış farklılıkları vardır.

Daha fazla bilgi için bkz . Başlatılan özellikleri doldurma.

ObjectCreationHandling içindeki Newtonsoft.Json ayarı, seri durumdan çıkarma sırasında yerine özelliklerdeki nesnelerin yeniden kullanılmasını belirtmenize olanak tanır. System.Text.Json her zaman özelliklerdeki nesneleri değiştirir. Özel dönüştürücüler bu işlevselliği sağlayabilir veya doldurma işlevselliği sağlayan .NET 8'e yükseltebilirsiniz.

Özellikleri ayarlayıcılar olmadan doldurma

.NET 8'den başlayarak, System.Text.Json ayarlayıcıya sahip olmayanlar da dahil olmak üzere özellikleri doldurmayı destekler. Daha fazla bilgi için bkz . Başlatılan özellikleri doldurma.

Seri durumdan çıkarma sırasında, Newtonsoft.Json özelliğinde ayarlayıcı olmasa bile nesneleri bir koleksiyona ekler. System.Text.Json ayarlayıcıları olmayan özellikleri yoksayar. Özel dönüştürücüler bu işlevselliği sağlayabilir veya salt okunur özellikleri doldurabilen .NET 8'e yükseltebilirsiniz.

Yılan olayı adlandırma ilkesi

System.Text.Json yılan örneği için yerleşik bir adlandırma ilkesi içerir. Ancak, bazı girişler için ile Newtonsoft.Json bazı davranış farklılıkları vardır. Aşağıdaki tabloda, ilke kullanılarak giriş dönüştürülürken bu farklardan bazıları gösterilmektedir JsonNamingPolicy.SnakeCaseLower .

Giriş Newtonsoft.Json Sonuç System.Text.Json Sonuç
"AB1" "a_b1" "ab1"
"SHA512Managed" "sh_a512_managed" "sha512_managed"
"abc123DEF456" "abc123_de_f456" "abc123_def456"
"KEBAB-CASE" "keba_b-_case" "kebab-case"

içindeki tek yerleşik özellik adlandırma ilkesi System.Text.Json , deve olayı içindir. Newtonsoft.Json özellik adlarını yılan durumuna dönüştürebilir. Özel adlandırma ilkesi bu işlevselliği sağlayabilir veya yerleşik yılan örneği adlandırma ilkelerini içeren .NET 8 veya sonraki bir sürüme yükseltebilir.

System.Runtime.Serialization öznitelikleri

System.Runtime.Serializationgibi öznitelikler DataContractAttributeDataMemberAttributeIgnoreDataMemberAttribute ve bir veri sözleşmesi tanımlamanızı sağlar. Veri sözleşmesi, bir hizmet ile istemci arasında değiş tokuş edilecek verileri soyut olarak açıklayan resmi bir anlaşmadır. Veri sözleşmesi, hangi özelliklerin değişim için seri hale getirildiği kesin olarak tanımlar.

System.Text.Json bu öznitelikler için yerleşik desteğe sahip değildir. Ancak, .NET 7'den başlayarak, destek eklemek için özel bir tür çözümleyici kullanabilirsiniz. Örnek için bkz . ZCS. DataContractResolver.

Sekizli sayılar

Newtonsoft.Json sayıları baştaki sıfırla sekizli sayılar olarak ele alır. System.Text.JsonRFC 8259 belirtimi bunlara izin vermediğinden baştaki sıfırlara izin vermez.

Eksik üyeleri işleme

Seri durumdan çıkarılmakta olan JSON hedef türünde eksik özellikler içeriyorsa, Newtonsoft.Json özel durumlar oluşturacak şekilde yapılandırılabilir. Varsayılan olarak, System.Text.Json [JsonExtensionData] özniteliğini kullanmanız dışında JSON'daki ek özellikleri yoksayar.

.NET 8 ve sonraki sürümlerde, aşağıdaki araçlardan birini kullanarak eşlenmemiş JSON özelliklerini atlayıp atlayıp atlamama tercihinizi ayarlayabilirsiniz:

JsonObjectAttribute

Newtonsoft.Json, hangi üyelerin seri hale getirildiğini, JsonObjectAttributedeğerlerin nasıl null işleneceğini ve tüm üyelerin gerekli olup olmadığını denetlemek için tür düzeyinde uygulanabilen bir özniteliğine sahiptir. System.Text.Json bir türe uygulanabilecek eşdeğer bir özniteliği yoktur. Değer işleme gibi null bazı davranışlar için aynı davranışı genelde JsonSerializerOptions veya her özellikte tek tek yapılandırabilirsiniz.

Tüm null özelliklerin yoksayılması gerektiğini belirtmek için aşağıdaki örneği göz Newtonsoft.Json.JsonObjectAttribute önünde bulundurun:

[JsonObject(ItemNullValueHandling = NullValueHandling.Ignore)]
public class Person { ... }

içindeSystem.Text.Json, tüm türler ve özellikler için davranışı ayarlayabilirsiniz:

JsonSerializerOptions options = new()
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

string json = JsonSerializer.Serialize<Person>(person, options);

Ya da her özellikte davranışı ayrı olarak ayarlayabilirsiniz:

public class Person
{
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public string? Name { get; set; }

    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public int? Age { get; set; }
}

Ardından, tüm üye özelliklerinin JSON'da mevcut olması gerektiğini belirtmek için kullanan Newtonsoft.Json.JsonObjectAttribute aşağıdaki örneği göz önünde bulundurun:

[JsonObject(ItemRequired = Required.Always)]
public class Person { ... }

C# required değiştiricisini veyaJsonRequiredAttribute öğesini her özelliğe ekleyerek içinde aynı davranışı System.Text.Json elde edebilirsiniz. Daha fazla bilgi için bkz . Gerekli özellikler.

public class Person
{
    [JsonRequired]
    public string? Name { get; set; }

    public required int? Age { get; set; }
}

TraceWriter

Newtonsoft.Json , serileştirme veya seri durumdan çıkarma tarafından oluşturulan günlükleri görüntülemek için kullanarak TraceWriter hata ayıklamanıza olanak tanır. System.Text.Json günlüğe kaydetmez.

JToken ile karşılaştırıldığında JsonDocument ve JsonElement (JObject, JArray gibi)

System.Text.Json.JsonDocumentmevcut JSON yüklerinden salt okunur bir Belge Nesne Modeli (DOM) ayrıştırma ve oluşturma olanağı sağlar. DOM, JSON yükündeki verilere rastgele erişim sağlar. Yükü oluşturan JSON öğelerine türü aracılığıyla JsonElement erişilebilir. Türü, JsonElement JSON metnini yaygın .NET türlerine dönüştürmek için API'ler sağlar. JsonDocument bir RootElement özelliği kullanıma sunar.

.NET 6'dan başlayarak, türü ve ad alanı içindeki System.Text.Json.Nodes diğer türleri kullanarak JsonNode mevcut JSON yüklerinden değiştirilebilir bir DOM ayrıştırabilir ve oluşturabilirsiniz. Daha fazla bilgi için bkz . Kullanma JsonNode.

JsonDocument is IDisposable

JsonDocument havuza alınan arabelleğe verilerin bellek içi görünümünü oluşturur. Bu nedenle, veya JArray türünden Newtonsoft.JsonJsonDocument farklı JObject olarak türü uygular IDisposable ve bir using bloğu içinde kullanılması gerekir. Daha fazla bilgi için bkz . JsonDocument IDisposable.

JsonDocument salt okunur

System.Text.Json DOM, JSON öğelerini ekleyemez, kaldıramaz veya değiştiremez. Bu yöntem, performans ve ortak JSON yük boyutlarını ayrıştırma (1 MB) < için ayırmaları azaltmak için tasarlanmıştır.

JsonElement bir birleşim yapısıdır

JsonDocumentRootElement, herhangi bir JSON öğesini kapsayan bir birleşim yapısı türü olan türünün JsonElementözelliği olarak kullanıma sunar. Newtonsoft.JsongibiJArrayJToken ayrılmış hiyerarşik türler JObjectkullanır. JsonElement üzerinde arama yapabilir ve numaralandırabilir ve JSON öğelerini .NET türlerine dönüştürebilmek için kullanabilirsiniz JsonElement .

.NET 6'dan başlayarak, ad alanında System.Text.Json.Nodes ve öğesine karşılık gelen JObjecttür ve JTokentürleri kullanabilirsinizJsonNodeJArray. Daha fazla bilgi için bkz . Kullanma JsonNode.

Bir JsonDocument ve JsonElement'de alt öğeler için arama

kullanarak JObject veya JArrayNewtonsoft.Json kullanarak JSON belirteçleri için yapılan aramalar, bazı sözlüklerde aramalar olduğundan görece hızlı olma eğilimindedir. Karşılaştırmak gerekirse, üzerindeki JsonElement aramalar özelliklerin sıralı bir aramasını gerektirir ve bu nedenle nispeten yavaştır (örneğin kullanırken TryGetProperty). System.Text.Json arama zamanı yerine ilk ayrıştırma süresini en aza indirmek için tasarlanmıştır. Daha fazla bilgi için bkz . JsonDocument ve JsonElement'de alt öğeleri arama.

Utf8JsonReader ve JsonTextReader karşılaştırması

System.Text.Json.Utf8JsonReader, READOnlySpan baytından> veya ReadOnlySequence<> baytından okunan UTF-8 kodlu JSON metni için yüksek performanslı, düşük ayırmalı, yalnızca ileriye dönük bir okuyucudur.< Utf8JsonReader, özel ayrıştırıcılar ve seri durumdan çıkarıcılar oluşturmak için kullanılabilecek düşük düzeyli bir türüdür.

Utf8JsonReader bir başvuru yapısıdır

in JsonTextReaderNewtonsoft.Json bir sınıftır. Türü Utf8JsonReader , bir başvuru yapısı olması bakımından farklılık gösterir. Daha fazla bilgi için bkz . Utf8JsonReader için başvuru yapısı sınırlamaları.

Null değerleri null değer türlerine okuma

Newtonsoft.Json, döndürerek bool?sizin için bir NullTokenType işleyen gibi ReadAsBoolean, döndüren Nullable<T>API'ler sağlar. Yerleşik API'ler System.Text.Json yalnızca null atanamayan değer türleri döndürür. Daha fazla bilgi için bkz . Null değerleri null değer türlerine okuma.

JSON okumak için çok hedefli

Belirli hedef çerçeveler için kullanmaya Newtonsoft.Json devam etmeniz gerekiyorsa, birden çok hedef oluşturabilir ve iki uygulamanız olabilir. Ancak, bu önemsiz değildir ve bazı #ifdefs ve kaynak yinelemesi gerektirir. Mümkün olduğunca çok kod paylaşmanın bir yolu ve Newtonsoft.Json.JsonTextReaderçevresinde Utf8JsonReader bir ref struct sarmalayıcı oluşturmaktır. Bu sarmalayıcı, davranış farklılıkları yalıtılırken genel yüzey alanını birleştirecektir. Bu, değişiklikleri esas olarak türün yapısında yalıtmanıza ve yeni türü başvuruya göre geçirmenize olanak tanır. Bu, Microsoft.Extensions.DependencyModel kitaplığının izlediği desendir:

Utf8JsonWriter ve JsonTextWriter karşılaştırması

System.Text.Json.Utf8JsonWriter, Int32ve DateTimegibi Stringyaygın .NET türlerinden UTF-8 kodlu JSON metni yazmanın yüksek performanslı bir yoludur. Yazıcı, özel seri hale getiriciler oluşturmak için kullanılabilecek düşük düzeyli bir türdür.

Ham değerler yazma

Newtonsoft.Json bir WriteRawValue değerin beklendiği yerde ham JSON yazan bir yönteme sahiptir. System.Text.Json doğrudan eşdeğeri vardır: Utf8JsonWriter.WriteRawValue. Daha fazla bilgi için bkz . Ham JSON yazma.

JSON biçimini özelleştirme

JsonTextWriter eşdeğeri olmayan aşağıdaki ayarları Utf8JsonWriter içerir:

  • QuoteChar - Dize değerlerini çevrelemek için kullanılacak karakteri belirtir. Utf8JsonWriter her zaman çift tırnak kullanır.
  • QuoteName - Özellik adlarının tırnak içine alınıp alınmayacağını belirtir. Utf8JsonWriter her zaman tırnak içine alır.

.NET 9'dan başlayarak, yapı tarafından JsonWriterOptions sunulan seçenekleri kullanmak için Utf8JsonWriter girinti karakterini ve boyutunu özelleştirebilirsiniz:

  • JsonWriterOptions.IndentCharacter
  • JsonWriterOptions.IndentSize

JsonTextWriter eşdeğeri olmayan aşağıdaki ayarları Utf8JsonWriter içerir:

  • Girinti - Girintilemenin kaç karakter yapılacağını belirtir. Utf8JsonWriter her zaman 2 karakter girintili.
  • IndentChar - Girintileme için kullanılacak karakteri belirtir. Utf8JsonWriter her zaman boşluk kullanır.
  • QuoteChar - Dize değerlerini çevrelemek için kullanılacak karakteri belirtir. Utf8JsonWriter her zaman çift tırnak kullanır.
  • QuoteName - Özellik adlarının tırnak içine alınıp alınmayacağını belirtir. Utf8JsonWriter her zaman tırnak içine alır.

tarafından Utf8JsonWriter üretilen JSON'yi bu yollarla özelleştirmenize olanak sağlayan bir geçici çözüm yoktur.

Zaman aralığı, Uri veya karakter değerleri yazma

JsonTextWriterWriteValue TimeSpan, Uri ve char değerleri için yöntemler sağlar. Utf8JsonWriter eşdeğer yöntemlere sahip değildir. Bunun yerine, bu değerleri dize olarak biçimlendirin (örneğin çağrısı ToString()yaparak) ve çağrısı yapın WriteStringValue.

JSON yazmak için çok hedefli

Belirli hedef çerçeveler için kullanmaya Newtonsoft.Json devam etmeniz gerekiyorsa, birden çok hedef oluşturabilir ve iki uygulamanız olabilir. Ancak, bu önemsiz değildir ve bazı #ifdefs ve kaynak yinelemesi gerektirir. Mümkün olduğunca çok kod paylaşmanın bir yolu ve Newtonsoft.Json.JsonTextWriterçevresinde Utf8JsonWriter bir sarmalayıcı oluşturmaktır. Bu sarmalayıcı, davranış farklılıkları yalıtılırken genel yüzey alanını birleştirecektir. Bu, değişiklikleri esas olarak türün yapısına göre yalıtmanızı sağlar. Microsoft.Extensions.DependencyModel kitaplığı aşağıdaki gibidir:

TypeNameHandling.All desteklenmiyor

-eşdeğer işlevselliği hariç System.Text.Json tutma TypeNameHandling.Allkararı kasıtlı olarak yapıldı. Bir JSON yükünün kendi tür bilgilerini belirtmesine izin vermek, web uygulamalarında yaygın bir güvenlik açığı kaynağıdır. Özellikle ile TypeNameHandling.All yapılandırmasıNewtonsoft.Json, uzak istemcinin yürütülebilir bir uygulamanın tamamını JSON yükünün içine eklemesine olanak tanır, böylece seri durumdan çıkarma sırasında web uygulaması ekli kodu ayıklar ve çalıştırır. Daha fazla bilgi için bkz . Cuma günü 13. JSON saldırıları PowerPoint ve Cuma günü 13. JSON saldırıları ayrıntıları.

JSON Yolu sorguları desteklenmiyor

JsonDocument DOM, JSON Yolu kullanarak sorgulamayı desteklemez.

JsonNode DOM'da her JsonNode örnek, bu düğümün yolunu döndüren bir yönteme sahiptirGetPath. Ancak JSON Yolu sorgu dizelerini temel alan sorguları işlemek için yerleşik API yoktur.

Daha fazla bilgi için dotnet/runtime #31068 GitHub sorununa bakın.

Bazı sınırlar yapılandırılamaz

System.Text.Json , karakter cinsinden (166 MB) ve temel 64 (125 MB) en büyük belirteç boyutu gibi bazı değerler için değiştirilmeyecek sınırları ayarlar. Daha fazla bilgi için kaynak kodu ve GitHub sorunu dotnet/runtime #39953 bölümüne bakınJsonConstants.

NaN, Infinity, -Infinity

Newtonsoft, , Infinityve -Infinity JSON dize belirteçlerini ayrıştırıyorNaN. ile System.Text.Jsonkullanın JsonNumberHandling.AllowNamedFloatingPointLiterals. Bu ayarın nasıl kullanılacağı hakkında bilgi için bkz . Tırnak içinde sayılara izin verme veya sayı yazma.

Ek kaynaklar