Geçiş Newtonsoft.Json'den System.Text.Json'ye

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

System.Text.Json ad alanı, JavaScript Nesne Gösterimi'ne (JSON) serileştirme ve JSON'dan seri durumdan çıkarma işlevselliği sağlar. System.Text.Json kitaplığı .NET Core 3.1 ve sonraki sürümlerin çalışma zamanına dahildir. 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.6.2 ve sonraki sürümleri
.NET Core 2.0, 2.1 ve 2.2

İpucu

'den Newtonsoft.Jsongeçiş yapmak için yapay zeka yardımı kullanabilirsiniz.

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 anda System.Text.Json için yerleşik bir işlevsellik yoktur, ancak önerilen geçici çözümler vardır. Diğer senaryolarda geçici çözümler pratik değildir.

Ekip System.Text.Json , en sık istenen özellikleri eklemeye yatırım yapıyor. 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) JsonDocumentve Utf8JsonReader türlerini kullanma Utf8JsonWriter yönergelerini de içerir.

Visual Basic'te Utf8JsonReader kullanamazsınız, bu da özel dönüştürücüler yazamayacağınız 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

Tablo aşağıda Newtonsoft.Json özelliklerle ve bunların System.Text.Json eşdeğerleriyle listelenmiştir. 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 özniteliğin veya genel seçeneğin kullanılması gerekebilir.
⚠️ Desteklenmez, ancak geçici çözüm mümkündür. Çözüm yolları, özelleştirilmiş dönüştürücüler olup, işlevsellikle tam eşlik sağlamayabilir.Newtonsoft.Json 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.
❌ Desteklenmiyor ve geçici çözüm pratik veya mümkün değil. 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
Karakter kaçışının en aza indirilmesi	✔️ Sıkı 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ı serileştirmek veya seriden çıkarmak	✔️ NumberHandling genel ayarı, [JsonNumberHandling] özniteliği
Değişmez 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 bir anahtarla `Dictionary` deseri̇alize etme	✔️ Destekli
Herkese açık olmayan özellik tanımlayıcıları ve erişimcileri için destek	✔️ JsonInclude özniteliği
`[JsonConstructor]` özniteliği	✔️ [JsonConstructor] özniteliği
`ReferenceLoopHandling` genel ayar	✔️ ReferenceHandling genel ayarı
Geri Çağırmalar	✔️ Geri Çağırmalar
NaN, Sonsuz, -Sonsuz	✔️ Destekli
`Required` özniteliğinde `[JsonProperty]` ayarı	✔️ [JsonRequired] özniteliği ve C# gerekli değiştirici
`DefaultContractResolver` özellikleri görmezden gelmek için	✔️ DefaultJsonTypeInfoResolver sınıfı
Polimorfik serileştirme	✔️ [JsonDerivedType] özniteliği
Polimorfik deserializasyon	✔️ [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
Setter olmadan özellikleri 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ü `object` özelliğine serileştirme içerisinden geri yükleme	⚠️ Desteklenmez, geçici çözüm, örnek
JSON `null` literali null atanamayan değer türlerine seri hale getirme	⚠️ 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` Öznitelikler için destek	⚠️ 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 etrafında tek tırnak işaretlerinin kullanılmasına 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 duyarsız serileştirmeyi geri alma

Serileştirmeyi kaldırma sırasında, Newtonsoft.Json varsayılan olarak küçük/büyük harf farkı gözetmeyen ö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 Büyük/küçük harfe duyarsız özellik eşleştirme'ye bakın.

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

ASP.NET Core, normalde tırnak içine alınan sayıların deseralize edilmesine de olanak tanır.

Karakter kaçışının en aza indirilmesi

Serileştirme sırasında, Newtonsoft.Json karakterlerin kaçış gerektirmeden geçmesine nispeten izin verir. Yani, karakterin kod noktası olan xxxx'yi \uxxxx ile 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.Json varsayılan olarak ASCII olmayan tüm karakterleri kaçırır, bu nedenle Newtonsoft.Json içinde StringEscapeHandling.EscapeNonAscii kullanıyorsanız 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, Newtonsoft.Json, varsayılan olarak JSON'daki yorumları görmezden gelir. System.Text.Json RFC 8259 belirtimi bunları içermediğinden, varsayılan olarak açıklamalar için özel durumlar oluşturulur. Açıklamalara ve sondaki virgüllere izin verme hakkında bilgi için bkz Yorumlara ve Sondaki Virgüllere İzin Ver.

Sondaki virgüller

Seri durumdan çıkarma işlemi sırasında, Newtonsoft.Json varsayılan olarak sondaki virgülleri 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:

Özellikte öznitelik
Türdeki öznitelik
Dönüştürücüler koleksiyonu

Bu düzen, Converters koleksiyonundaki özel bir dönüştürücünün, tür seviyesinde 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şikliklerinin tasarım zamanı seçimlerini geçersiz kılmasıdır. Önceliği değiştirmenin hiçbir yolu yoktur.

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

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 özellik adlarını çift tırnak, tek tırnak veya tırnak işareti olmadan 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 olmayan değerleri dize özelliklerine dönüştürmez. 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 tam eşlik etmeyebilen ö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 dizeleri olarak (tırnak içine alınmış) temsil edilen sayıları seri hale getirebilir veya seri durumdan çıkarabilir. Örneğin, şunu kabul edebilir: {"DegreesCelsius":"23"} yerine {"DegreesCelsius":23}. System.Text.Json bu davranışı etkinleştirmek için, JsonSerializerOptions.NumberHandling'i WriteAsString veya AllowReadingFromString olarak ayarlayın ya da [JsonNumberHandling] özniteliğini kullanın.

ASP.NET Core'u kullanarak dolaylı olarak System.Text.Json kullanıyorsanız, Newtonsoft.Json gibi bir davranış elde etmek için hiçbir şey yapmanız gerekmez. ASP.NET Core, web varsayılanları belirttiğinde System.Text.Json kullanır ve web varsayılanları alıntılanan sayılara izin verir.

Daha fazla bilgi için tırnak içinde sayılara izin verme veya bunları yazma bölümüne bakın.

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

Newtonsoft.Json [JsonConstructor] özniteliği, bir POCO'ya seri durumdan çıkarı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şul altında yok sayma

Newtonsoft.Json serileştirme veya deserialize etme işlemlerinde 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.
NullValueHandling ve DefaultValueHandling ayarları, JsonSerializerSettings üzerindeki tüm null değerli veya varsayılan değere sahip özelliklerin göz ardı edileceğini belirtmenize olanak sağlar.
NullValueHandling özniteliğindeki DefaultValueHandling ve [JsonProperty] ayarları, null veya varsayılan değer olarak ayarlandığında yoksayılması gereken tek tek özellikleri belirtmenize olanak sağlar.

System.Text.Json serileştirme sırasında özellikleri veya alanları yoksaymak için aşağıdaki yollarını sunar.

Bir özellik üzerindeki [JsonIgnore] özniteliği, özelliğin serileştirme sırasında JSON'dan atlanmasına neden olur.
IgnoreReadOnlyProperties genel seçeneği, tüm salt okunur özellikleri yoksaymanızı sağlar.
Eğer alanları dahil ediyorsanız, JsonSerializerOptions.IgnoreReadOnlyFields genel seçenek tüm salt okunur alanları yoksaymanızı sağlar.
Genel DefaultIgnoreCondition seçenek, varsayılan değerleri olan tüm değer türü özelliklerini yoksaymanıza veya null değerleri olan tüm başvuru türü özelliklerini yoksaymanıza olanak tanır.

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.

Genel ve genel olmayan alanlar

Newtonsoft.Json hem alanları hem de özellikleri serileştirebilir ve seri durumundan çıkarabilir.

System.Text.Json içinde, serileştirme veya ters serileştirme sırasında genel ayarı JsonSerializerOptions.IncludeFields veya [JsonInclude] özniteliğini kullanarak genel alanları dahil edin. "Örnek için Alanları Ekleme kısmına bakınız."

Nesne referanslarını koruma ve döngüleri yönetme

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, referans alarak seri hale getirmenizi sağlayan bir JsonSerializerSettings ayarına 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 istisna oluşturmak yerine döngüsel başvuruları yoksaymanıza olanak tanıyan bir ayara sahiptir.

System.Text.Json içindeki başvuruları korumak ve döngüsel başvuruları işlemek için, JsonSerializerOptions.ReferenceHandler değerini Preserve olarak ayarlayın. ReferenceHandler.Preserve ayarı, PreserveReferencesHandling, = , PreserveReferencesHandling.All ve Newtonsoft.Json'de eşdeğerdir.

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 Döngüsel başvuruları yoksayma bölümüne bakın.

Newtonsoft.Json ReferenceResolver gibi, System.Text.Json.Serialization.ReferenceResolver sınıfı da serileştirme ve seri durumdan çıkarma işlemlerinde referansların korunma 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 Başvuruları ve döngüsel başvuruları koruma ve işleme sayfasına bakın.

Dize olmayan anahtar içeren sözlük

Hem Newtonsoft.Json hem de System.Text.Json, Dictionary<TKey, TValue> koleksiyonlarını destekler. Desteklenen anahtar türleri hakkında bilgi için bkz. Desteklenen anahtar türleri.

Dikkat

Dictionary<TKey, TValue>'a TKey'in string dışındaki bir tür olarak serileştirilmesi, tüketici uygulamada bir güvenlik açığı oluşturabilir. 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:

DataTable ve ilgili türler (daha fazla bilgi için bkz. Desteklenen türler)
ExpandoObject
TimeZoneInfo
BigInteger
DBNull
Type
ValueTuple ve onun ilişkili genel türleri

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 deserializasyon

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 nasıl yazılır başlığındaki örneğe benzer bir dönüştürücü oluşturun.

Enum string 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, JsonStringEnumConverter dönüştürücüsünü kullanarak dize sabit listesi değerlerinin seri durumdan çıkarılmasını etkinleştirebilirsiniz. Daha fazla bilgi için bkz Enum'lar dizge olarak.

Nesne özelliklerinin seri durumdan çıkarılması

Newtonsoft.Json deseriyalize edilip Object ile durumunu geri yüklediğinde:

JSON yükündeki ilkel değerlerin türünü (örneğin null dışındaki) çıkarsar ve depolanan string, long, double, boolean veya DateTime öğesini kutulu bir 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 JObject ya da JArray 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. Süslü parantezler veya köşeli parantezler 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 referans döndürür.

System.Text.Json, Object'ye serileştirilirken 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 ve Newtonsoft.Json'ye aynı şekilde davranır ve null referans döndürür.

Özellikler için tür çıkarımı uygulamak amacıyla, objectÖzel dönüştürücü nasıl yazılır başlıklı rehberdeki örneğe benzer bir dönüştürücü oluşturun.

Null'u null olmayan türe deserileştirmek

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

NullValueHandling, Ignore olarak ayarlanı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 istisna fırlatır. (System.Text.Json içindeki karşılık gelen null işleme ayarı 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, int'yi int? olarak değiştirin).

Başka bir alternatif çözüm, türler için DateTimeOffset null değerlerini işleyen aşağıdaki örnek gibi bir dönüştürücü oluşturmaktır.

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);
    }
}

Bu özel dönüştürücüyü, özelliğe bir öznitelik ekleyerek veya dönüştürücüyü koleksiyona ekleyerek kaydedin.

Not: Önceki dönüştürücü, varsayılan değerleri belirten POCO'lar için null değerleri farklı şekilde işlerNewtonsoft.Json. Ö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şlemi sonrasında Date özelliğin değeri 1/1/0001 (default(DateTimeOffset)) olur; yani, oluşturucuda ayarlanan değer üzerine yazılır. Aynı POCO ve JSON göz önünde bulundurulduğunda, Newtonsoft.Json seri durumdan çıkarma işlemi Date özelliğinde 1/1/2001 değerini bırakır.

Değişmez sınıflar ve yapılar için seri durumdan çıkarma

Newtonsoft.Json, parametreleri olan oluşturucuları kullanabildiği için değiştirilemez sınıfları ve yapıları serileştirmeden çıkarabilir.

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

Newtonsoft.Json içinde, [JsonProperty] özniteliğini ayarlayarak bir özelliğin Required gerekli olduğunu belirtirsiniz. Newtonsoft.Json JSON'da gerekli olarak işaretlenmiş bir özellik için değer alınmazsa hata 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.

Tarih biçimini belirtme

Newtonsoft.Json, DateTime ve DateTimeOffset türlerinin özelliklerinin nasıl serileştirilip seri durumdan çı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ş, belirsiz 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, Unix zaman damgası biçimini kullanan ve saat dilimi farkıyla veya farkı olmadan (örneğin /Date(1590863400000-0700)/ veya /Date(1590863400000)/ gibi değerlerle) JSON verilerini serileştiren ve seriden çıkaran:

sealed class UnixEpochDateTimeOffsetConverter : System.Text.Json.Serialization.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, NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime)
                || !int.TryParse(match.Groups[3].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int hours)
                || !int.TryParse(match.Groups[4].Value, NumberStyles.Integer, CultureInfo.InvariantCulture, out int minutes))
        {
            throw new System.Text.Json.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 = value.ToUnixTimeMilliseconds();

        TimeSpan utcOffset = value.Offset;

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

        writer.WriteStringValue(formatted);
    }
}

sealed class UnixEpochDateTimeConverter : System.Text.Json.Serialization.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, NumberStyles.Integer, CultureInfo.InvariantCulture, out long unixTime))
        {
            throw new System.Text.Json.JsonException();
        }

        return s_epoch.AddMilliseconds(unixTime);
    }

    public override void Write(
        Utf8JsonWriter writer,
        DateTime value,
        JsonSerializerOptions options)
    {
        long unixTime = (value - s_epoch).Ticks / TimeSpan.TicksPerMillisecond;

        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 nesneyi deserilize etmeye 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 ortaya çıkarır. Bunları kullanmak için System.Text.Json.Serialization ad alanındaki aşağıdaki arabirimlerden 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ılmış özellikleri doldurma.

Setter olmadan özellikleri 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, Başlatılan özellikleri doldurma kısmına bakın.

Yılan olayı adlandırma ilkesi

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

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 (kebap durumu)"	keba_b-_case	"kebab-case" (kelimelerin tire ile ayrıldığı adlandırma kuralları)

System.Runtime.Serialization öznitelikleri

System.Runtime.Serializationgibi öznitelikler DataContractAttribute DataMemberAttribute IgnoreDataMemberAttribute 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.Json baştaki sıfırlara izin vermez çünkü RFC 8259 belirtimi bunlara izin vermiyor.

Eksik üyelerle başa çıkma

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:

Deserialize ederken hedeflediğiniz türe JsonUnmappedMemberHandlingAttribute özniteliğini uygulayın.
Tercihinizi genel olarak ayarlamak için özelliğini ayarlayın JsonSerializerOptions.UnmappedMemberHandling . Veya kaynak oluşturma için JsonSourceGenerationOptionsAttribute.UnmappedMemberHandling özelliğini ayarlayın ve JsonSerializerContext özniteliğini sınıfınıza uygulayın.
JsonTypeInfo.UnmappedMemberHandling öğesini özelleştirin.

JsonObjectAttribute

Newtonsoft.Json'ün, hangi üyelerin serileştirileceğini, null değerlerin nasıl işleneceğini ve tüm üyelerin gerekli olup olmadığını kontrol etmek için tür seviyesinde uygulanabilen bir özniteliği vardır. System.Text.Json bir türe uygulanabilecek eşdeğer bir özniteliği yoktur. Bazı davranışlar, örneğin null değer işleme gibi durumlar için, JsonSerializerOptions genelde veya her bir özelliği JsonIgnoreAttribute kullanarak tek tek yapılandırabilirsiniz.

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

[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 veya her bir özelliğe JsonRequiredAttribute ekleyerek, System.Text.Json içinde aynı davranışı 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; }
}

Son olarak, JSON şema oluşturma için bir başlık belirtmek için kullanılan Newtonsoft.Json.JsonObjectAttribute aşağıdaki örneği göz önünde bulundurun:

[JsonObject(Title = "PersonTitle")]
public class Person { ... }

Title özelliği JSON şema meta verileri için kullanılır ve içinde System.Text.Jsondoğrudan eşdeğeri yoktur. .NET 9'dan başlayarak, JsonSchemaExporter öğesini kullanarak JSON şemaları oluşturabilir ve TransformSchemaNode temsilcisiyle şema başlığını özelleştirebilirsiniz. Bir örnek için bkz . Oluşturulan şemayı dönüştürme.

TraceWriter

Newtonsoft.Json, serileştirme veya seri durumdan çıkarma tarafından oluşturulan günlükleri görüntülemek için TraceWriter kullanarak 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 tanımlar.

.NET 6'dan itibaren, mevcut JSON yüklerinden değiştirilebilir bir DOM ayrıştırmak ve oluşturmak için JsonNode türü ve System.Text.Json.Nodes ad alanındaki diğer türleri kullanabilirsiniz. Daha fazla bilgi için bkz JsonNode kullanımı.

JsonDocument IDisposable'dir

JsonDocument verilerin bellek içi görünümünü, paylaşımlı bir arabellekte oluşturur. Bu nedenle, Newtonsoft.Json'nın JObject veya JArray'dan farklı olarak, JsonDocument türü IDisposable uygular 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 yaygın JSON yük boyutlarını (örn. < 1 MB) ayrıştırırken yapılan ayırmaları azaltmak için tasarlanmıştır.

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

JsonDocument herhangi bir JSON öğesini kapsayan bir birleşim yapı türü olan JsonElement türündeki özelliği RootElement olarak kullanıma sunar. Newtonsoft.Json, JObject, JArray, JToken gibi ayrılmış hiyerarşik türleri kullanır. JsonElement üzerinde arama yapabilir ve numaralandırabilir, JsonElement'i JSON öğelerini .NET türlerine dönüştürmek için kullanabilirsiniz.

.NET 6 ile başlayarak, JObject, JArray ve JToken öğelerine karşılık gelen JsonNode türü ve System.Text.Json.Nodes ad alanındaki türleri kullanabilirsiniz. Daha fazla bilgi için bkz Kullan JsonNode.

JsonDocument ve JsonElement içinde alt öğeler nasıl aranır?

JObject veya JArray'den Newtonsoft.Json kullanarak JSON belirteçleri için yapılan aramalar, bazı sözlüklerde yapılan sorgulamalar olduğundan göreceli olarak 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 JsonDocument ve JsonElement'te alt öğeleri arama konusuna bakın.

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

System.Text.Json.Utf8JsonReader, yüksek performanslı, düşük bellek tüketimli, yalnızca ileri yönlü bir okuyucudur ve UTF-8 ile kodlanmış JSON metnini ReadOnlySpan<byte> veya ReadOnlySequence<byte>'den okur. Utf8JsonReader, özel ayrıştırıcılar ve serileştiriciler oluşturmak için kullanılabilecek düşük düzeyli bir türdür.

Utf8JsonReader bir ref yapısıdır

JsonTextReader, Newtonsoft.Json içinde 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 Utf8JsonReader için referans yapı sınırlamaları kısmına bakın.

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

Newtonsoft.Json, sizin için bir ReadAsBooleanNull işleyen ve bool? döndüren ReadAsBoolean gibi Nullable<T> döndüren API'ler sağlar. Yerleşik System.Text.Json API'ler yalnızca null atanamayan değer türlerini döndürür. Daha fazla bilgi için Null değerleri null yapılabilir türlere okuma konusuna bakın.

JSON okumak için çoklu hedefleme

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, ref struct ve Utf8JsonReader etrafına Newtonsoft.Json.JsonTextReader adlı bir sarmalayıcı oluşturmaktır. Bu sarmalayıcı, davranışsal farklılıkları izole ederken genel ortak yüzey alanını birleştirecektir. Bu, değişiklikleri esas olarak türün inşasında yalıtmanıza ve yeni türü referans olarak 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, Stringve Int32gibi DateTimeyaygı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ğerleri yaz

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 Ham JSON yazma bölümüne bkz.

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 kelimeleri tırnak içine alır.

.NET 9'da, JsonWriterOptions yapısı tarafından sunulan seçenekleri kullanarak Utf8JsonWriter için girinti karakterini ve boyutunu özelleştirebilirsiniz.

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

Girinti - Girintileme karakter sayısını belirtir. Utf8JsonWriter her zaman 2 karakterle girinti yapar.
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 onları 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ğerlerini yaz

JsonTextWriter WriteValue 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 yazımı için birden fazla hedef

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. Kodları mümkün olduğunca çok paylaşmanın bir yolu, Utf8JsonWriter ve Newtonsoft.Json.JsonTextWriter etrafında bir sarmalayıcı oluşturmaktır. Bu sarmalayıcı, davranış farklılıklarını yalıtırken açık 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

TypeNameHandling.All ile eşdeğer işlevselliğin System.Text.Json'den hariç tutulması kararı kasıtlı olarak verildi. 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. Newtonsoft.Json ve TypeNameHandling.All ile yapılandırmak, uzak istemcinin yürütülebilir bir uygulamanın tamamını JSON yükünün içine eklemesine olanak tanır, böylece deserialization sırasında web uygulaması ekli kodu ayıklar ve çalıştırır. Daha fazla bilgi için 13. Cuma JSON saldırıları hakkında PowerPoint sunumu ve 13. Cuma JSON saldırıları ayrıntılarına bakın.

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 bazı değerler için, karakter sayısına göre en büyük belirteç boyutu (166 MB) ve base 64 kodlamasında (125 MB) gibi değiştirilemez sınırlar belirler. Daha fazla bilgi için kaynak koddaki bölüme ve GitHub dotnet/runtime #39953 sorununa bakın.

NaN, Sonsuz, -Sonsuz

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

Çözüm genelinde geçiş için yapay zeka kullanma

Çözüm kodunuzu Newtonsoft.Json öğesinden System.Text.Json öğesine geçirmek için GitHub Copilot gibi yapay zeka araçlarını kullanabilirsiniz.

Bir çözümü geçirmek için Visual Studio Copilot Sohbeti'nde kullanabileceğiniz örnek bir istem aşağıda verilmiştir.

Convert all serialization code in this #solution from Newtonsoft.Json to System.Text.Json, using the recommended approach for my current .NET version.
- Update attributes and properties, including rules for skipping or renaming during serialization
- Ensure polymorphic serialization continues to work correctly
- Respect existing custom converters and project-level settings (for example, from the Utilities folder or appsettings.json)
- Update related unit tests and highlight any potential breaking changes
- Generate a migration summary

Uygulamadan önce Copilot'un önerilerini gözden geçirin.

GitHub Copilot hakkında daha fazla bilgi için bkz. GitHub'ın SSS'leri.

Ek kaynaklar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-03-26