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

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.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 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.

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 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 Newtonsoft.Json eşdeğerler listelenmiştirSystem.Text.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 özniteliğin veya genel seçeneğin kullanılması gerekebilir.
⚠️ Desteklenmez, ancak geçici çözüm mümkündür. Geçici çözümler, işlevsellikle tam eşlik sağlayabilen özel dönüştürücülerdir.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.
❌ 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`	✔️ Destekli
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, Sonsuz, -Sonsuz	✔️ Destekli
`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

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 \uxxxx olduğuyla xxxx 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 StringEscapeHandling.EscapeNonAsciikullanıyorsanız Newtonsoft.Json 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:

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

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ş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 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 tam eşlik sağlayabilen özel dönüştürücülerdir.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.

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 JsonSerializerOptions.NumberHandlingolarak ayarlayın WriteAsString AllowReadingFromString 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 web varsayılanlarınıSystem.Text.Jsonve 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 NullValueHandlingDefaultValueHandling ve JsonSerializerSettings ayarları, tüm null-değer veya varsayılan değer özelliklerinin yoksayılacağını 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 seri hale getirme sırasında özellikleri veya alanları yoksaymak için aşağıdaki yolları sağlar:

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.
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 durumdan çıkarabilirsiniz.

içindeSystem.Text.Json, seri hale getirme veya seri durumdan JsonSerializerOptions.IncludeFields özniteliğini kullanın. Ö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 PreserveReferencesHandling göre seri hale getirmenizi sağlayan bir JsonSerializerSettings 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 JsonSerializerOptions.ReferenceHandlerayarlayınPreserve. ayarı ReferenceHandler.Preserve ile PreserveReferencesHandlingeşdeğerdir = PreserveReferencesHandling.AllNewtonsoft.Json.

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.Json ReferenceResolver 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

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

Dikkat

Bir yerine Dictionary<TKey, TValue>TKey seri durumdan string çı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:

DataTable ve ilgili türler (daha fazla bilgi için bkz. Desteklenen türler)
ExpandoObject
TimeZoneInfo
BigInteger
DBNull
Type
ValueTuple ve 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 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 Newtonsoft.JsonçıkarıldığındaObject:

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 JsonElementçıkarıldığında hem ilkel hem de karmaşık değerler için kutulu Object 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.

Tarih biçimini belirtme

Newtonsoft.Jsonve DateTime türlerinin özelliklerinin nasıl serileştirilip seri durumdan DateTimeOffset çı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 : 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 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.

Ö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.

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 (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.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:

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

JsonObjectAttribute

Newtonsoft.Json, hangi üyelerin seri hale getirildiğini, JsonObjectAttributedeğerlerin nasıl işleneceğini ve tüm üyelerin null uygulanabilen bir özniteliğine sahiptir. 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.

Tüm Newtonsoft.Json.JsonObjectAttribute özelliklerin yoksayılması gerektiğini belirtmek için aşağıdaki örneği göz null ö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# System.Text.Json değiştiricisini veya required ekleyerek içinde aynı davranışı JsonRequiredAttribute 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 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 diğer türleri kullanarak JsonNode mevcut JSON yüklerinden değiştirilebilirSystem.Text.Json.NodesDOM ayrıştırabilir ve oluşturabilirsiniz. Daha fazla bilgi için bkz . Kullanma JsonNode.

JsonDocument IDisposable'dir

JsonDocument havuza alınan arabelleğe verilerin bellek içi görünümünü oluşturur. Bu nedenle, veya JObject türünden JArrayNewtonsoft.Json farklı JsonDocument 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

JsonDocument RootElement, 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.Json, , JObjectJArrayvb. gibi JTokenayrılmış hiyerarşik türleri kullanı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 JsonNode , ve öğesine karşılık gelen System.Text.Json.Nodestür ve JObjecttürleri kullanabilirsiniz JArrayJToken. 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<>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 Nullable<T>sizin için bir ReadAsBooleanNull işleyen gibi TokenType, döndüren bool?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 ref structçevresinde Utf8JsonReader bir Newtonsoft.Json.JsonTextReader 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, 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ğ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 Utf8JsonWriter sunulan seçenekleri kullanmak için JsonWriterOptions girinti karakterini ve boyutunu özelleştirebilirsiniz:

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

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 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 Utf8JsonWriterçevresinde Newtonsoft.Json.JsonTextWriter 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ç TypeNameHandling.All tutma System.Text.Jsonkararı 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 Newtonsoft.Json yapılandırmasıTypeNameHandling.All, 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 JsonConstants bölümüne bakın .

NaN, Sonsuz, -Sonsuz

Newtonsoft, , NaNve Infinity JSON dize belirteçlerini ayrıştırıyor-Infinity. 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.

Çö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 2025-10-03

Aracılığıyla paylaş

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

Farklılıklar tablosu

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

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

En az karakter kaçışı

Açıklamalar

Sondaki virgüller

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

Maksimum derinlik

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

Dize özellikleri için dize olmayan değerler

JsonSerializer kullanan senaryolar

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

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

Bir özelliği koşullu olarak yoksayma

Genel ve genel olmayan alanlar

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

Dize olmayan anahtar içeren sözlük

Yerleşik destek olmadan türler

Polimorfik serileştirme

Polimorfik seri durumdan çıkarma

Dize sabit listesi değerlerini seri durumdan çıkarma

Nesne özelliklerinin seri durumdan çıkarılması

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

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

Gerekli özellikler

Tarih biçimini belirtme

Geri Çağırmalar

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

Varolan nesneleri doldurma

Özellikleri değiştirmek yerine yeniden kullanma

Özellikleri ayarlayıcılar olmadan doldurma

Yılan olayı adlandırma ilkesi

System.Runtime.Serialization öznitelikleri

Sekizli sayılar

Eksik üyeleri işleme

JsonObjectAttribute

TraceWriter

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

JsonDocument IDisposable'dir

JsonDocument salt okunur

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

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

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

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

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

JSON okumak için çok hedefli

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

Ham değerler yazma

JSON biçimini özelleştirme

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

JSON yazmak için çok hedefli

TypeNameHandling.All desteklenmiyor

JSON Yolu sorguları desteklenmiyor

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

NaN, Sonsuz, -Sonsuz

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

Ek kaynaklar

Geri Bildirim

Ek kaynaklar