' Den ' a geçiş Newtonsoft.JsonSystem.Text.JsonHow to migrate from Newtonsoft.Json to System.Text.Json

Bu makalede, ' den ' e nasıl geçiş yapılacağı gösterilmektedir Newtonsoft.Json System.Text.Json .This article shows how to migrate from Newtonsoft.Json to System.Text.Json.

System.Text.JsonAd alanı, JavaScript nesne gösterimi (JSON) öğesinden serileştirmek ve seri durumdan çıkarmak için işlevsellik sağlar.The System.Text.Json namespace provides functionality for serializing to and deserializing from JavaScript Object Notation (JSON). System.Text.JsonKitaplık, .net Core 3,0 paylaşılan çerçevesine dahildir.The System.Text.Json library is included in the .NET Core 3.0 shared framework. Diğer hedef çerçeveler için System.Text.Json NuGet paketini yükler.For other target frameworks, install the System.Text.Json NuGet package. Paket şunları destekler:The package supports:

  • .NET Standard 2,0 ve sonraki sürümler.NET Standard 2.0 and later versions
  • .NET Framework 4.7.2 ve sonraki sürümler.NET Framework 4.7.2 and later versions
  • .NET Core 2,0, 2,1 ve 2,2.NET Core 2.0, 2.1, and 2.2

System.Text.JsonÖncelikle performans, güvenlik ve standartlar uyumluluğuna odaklanır.System.Text.Json focuses primarily on performance, security, and standards compliance. Varsayılan davranışta bazı önemli farklılıklar vardır ve ile özellik eşliği yoktur Newtonsoft.Json .It has some key differences in default behavior and doesn't aim to have feature parity with Newtonsoft.Json. Bazı senaryolarda System.Text.Json yerleşik işlevselliği yoktur, ancak önerilen geçici çözümler vardır.For some scenarios, System.Text.Json has no built-in functionality, but there are recommended workarounds. Diğer senaryolar için geçici çözümler pratik bir şekilde yapılır.For other scenarios, workarounds are impractical. Uygulamanız eksik bir özelliğe bağımlıysa, senaryonuza yönelik desteğin eklenip eklenemediğine ulaşmak için bir sorun yerleştirmeyi düşünün.If your application depends on a missing feature, consider filing an issue to find out if support for your scenario can be added.

Bu makalenin çoğu, API 'yi kullanma ile JsonSerializer ilgilidir, ancak aynı zamanda JsonDocument (belge nesne MODELI veya DOM), Utf8JsonReader ve türlerini temsil eder Utf8JsonWriter .Most of this article is about how to use the JsonSerializer API, but it also includes guidance on how to use the JsonDocument (which represents the Document Object Model or DOM), Utf8JsonReader, and Utf8JsonWriter types.

Ve arasındaki farklar tablosu Newtonsoft.JsonSystem.Text.JsonTable of differences between Newtonsoft.Json and System.Text.Json

Aşağıdaki tabloda Newtonsoft.Json Özellikler ve eşdeğerleri listelenmektedir System.Text.Json .The following table lists Newtonsoft.Json features and System.Text.Json equivalents. Eşdeğerleri aşağıdaki kategorilere ayrılır:The equivalents fall into the following categories:

  • Yerleşik işlevsellik tarafından desteklenir.Supported by built-in functionality. Benzer davranış alma System.Text.Json , bir öznitelik veya genel seçenek kullanımını gerektirebilir.Getting similar behavior from System.Text.Json may require the use of an attribute or global option.
  • Desteklenmez, geçici çözüm mümkündür.Not supported, workaround is possible. Geçici çözümler, işlevlerle tamamen eşlik sağlamayan özel dönüştürücülerdir Newtonsoft.Json .The workarounds are custom converters, which may not provide complete parity with Newtonsoft.Json functionality. Bunlardan bazılarının örnek kodu örnek olarak verilmiştir.For some of these, sample code is provided as examples. Bu özelliklerden yararlandıysanız Newtonsoft.Json geçiş, .NET nesne modellerinizde veya diğer kod değişikliklerinde değişiklik yapılmasını gerektirir.If you rely on these Newtonsoft.Json features, migration will require modifications to your .NET object models or other code changes.
  • Desteklenmez, geçici çözüm pratik veya mümkün değildir.Not supported, workaround is not practical or possible. Bu özelliklerden yararlandıysanız Newtonsoft.Json geçiş önemli değişiklikler yapılmadan mümkün olmayacaktır.If you rely on these Newtonsoft.Json features, migration will not be possible without significant changes.
Newtonsoft.Json özelliğiNewtonsoft.Json feature System.Text.JsondeğerininSystem.Text.Json equivalent
Varsayılan olarak büyük/küçük harfe duyarsız seri haleCase-insensitive deserialization by default ✔️ Propertynamecaseduyarsız genel ayarı✔️ PropertyNameCaseInsensitive global setting
Camel-Case Özellik adlarıCamel-case property names ✔️ Propertynamingpolicy genel ayarı✔️ PropertyNamingPolicy global setting
En az karakter kaçışMinimal character escaping ✔️ katı karakter kaçış, yapılandırılabilir✔️ Strict character escaping, configurable
NullValueHandling.IgnoreGenel ayarNullValueHandling.Ignore global setting ✔️ ıgnorenullvalues genel seçeneği✔️ IgnoreNullValues global option
Açıklamalara izin verAllow comments ✔️ ReadCommentHandling genel ayarı✔️ ReadCommentHandling global setting
Sondaki virgüllerin kullanılmasına izin verAllow trailing commas ✔️ Allowtrailingvirgüller genel ayarı✔️ AllowTrailingCommas global setting
Özel dönüştürücü kaydıCustom converter registration ✔️ öncelik sırası farklı✔️ Order of precedence differs
Varsayılan olarak en fazla derinlik yokNo maximum depth by default ✔️ varsayılan en yüksek derinlik 64, yapılandırılabilir✔️ Default maximum depth 64, configurable
Geniş kapsamlı türler için destekSupport for a broad range of types ⚠️Bazı türler için özel dönüştürücüler gerekir⚠️ Some types require custom converters
Dizeleri sayı olarak seri durumdan çıkarmaDeserialize strings as numbers ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
DictionaryDize olmayan anahtarla seri durumdan çıkarmaDeserialize Dictionary with non-string key ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Polimorfik serileştirmePolymorphic serialization ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Polimorfik seri kaldırmaPolymorphic deserialization ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Çıkarılan türden özellikleri seri durumdan çıkar objectDeserialize inferred type to object properties ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
JSON null sabit değerinin null yapılamayan değer türlerine serisini kaldırmaDeserialize JSON null literal to non-nullable value types ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Sabit sınıflar ve yapılar için seri durumdan çıkarmaDeserialize to immutable classes and structs ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
[JsonConstructor] özniteliği[JsonConstructor] attribute ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Requiredözniteliği üzerinde ayarlama [JsonProperty]Required setting on [JsonProperty] attribute ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
NullValueHandlingözniteliği üzerinde ayarlama [JsonProperty]NullValueHandling setting on [JsonProperty] attribute ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
DefaultValueHandlingözniteliği üzerinde ayarlama [JsonProperty]DefaultValueHandling setting on [JsonProperty] attribute ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
DefaultValueHandlingGenel ayarDefaultValueHandling global setting ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
DefaultContractResolverözellikleri dışlamak içinDefaultContractResolver to exclude properties ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
DateTimeZoneHandling, DateFormatString AyarlarDateTimeZoneHandling, DateFormatString settings ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Geri ÇağırmalarCallbacks ⚠️Desteklenmez, geçici çözüm, örnek⚠️ Not supported, workaround, sample
Ortak ve genel olmayan alanlar için destekSupport for public and non-public fields ⚠️Desteklenmez, geçici çözüm⚠️ Not supported, workaround
İç ve özel özellik ayarlayıcıları ve alıcılar için destekSupport for internal and private property setters and getters ⚠️Desteklenmez, geçici çözüm⚠️ Not supported, workaround
JsonConvert.PopulateObject yöntemiJsonConvert.PopulateObject method ⚠️Desteklenmez, geçici çözüm⚠️ Not supported, workaround
ObjectCreationHandlingGenel ayarObjectCreationHandling global setting ⚠️Desteklenmez, geçici çözüm⚠️ Not supported, workaround
Ayarlayıcısız koleksiyonlara EkleAdd to collections without setters ⚠️Desteklenmez, geçici çözüm⚠️ Not supported, workaround
PreserveReferencesHandlingGenel ayarPreserveReferencesHandling global setting DesteklenmiyorNot supported
ReferenceLoopHandlingGenel ayarReferenceLoopHandling global setting DesteklenmiyorNot supported
Öznitelikler için destek System.Runtime.SerializationSupport for System.Runtime.Serialization attributes DesteklenmiyorNot supported
MissingMemberHandlingGenel ayarMissingMemberHandling global setting DesteklenmiyorNot supported
Tırnak işaretleri olmadan özellik adlarına izin verAllow property names without quotes DesteklenmiyorNot supported
Dize değerlerinin çevresinde tek tırnak işaretlerine izin verAllow single quotes around string values DesteklenmiyorNot supported
Dize özellikleri için dize olmayan JSON değerlerine izin verAllow non-string JSON values for string properties DesteklenmiyorNot supported

Bu, özelliklerin kapsamlı bir listesi değildir Newtonsoft.Json .This is not an exhaustive list of Newtonsoft.Json features. Listede, GitHub sorunları veya StackOverflow gönderileri için istenen birçok senaryo bulunur.The list includes many of the scenarios that have been requested in GitHub issues or StackOverflow posts. Burada listelenen senaryolardan biri için şu anda örnek kodu olmayan bir geçici çö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 sayfayı seçin.If you implement a workaround for one of the scenarios listed here that doesn't currently have sample code, and if you want to share your solution, select This page in the Feedback section at the bottom of this page. Bu, bu belgenin GitHub deposunda bir sorun oluşturur ve bu sayfadaki geri bildirim bölümünde de listeler.That creates an issue in this documentation's GitHub repo and lists it in the Feedback section on this page too.

Varsayılan JsonSerializer davranışındaki farklılıklarNewtonsoft.JsonDifferences in default JsonSerializer behavior compared to Newtonsoft.Json

System.Text.JsonVarsayılan olarak katı olur ve arayan adına tahmin veya yorumlamayı önler, belirleyici davranışı vurgulayarak.System.Text.Json is strict by default and avoids any guessing or interpretation on the caller's behalf, emphasizing deterministic behavior. Kitaplık, performans ve güvenlik için kasıtlı olarak bu şekilde tasarlanmıştır.The library is intentionally designed this way for performance and security. Newtonsoft.JsonVarsayılan olarak esnektir.Newtonsoft.Json is flexible by default. Tasarımda bu temel fark, varsayılan davranıştaki aşağıdaki belirli farklılıklardan birçoğın arkasında bulunur.This fundamental difference in design is behind many of the following specific differences in default behavior.

Büyük/küçük harfe duyarsız seri haleCase-insensitive deserialization

Seri durumdan çıkarma sırasında, Newtonsoft.Json Varsayılan olarak büyük/küçük harfe duyarsız Özellik adı eşleştirmeyi yapar.During deserialization, Newtonsoft.Json does case-insensitive property name matching by default. System.Text.JsonVarsayılan değer büyük/küçük harfe duyarlıdır ve tam bir eşleşme yaptığından daha iyi performans sağlar.The System.Text.Json default is case-sensitive, which gives better performance since it's doing an exact match. Büyük/küçük harfe duyarsız eşleşme yapma hakkında daha fazla bilgi için bkz. büyük/küçük harfe duyarsız Özellik eşleştirme.For information about how to do case-insensitive matching, see Case-insensitive property matching.

System.Text.JsonASP.NET Core kullanarak dolaylı olarak kullanıyorsanız, gibi davranışları almak için herhangi bir şey yapmanız gerekmez Newtonsoft.Json .If you're using System.Text.Json indirectly by using ASP.NET Core, you don't need to do anything to get behavior like Newtonsoft.Json. ASP.NET Core, kullandığı Camel özellik adlarına ve büyük/küçük harfe duyarsız eşleştirmeye yönelik ayarları belirtir System.Text.Json .ASP.NET Core specifies the settings for camel-casing property names and case-insensitive matching when it uses System.Text.Json. Varsayılan değerler Jsonoptions sınıfındaayarlanır.The default values are set in the JsonOptions class.

En az karakter kaçışMinimal character escaping

Serileştirme sırasında, Newtonsoft.Json karakterlerin kaçış olmadan üzerinden izin verme konusunda görece bir şekilde izin verilir.During serialization, Newtonsoft.Json is relatively permissive about letting characters through without escaping them. Diğer bir deyişle, bunları \uxxxx xxxx karakterin kod noktası olduğu yerde değiştirmez.That is, it doesn't replace them with \uxxxx where xxxx is the character's code point. Burada kaçış yaptığı yerlerde, \ karakterden önce bir (örneğin, " olur) bir olarak yayarak bunu yapar \" .Where it does escape them, it does so by emitting a \ before the character (for example, " becomes \"). System.Text.Jsonsiteler arası betik (XSS) veya bilgi açıklama saldırılarına karşı derinlemesine savunma korumaları sağlamak için varsayılan olarak daha fazla karakter çıkar ve altı karakterli sırayı kullanarak bu şekilde yapılır.System.Text.Json escapes more characters by default to provide defense-in-depth protections against cross-site scripting (XSS) or information-disclosure attacks and does so by using the six-character sequence. System.Text.JsonASCII olmayan tüm karakterleri varsayılan olarak çıkar, bu nedenle içinde kullanıyorsanız herhangi bir şey yapmanız gerekmez StringEscapeHandling.EscapeNonAscii Newtonsoft.Json .System.Text.Json escapes all non-ASCII characters by default, so you don't need to do anything if you're using StringEscapeHandling.EscapeNonAscii in Newtonsoft.Json. System.Text.JsonAyrıca, varsayılan olarak HTML duyarlı karakterleri de çıkar.System.Text.Json also escapes HTML-sensitive characters, by default. Varsayılan davranışı geçersiz kılma hakkında daha fazla bilgi için System.Text.Json bkz. karakter kodlamasını özelleştirme.For information about how to override the default System.Text.Json behavior, see Customize character encoding.

AçıklamalarComments

Seri durumdan çıkarma sırasında, Newtonsoft.Json Varsayılan olarak JSON 'daki açıklamaları yoksayar.During deserialization, Newtonsoft.Json ignores comments in the JSON by default. System.Text.Json RFC 8259 belirtiminde bunları içermediğinden, açıklamalar için özel durumlar oluşturmak varsayılan değer.The System.Text.Json default is to throw exceptions for comments because the RFC 8259 specification doesn't include them. Açıklamalara izin verme hakkında daha fazla bilgi için bkz. yorumlara Izin verme ve sondaki virgüller.For information about how to allow comments, see Allow comments and trailing commas.

Sondaki virgüllerTrailing commas

Seri durumdan çıkarma sırasında, Newtonsoft.Json Varsayılan olarak sondaki virgüllerin yok sayılır.During deserialization, Newtonsoft.Json ignores trailing commas by default. Ayrıca, birden çok sondaki virgül yoksayar (örneğin, [{"Color":"Red"},{"Color":"Green"},,] ).It also ignores multiple trailing commas (for example, [{"Color":"Red"},{"Color":"Green"},,]). Varsayılan olarak, System.Text.Json RFC 8259 belirtimi bunlara izin vermediğinden, sondaki virgüller için özel durumlar throw.The System.Text.Json default is to throw exceptions for trailing commas because the RFC 8259 specification doesn't allow them. Bunları kabul etme hakkında daha fazla bilgi için System.Text.Json bkz. yorumlara izin verme ve sondaki virgüller.For information about how to make System.Text.Json accept them, see Allow comments and trailing commas. Birden çok bitiş virgülne izin vermenin bir yolu yoktur.There's no way to allow multiple trailing commas.

Dönüştürücü kayıt önceliğiConverter registration precedence

Newtonsoft.JsonÖzel dönüştürücüler için kayıt önceliği aşağıdaki gibidir:The Newtonsoft.Json registration precedence for custom converters is as follows:

Bu sıra, koleksiyondaki bir özel dönüştürücünün 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.This order means that a custom converter in the Converters collection is overridden by a converter that is registered by applying an attribute at the type level. Bu kayıtların her ikisi de özellik düzeyindeki bir öznitelik tarafından geçersiz kılınır.Both of those registrations are overridden by an attribute at the property level.

System.Text.JsonÖzel dönüştürücüler için kayıt önceliği farklıdır:The System.Text.Json registration precedence for custom converters is different:

  • Özelliğindeki öznitelikAttribute on property
  • ConverterskoleksiyonConverters collection
  • Türündeki öznitelikAttribute on type

Buradaki fark, koleksiyondaki özel dönüştürücünün Converters tür düzeyinde bir özniteliği geçersiz kılmanızdır.The difference here is that a custom converter in the Converters collection overrides an attribute at the type level. Bu öncelik sırasının arkasındaki amaç, çalışma zamanı değişikliklerinin tasarım zamanı seçimlerini geçersiz kılmasını sağlamak olacaktır.The intention behind this order of precedence is to make run-time changes override design-time choices. Önceliği değiştirme yolu yoktur.There's no way to change the precedence.

Özel dönüştürücü kaydı hakkında daha fazla bilgi için bkz. özel dönüştürücüyü kaydetme.For more information about custom converter registration, see Register a custom converter.

En yüksek derinlikMaximum depth

Newtonsoft.JsonVarsayılan olarak en yüksek derinlik sınırına sahip değildir.Newtonsoft.Json doesn't have a maximum depth limit by default. System.Text.JsonVarsayılan 64 için bir sınır vardır ve bu ayar tarafından yapılandırılabilir JsonSerializerOptions.MaxDepth .For System.Text.Json there's a default limit of 64, and it's configurable by setting JsonSerializerOptions.MaxDepth.

System.Text.JsonASP.NET Core kullanarak dolaylı olarak kullanıyorsanız, varsayılan derinlik üst sınırı 32 ' dir.If you're using System.Text.Json indirectly by using ASP.NET Core, the default maximum depth limit is 32. Varsayılan değer model bağlama ile aynıdır ve Jsonoptions sınıfındaayarlanır.The default value is the same as for model binding and is set in the JsonOptions class.

JSON dizeleri (özellik adları ve dize değerleri)JSON strings (property names and string values)

Seri durumdan çıkarma sırasında, Newtonsoft.Json çift tırnak, tek tırnak veya tırnak işaretleri olmadan çevrelenmiş özellik adlarını kabul eder.During deserialization, Newtonsoft.Json accepts property names surrounded by double quotes, single quotes, or without quotes. Çift tırnak veya tek tırnak işareti içine alınmış dize değerlerini kabul eder.It accepts string values surrounded by double quotes or single quotes. Örneğin, Newtonsoft.Json AŞAĞıDAKI JSON 'yi kabul eder:For example, Newtonsoft.Json accepts the following JSON:

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

System.Text.Jsonyalnızca çift tırnak içindeki özellik adlarını ve dize değerlerini kabul eder çünkü bu biçim, RFC 8259 belirtimi için gereklidir ve geçerli JSON olarak kabul edilen tek biçimdir.System.Text.Json only accepts property names and string values in double quotes because that format is required by the RFC 8259 specification and is the only format considered valid JSON.

Tek tırnak içine alınmış bir değer, aşağıdaki iletiyle birlikte bir Jsonexception ile sonuçlanır:A value enclosed in single quotes results in a JsonException with the following message:

''' is an invalid start of a value.

Dize özellikleri için dize olmayan değerlerNon-string values for string properties

Newtonsoft.Jsonsayı veya sabit değerler gibi dize olmayan değerleri kabul eder true ve false tür dizesinin özelliklerine seri durumdan çıkarmak için.Newtonsoft.Json accepts non-string values, such as a number or the literals true and false, for deserialization to properties of type string. Aşağıdaki sınıfa başarıyla seri hale getirilen bir JSON örneği aşağıda verilmiştir Newtonsoft.Json :Here's an example of JSON that Newtonsoft.Json successfully deserializes to the following class:

{
  "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.Jsondize olmayan değerlerin dize özelliklerine serileştirmez.System.Text.Json doesn't deserialize non-string values into string properties. Bir dize alanı için alınan dize olmayan bir değer, aşağıdaki iletiyle birlikte bir Jsonexception ile sonuçlanır:A non-string value received for a string field results in a JsonException with the following message:

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

Geçici çözüm gerektiren JsonSerializer kullanan senaryolarScenarios using JsonSerializer that require workarounds

Aşağıdaki senaryolar yerleşik işlevsellik tarafından desteklenmez, ancak geçici çözümler mümkündür.The following scenarios aren't supported by built-in functionality, but workarounds are possible. Geçici çözümler, işlevlerle tamamen eşlik sağlamayan özel dönüştürücülerdir Newtonsoft.Json .The workarounds are custom converters, which may not provide complete parity with Newtonsoft.Json functionality. Bunlardan bazılarının örnek kodu örnek olarak verilmiştir.For some of these, sample code is provided as examples. Bu özelliklerden yararlandıysanız Newtonsoft.Json geçiş, .NET nesne modellerinizde veya diğer kod değişikliklerinde değişiklik yapılmasını gerektirir.If you rely on these Newtonsoft.Json features, migration will require modifications to your .NET object models or other code changes.

Yerleşik destek olmadan türlerTypes without built-in support

System.Text.Json, aşağıdaki türler için yerleşik destek sağlamaz:System.Text.Json doesn't provide built-in support for the following types:

Özel dönüştürücüler, yerleşik desteği olmayan türler için uygulanabilir.Custom converters can be implemented for types that don't have built-in support.

Tırnak işaretli sayılarQuoted numbers

Newtonsoft.JsonJSON dizeleri (tırnak içine alınmış) tarafından temsil edilen sayıları seri hale getirme veya seri durumdan çıkarma.Newtonsoft.Json can serialize or deserialize numbers represented by JSON strings (surrounded by quotes). Örneğin, yerine şunları kabul edebilir: {"DegreesCelsius":"23"} {"DegreesCelsius":23} .For example, it can accept: {"DegreesCelsius":"23"} instead of {"DegreesCelsius":23}. İçindeki bu davranışı etkinleştirmek için System.Text.Json , aşağıdaki örneğe benzer bir özel dönüştürücü uygulayın.To enable that behavior in System.Text.Json, implement a custom converter like the following example. Dönüştürücü şu şekilde tanımlanan özellikleri işler long :The converter handles properties defined as long:

  • Onları JSON dizeleri olarak serileştirir.It serializes them as JSON strings.
  • Seri durumdan çıkarılırken, tırnak içindeki JSON numaralarını ve sayıları kabul eder.It accepts JSON numbers and numbers within quotes while deserializing.
using System;
using System.Buffers;
using System.Buffers.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class LongToStringConverter : JsonConverter<long>
    {
        public override long Read(ref Utf8JsonReader reader, Type type, JsonSerializerOptions options)
        {
            if (reader.TokenType == JsonTokenType.String)
            {
                ReadOnlySpan<byte> span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
                if (Utf8Parser.TryParse(span, out long number, out int bytesConsumed) && span.Length == bytesConsumed)
                    return number;

                if (Int64.TryParse(reader.GetString(), out number))
                    return number;
            }

            return reader.GetInt64();
        }

        public override void Write(Utf8JsonWriter writer, long longValue, JsonSerializerOptions options)
        {
            writer.WriteStringValue(longValue.ToString());
        }
    }
}

Tek tek özelliklerde bir özniteliği kullanarak long veya çeviriciyi koleksiyona ekleyerek bu özel dönüştürücüyü kaydettirin Converters .Register this custom converter by using an attribute on individual long properties or by adding the converter to the Converters collection.

Dize olmayan anahtarla sözlükDictionary with non-string key

Newtonsoft.Jsontüründeki koleksiyonları destekler Dictionary<TKey, TValue> .Newtonsoft.Json supports collections of type Dictionary<TKey, TValue>. ' Deki sözlük koleksiyonları için yerleşik destek System.Text.Json ile sınırlıdır Dictionary<string, TValue> .The built-in support for dictionary collections in System.Text.Json is limited to Dictionary<string, TValue>. Diğer bir deyişle, anahtar bir dize olmalıdır.That is, the key must be a string.

Anahtar olarak bir tamsayı veya diğer tür ile bir sözlüğü desteklemek için, özel dönüştürücüler yazmabölümünde örnek gibi bir dönüştürücü oluşturun.To support a dictionary with an integer or some other type as the key, create a converter like the example in How to write custom converters.

Polimorfik serileştirmePolymorphic serialization

Newtonsoft.Jsonotomatik olarak polimorfik serileştirme yapar.Newtonsoft.Json automatically does polymorphic serialization. ' Nin sınırlı çok biçimli serileştirme özellikleri hakkında daha fazla bilgi için System.Text.Json bkz. türetilmiş sınıfların serileştirme özellikleri.For information about the limited polymorphic serialization capabilities of System.Text.Json, see Serialize properties of derived classes.

Açıklanan geçici çözüm, türü olarak türetilmiş sınıflar içerebilen özellikleri tanımlamaktır object .The workaround described there is to define properties that may contain derived classes as type object. Bu mümkün değilse, diğer bir seçenek de Write özel dönüştürücüler yazmaiçindeki örnek gibi tüm devralma türü hiyerarşisi için bir yöntemle dönüştürücü oluşturmaktır.If that isn't possible, another option is to create a converter with a Write method for the whole inheritance type hierarchy like the example in How to write custom converters.

Polimorfik seri kaldırmaPolymorphic deserialization

Newtonsoft.Json``TypeNameHandlingserileştirme SıRASıNDA JSON 'a tür adı meta verileri ekleyen bir ayara sahiptir.Newtonsoft.Json has a TypeNameHandling setting that adds type name metadata to the JSON while serializing. Seri durumdan çıkarma sırasında çok biçimli seri kaldırma işlemi yaparken meta verileri kullanır.It uses the metadata while deserializing to do polymorphic deserialization. System.Text.Jsonçok sayıda polimorfik serileştirme , ancak polimorfik seri hale getirme işlemi yapabilir.System.Text.Json can do a limited range of polymorphic serialization but not polymorphic deserialization.

Polimorfik serisini desteklemek için özel dönüştürücüler yazmabölümünde örnek gibi bir dönüştürücü oluşturun.To support polymorphic deserialization, create a converter like the example in How to write custom converters.

Nesne özelliklerinin serisini kaldırmaDeserialization of object properties

Newtonsoft.JsonSeri Object hale geldiğinde:When Newtonsoft.Json deserializes to Object, it:

  • , JSON yükünde (dışındaki) ilkel değerlerin türünü null ve depolanan string , long , double , boolean veya DateTime paketlenmiş nesne olarak döndürür.Infers the type of primitive values in the JSON payload (other than null) and returns the stored string, long, double, boolean, or DateTime as a boxed object. İlkel değerler , JSON numarası, dize,, veya gıbı tek JSON değerleridir true false null .Primitive values are single JSON values such as a JSON number, string, true, false, or null.
  • JObject JArray JSON yükünde karmaşık değerler için bir veya döndürür.Returns a JObject or JArray for complex values in the JSON payload. Karmaşık değerler , küme ayracı () içinde JSON anahtar-değer çiftleri {} veya köşeli ayraç () içindeki değer listelerinde yer alan koleksiyonlardır [] .Complex values are collections of JSON key-value pairs within braces ({}) or lists of values within brackets ([]). Küme ayraçları ve köşeli ayraçlar içindeki Özellikler ve değerler ek özelliklere veya değerlere sahip olabilir.The properties and values within the braces or brackets can have additional properties or values.
  • Yükün JSON sabit değeri olduğunda bir null başvurusu döndürür null .Returns a null reference when the payload has the null JSON literal.

System.Text.JsonJsonElementseri durumdan çıkarma sırasında hem ilkel hem de karmaşık değerler için paketlenmiş bir depolar Object , örneğin:System.Text.Json stores a boxed JsonElement for both primitive and complex values whenever deserializing to Object, for example:

  • Bir object özellik.An object property.
  • objectSözlük değeri.An object dictionary value.
  • Bir object dizi değeri.An object array value.
  • Bir kök object .A root object.

Ancak, System.Text.Json null ile aynı şekilde davranır Newtonsoft.Json ve yük null içindeki JSON değişmez değeri olduğunda bir null başvurusu döndürür.However, System.Text.Json treats null the same as Newtonsoft.Json and returns a null reference when the payload has the null JSON literal in it.

Özellikler için tür çıkarımı uygulamak için object , özel dönüştürücüler yazmabölümünde örnek gibi bir dönüştürücü oluşturun.To implement type inference for object properties, create a converter like the example in How to write custom converters.

Null olamayan tür için null serisini kaldırmaDeserialize null to non-nullable type

Newtonsoft.JsonAşağıdaki senaryoda özel durum oluşturmaz:Newtonsoft.Json doesn't throw an exception in the following scenario:

  • NullValueHandling, olarak ayarlanır Ignore veNullValueHandling is set to Ignore, and
  • Seri durumdan çıkarma sırasında JSON null yapılamayan bir değer türü için null değer içerir.During deserialization, the JSON contains a null value for a non-nullable value type.

Aynı senaryoda System.Text.Json bir özel durum oluşturur.In the same scenario, System.Text.Json does throw an exception. (Karşılık gelen null işleme ayarı JsonSerializerOptions.IgnoreNullValues .)(The corresponding null handling setting is JsonSerializerOptions.IgnoreNullValues.)

Hedef türün sahibiyseniz, en iyi geçici çözüm, özelliğin boş değer atanabilir olması (örneğin, int olarak değiştirin int? ).If you own the target type, the best workaround is to make the property in question nullable (for example, change int to int?).

Farklı bir geçici çözüm, türler için null değerleri işleyen aşağıdaki örnek gibi tür için bir dönüştürücü hale getirme örneğidir DateTimeOffset :Another workaround is to make a converter for the type, such as the following example that handles null values for DateTimeOffset types:

using System;
using System.Globalization;
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)
        {
            if (reader.TokenType == JsonTokenType.Null)
            {
                return default;
            }
            return reader.GetDateTimeOffset();
        }

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

Bu özel dönüştürücüyü , özellik üzerindeki bir özniteliği kullanarak veya dönüştürücüyü koleksiyona ekleyerek kaydettirin Converters .Register this custom converter by using an attribute on the property or by adding the converter to the Converters collection.

Note: Yukarıdaki dönüştürücü, handles null values differently Newtonsoft.Json varsayılan değerleri belirten Pocos için, null değerleri farklı işler.Note: The preceding converter handles null values differently than Newtonsoft.Json does for POCOs that specify default values. Örneğin, aşağıdaki kodun hedef nesneniz temsil ettiğini varsayalım:For example, suppose the following code represents your target object:

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

Ve önceki dönüştürücüyü kullanarak aşağıdaki JSON 'nin seri durumdan çıkarıldığını varsayalım:And suppose the following JSON is deserialized by using the preceding converter:

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

Seri durumdan çıktıktan sonra, Date özelliği 1/1/0001 ( default(DateTimeOffset) ) değerini içerir, diğer bir deyişle, oluşturucuda ayarlanan değerin üzerine yazılır.After deserialization, the Date property has 1/1/0001 (default(DateTimeOffset)), that is, the value set in the constructor is overwritten. Aynı POCO ve JSON olarak verildiğinde, Newtonsoft.Json seri durumdan çıkarma özelliğinde 1/1/2001 ' i bırakır Date .Given the same POCO and JSON, Newtonsoft.Json deserialization would leave 1/1/2001 in the Date property.

Sabit sınıflar ve yapılar için seri durumdan çıkarmaDeserialize to immutable classes and structs

Newtonsoft.Jsonparametreleri olan oluşturucuları kullanabilmesi için, sabit sınıflar ve yapılar için seri hale getirebilirsiniz.Newtonsoft.Json can deserialize to immutable classes and structs because it can use constructors that have parameters. System.Text.Jsonyalnızca ortak parametresiz oluşturucuları destekler.System.Text.Json supports only public parameterless constructors. Geçici bir çözüm olarak, özel bir dönüştürücüde parametreleri olan bir Oluşturucu çağırabilirsiniz.As a workaround, you can call a constructor with parameters in a custom converter.

İşte birden çok Oluşturucu parametresi olan değişmez bir struct:Here's an immutable struct with multiple constructor parameters:

public readonly struct ImmutablePoint
{
    public ImmutablePoint(int x, int y)
    {
        X = x;
        Y = y;
    }

    public int X { get; }
    public int Y { get; }
}

İşte bu yapıyı seri hale getirir ve seri hale getirir:And here's a converter that serializes and deserializes this struct:

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

namespace SystemTextJsonSamples
{
    public class ImmutablePointConverter : JsonConverter<ImmutablePoint>
    {
        private readonly JsonEncodedText XName = JsonEncodedText.Encode("X");
        private readonly JsonEncodedText YName = JsonEncodedText.Encode("Y");

        private readonly JsonConverter<int> _intConverter;

        public ImmutablePointConverter(JsonSerializerOptions options)
        {
            if (options?.GetConverter(typeof(int)) is JsonConverter<int> intConverter)
            {
                _intConverter = intConverter;
            }
            else
            {
                throw new InvalidOperationException();
            }
        }

        public override ImmutablePoint Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options)
        {
            if (reader.TokenType != JsonTokenType.StartObject)
            {
                throw new JsonException();
            };

            int x = default;
            bool xSet = false;

            int y = default;
            bool ySet = false;

            // Get the first property.
            reader.Read();
            if (reader.TokenType != JsonTokenType.PropertyName)
            {
                throw new JsonException();
            }

            if (reader.ValueTextEquals(XName.EncodedUtf8Bytes))
            {
                x = ReadProperty(ref reader, options);
                xSet = true;
            }
            else if (reader.ValueTextEquals(YName.EncodedUtf8Bytes))
            {
                y = ReadProperty(ref reader, options);
                ySet = true;
            }
            else
            {
                throw new JsonException();
            }

            // Get the second property.
            reader.Read();
            if (reader.TokenType != JsonTokenType.PropertyName)
            {
                throw new JsonException();
            }

            if (xSet && reader.ValueTextEquals(YName.EncodedUtf8Bytes))
            {
                y = ReadProperty(ref reader, options);
            }
            else if (ySet && reader.ValueTextEquals(XName.EncodedUtf8Bytes))
            {
                x = ReadProperty(ref reader, options);
            }
            else
            {
                throw new JsonException();
            }

            reader.Read();

            if (reader.TokenType != JsonTokenType.EndObject)
            {
                throw new JsonException();
            }

            return new ImmutablePoint(x, y);
        }

        private int ReadProperty(ref Utf8JsonReader reader, JsonSerializerOptions options)
        {
            Debug.Assert(reader.TokenType == JsonTokenType.PropertyName);

            reader.Read();
            return _intConverter.Read(ref reader, typeof(int), options);
        }

        private void WriteProperty(Utf8JsonWriter writer, JsonEncodedText name, int intValue, JsonSerializerOptions options)
        {
            writer.WritePropertyName(name);
            _intConverter.Write(writer, intValue, options);
        }

        public override void Write(
            Utf8JsonWriter writer,
            ImmutablePoint point,
            JsonSerializerOptions options)
        {
            writer.WriteStartObject();
            WriteProperty(writer, XName, point.X, options);
            WriteProperty(writer, YName, point.Y, options);
            writer.WriteEndObject();
        }
    }
}

Dönüştürücüyü koleksiyona ekleyerek bu özel dönüştürücüyü kaydedin Converters .Register this custom converter by adding the converter to the Converters collection.

Açık genel özellikleri işleyen benzer dönüştürücünün bir örneği için bkz. anahtar-değer çiftleri için yerleşik dönüştürücü.For an example of a similar converter that handles open generic properties, see the built-in converter for key-value pairs.

Kullanılacak oluşturucuyu belirtinSpecify constructor to use

Newtonsoft.Json [JsonConstructor] Özniteliği bir poco 'ya seri durumdan çıkarılırken hangi oluşturucunun çağrılacağını belirtmenizi sağlar.The Newtonsoft.Json [JsonConstructor] attribute lets you specify which constructor to call when deserializing to a POCO. System.Text.Jsonyalnızca parametresiz oluşturucuları destekler.System.Text.Json supports only parameterless constructors. Geçici bir çözüm olarak, özel bir dönüştürücüde hangi oluşturucuyu ihtiyacınız olduğunu çağırabilirsiniz.As a workaround, you can call whichever constructor you need in a custom converter. Sabit sınıflar ve yapılar Için seri durumdan çıkarmaörneğine bakın.See the example for Deserialize to immutable classes and structs.

Gerekli özelliklerRequired properties

' De Newtonsoft.Json , özniteliği için bir özelliğin gerekli olduğunu belirtirsiniz Required [JsonProperty] .In Newtonsoft.Json, you specify that a property is required by setting Required on the [JsonProperty] attribute. Newtonsoft.JsonJSON içinde gerekli olarak işaretlenmiş bir özellik için hiçbir değer alınmadığında bir özel durum oluşturur.Newtonsoft.Json throws an exception if no value is received in the JSON for a property marked as required.

System.Text.Jsonhedef türün özelliklerinden biri için hiçbir değer alınmazsa özel durum oluşturmaz.System.Text.Json doesn't throw an exception if no value is received for one of the properties of the target type. Örneğin, bir WeatherForecast sınıfınız varsa:For example, if you have a WeatherForecast class:

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

Aşağıdaki JSON, hata olmadan seri durumdan çıkarılacak:The following JSON is deserialized without error:

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

JSON içinde herhangi bir özellik yoksa seriyi kaldırma başarısız olması için Date özel bir dönüştürücü uygulayın.To make deserialization fail if no Date property is in the JSON, implement a custom converter. Aşağıdaki örnek dönüştürücü kodu, Date seri kaldırma tamamlandıktan sonra özellik ayarlanmamışsa bir özel durum oluşturur:The following sample converter code throws an exception if the Date property isn't set after deserialization is complete:

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

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

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

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

Dönüştürücüyü koleksiyona ekleyerek bu özel dönüştürücüyü kaydedin JsonSerializerOptions.Converters .Register this custom converter by adding the converter to the JsonSerializerOptions.Converters collection.

Dönüştürücüyü yinelemeli olarak çağırmanın bu deseninin JsonSerializerOptions bir özniteliği kullanarak değil kullanarak dönüştürücüyü kaydetmesi gerekir.This pattern of recursively calling the converter requires that you register the converter by using JsonSerializerOptions, not by using an attribute. Dönüştürücüyü bir özniteliği kullanarak kaydettiğinizde, özel dönüştürücü özyinelemeli olarak kendine çağırır.If you register the converter by using an attribute, the custom converter recursively calls into itself. Sonuç, yığın taşması özel durumuyla biten sonsuz bir döngüdür.The result is an infinite loop that ends in a stack overflow exception.

Options nesnesini kullanarak dönüştürücüyü kaydettiğinizde, veya özyinelemeli bir döngüden, yinelemeli olarak veya çağrılırken Options nesnesine geçirilmeyen bir döngüden kaçının Serialize Deserialize .When you register the converter by using the options object, avoid an infinite loop by not passing in the options object when recursively calling Serialize or Deserialize. Options nesnesi Converters koleksiyonu içerir.The options object contains the Converters collection. Veya ' a geçirirseniz, Serialize Deserialize özel dönüştürücü kendi kendine çağrı yapar ve yığın taşması özel durumuna neden olan sonsuz bir döngü sağlar.If you pass it in to Serialize or Deserialize, the custom converter calls into itself, making an infinite loop that results in a stack overflow exception. Varsayılan seçenekler uygun değilse, gereken ayarlarla seçeneklerin yeni bir örneğini oluşturun.If the default options are not feasible, create a new instance of the options with the settings that you need. Her yeni örnek bağımsız olarak önbelleğe aldığından bu yaklaşım yavaş olur.This approach will be slow since each new instance caches independently.

Dönüştürülecek sınıfta kayıt kullanılabilecek alternatif bir model vardır JsonConverterAttribute .There is an alternative pattern that can use JsonConverterAttribute registration on the class to be converted. Bu yaklaşımda dönüştürücü kodu, Serialize Deserialize dönüştürülecek sınıftan türeyen bir sınıfı çağırır.In this approach, the converter code calls Serialize or Deserialize on a class that derives from the class to be converted. Türetilmiş sınıf JsonConverterAttribute kendisine uygulanmış değil.The derived class doesn't have a JsonConverterAttribute applied to it. Aşağıdaki örnekte, bu alternatif aşağıda verilmiştir:In the following example of this alternative:

  • WeatherForecastWithRequiredPropertyConverterAttribute, seri durumdan çıkarılacak ve ona uygulanmış olan sınıftır JsonConverterAttribute .WeatherForecastWithRequiredPropertyConverterAttribute is the class to be deserialized and has the JsonConverterAttribute applied to it.
  • WeatherForecastWithoutRequiredPropertyConverterAttribute, Converter özniteliğine sahip olmayan türetilmiş sınıftır.WeatherForecastWithoutRequiredPropertyConverterAttribute is the derived class that doesn't have the converter attribute.
  • Dönüştürücüdeki kod, Serialize Deserialize WeatherForecastWithoutRequiredPropertyConverterAttribute sonsuz bir döngüden kaçınmak için ve öğesini çağırır.The code in the converter calls Serializeand Deserialize on WeatherForecastWithoutRequiredPropertyConverterAttribute to avoid an infinite loop. Ek bir nesne örneklemesi ve özellik değerlerinin kopyalanması nedeniyle serileştirme üzerinde bu yaklaşımın performans maliyeti vardır.There is a performance cost to this approach on serialization due to an extra object instantiation and copying of property values.

WeatherForecast*Türler şunlardır:Here are the WeatherForecast* types:

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

public class WeatherForecastWithoutRequiredPropertyConverterAttribute : WeatherForecastWithRequiredPropertyConverterAttribute
{
}

Dönüştürücü şöyledir:And here is the converter:

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

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

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

            return forecast;
        }

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

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

Gerekli özellikler Dönüştürücüsü, [Jsonıgnore] gibi öznitelikleri veya özel kodlayıcılar gibi farklı seçenekleri işlemeniz gerekiyorsa ek mantık gerektirir.The required properties converter would require additional logic if you need to handle attributes such as [JsonIgnore] or different options, such as custom encoders. Ayrıca, örnek kod, oluşturucuda varsayılan bir değer ayarlanan özellikleri işlemez.Also, the example code doesn't handle properties for which a default value is set in the constructor. Bu yaklaşım aşağıdaki senaryolar arasında ayrım yapmaz:And this approach doesn't differentiate between the following scenarios:

  • JSON 'da bir özellik eksik.A property is missing from the JSON.
  • Null atanamaz bir tür için bir özellik JSON içinde bulunur, ancak değer, türü için sıfır gibi varsayılan değerdir int .A property for a non-nullable type is present in the JSON, but the value is the default for the type, such as zero for an int.
  • JSON 'da null olabilen bir değer türü özelliği var, ancak değer null.A property for a nullable value type is present in the JSON, but the value is null.

Özelliği koşullu olarak YoksayConditionally ignore a property

Newtonsoft.Jsonserileştirme veya seri durumdan çıkarma için bir özelliği koşullu olarak yoksaymanın birkaç yolu vardır:Newtonsoft.Json has several ways to conditionally ignore a property on serialization or deserialization:

  • DefaultContractResolverRastgele ölçütlere göre dahil edilecek veya hariç tutulacak özellikleri seçmenizi sağlar.DefaultContractResolver lets you select properties to include or exclude, based on arbitrary criteria.
  • NullValueHandlingVe DefaultValueHandling ayarları, JsonSerializerSettings tüm null değer veya varsayılan değer özelliklerinin yoksayılmasını belirtmenize izin verir.The NullValueHandling and DefaultValueHandling settings on JsonSerializerSettings let you specify that all null-value or default-value properties should be ignored.
  • NullValueHandling DefaultValueHandling Öznitelikteki ve ayarları, [JsonProperty] null veya varsayılan değer olarak ayarlandığında yoksayılacak tek tek özellikleri belirtmenize izin verir.The NullValueHandling and DefaultValueHandling settings on the [JsonProperty] attribute let you specify individual properties that should be ignored when set to null or the default value.

System.Text.Jsonserileştirilirken özellikleri atlamak için aşağıdaki yolları sağlar:System.Text.Json provides the following ways to omit properties while serializing:

  • Bir özellikte [Jsonıgnore] özniteliği, serileştirme SıRASıNDA özelliğin JSON 'dan atlanmasına neden olur.The [JsonIgnore] attribute on a property causes the property to be omitted from the JSON during serialization.
  • Ignorenullvalues genel seçeneği, tüm null değerli özellikleri dışlamanızı sağlar.The IgnoreNullValues global option lets you exclude all null-value properties.
  • Ignorereadonlyproperties genel seçeneği, tüm salt okunurdur özellikleri dışlamanızı sağlar.The IgnoreReadOnlyProperties global option lets you exclude all read-only properties.

Bu seçenekler şunları yapmanızı sağlar :These options don't let you:

  • Türü için varsayılan değere sahip tüm özellikleri yoksayın.Ignore all properties that have the default value for the type.
  • Türü için varsayılan değere sahip seçili özellikleri yoksayın.Ignore selected properties that have the default value for the type.
  • Değerleri null ise seçili özellikleri yoksayın.Ignore selected properties if their value is null.
  • Çalışma zamanında değerlendirilen rastgele ölçütlere göre seçili özellikleri yoksayın.Ignore selected properties based on arbitrary criteria evaluated at run time.

Bu işlevsellik için özel bir dönüştürücü yazabilirsiniz.For that functionality, you can write a custom converter. İşte bu yaklaşımı gösteren örnek bir POCO ve özel dönüştürücü.Here's a sample POCO and a custom converter for it that illustrates this approach:

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}
using System;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class WeatherForecastRuntimeIgnoreConverter : JsonConverter<WeatherForecast>
    {
        public override WeatherForecast Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options)
        {
            if (reader.TokenType != JsonTokenType.StartObject)
            {
                throw new JsonException();
            }

            var wf = new WeatherForecast();

            while (reader.Read())
            {
                if (reader.TokenType == JsonTokenType.EndObject)
                {
                    return wf;
                }

                if (reader.TokenType == JsonTokenType.PropertyName)
                {
                    string propertyName = reader.GetString();
                    reader.Read();
                    switch (propertyName)
                    {
                        case "Date":
                            DateTimeOffset date = reader.GetDateTimeOffset();
                            wf.Date = date;
                            break;
                        case "TemperatureCelsius":
                            int temperatureCelsius = reader.GetInt32();
                            wf.TemperatureCelsius = temperatureCelsius;
                            break;
                        case "Summary":
                            string summary = reader.GetString();
                            wf.Summary = string.IsNullOrWhiteSpace(summary) ? "N/A" : summary;
                            break;
                    }
                }
            }

            throw new JsonException();
        }

        public override void Write(Utf8JsonWriter writer, WeatherForecast wf, JsonSerializerOptions options)
        {
            writer.WriteStartObject();

            writer.WriteString("Date", wf.Date);
            writer.WriteNumber("TemperatureCelsius", wf.TemperatureCelsius);
            if (!string.IsNullOrWhiteSpace(wf.Summary) && wf.Summary != "N/A")
            {
                writer.WriteString("Summary", wf.Summary);
            }

            writer.WriteEndObject();
        }
    }
}

Dönüştürücü, Summary değeri null, boş bir dize veya "N/A" ise, özelliğin Serileştirmeden atlanmasına neden olur.The converter causes the Summary property to be omitted from serialization if its value is null, an empty string, or "N/A".

Bu özel dönüştürücüyü sınıfında bir özniteliği kullanarak veya dönüştürücüyü koleksiyona ekleyerek kaydedin Converters .Register this custom converter by using an attribute on the class or by adding the converter to the Converters collection.

Bu yaklaşım aşağıdaki durumlarda ek mantık gerektirir:This approach requires additional logic if:

  • POCO, karmaşık özellikler içerir.The POCO includes complex properties.
  • Gibi öznitelikleri [JsonIgnore] veya özel kodlayıcılar gibi seçenekleri işlemeniz gerekir.You need to handle attributes such as [JsonIgnore] or options such as custom encoders.

Tarih biçimini belirtinSpecify date format

Newtonsoft.Json, DateTime ve DateTimeOffset türlerinin özelliklerinin serileştirilme ve seri durumdan çıkarılme biçimini denetlemek için çeşitli yollar sağlar:Newtonsoft.Json provides several ways to control how properties of DateTime and DateTimeOffset types are serialized and deserialized:

  • DateTimeZoneHandlingAyar, tüm DateTime değerleri UTC tarihleri olarak seri hale getirmek için kullanılabilir.The DateTimeZoneHandling setting can be used to serialize all DateTime values as UTC dates.
  • DateFormatStringAyar ve DateTime dönüştürücüler, tarih dizelerinin biçimini özelleştirmek için kullanılabilir.The DateFormatString setting and DateTime converters can be used to customize the format of date strings.

' De System.Text.Json , yerleşik desteği olan tek BIÇIM ıso 8601-1:2019 ' dir ve bu yana büyük ölçüde benimsediğinden ve tam olarak gidiş dönüş yaptığından emin olur.In System.Text.Json, the only format that has built-in support is ISO 8601-1:2019 since it's widely adopted, unambiguous, and makes round trips precisely. Başka bir biçim kullanmak için özel bir dönüştürücü oluşturun.To use any other format, create a custom converter. Daha fazla bilgi için, bkz. ' de System.Text.Json DateTime ve DateTimeOffset desteği .For more information, see DateTime and DateTimeOffset support in System.Text.Json.

Geri ÇağırmalarCallbacks

Newtonsoft.Jsonserileştirme veya seri kaldırma işleminde özel kodu birkaç noktada yürütmenize imkan tanır:Newtonsoft.Json lets you execute custom code at several points in the serialization or deserialization process:

  • Onserisini kaldırma (bir nesnenin serisini kaldırmada başlayan)OnDeserializing (when beginning to deserialize an object)
  • Onseri durumdan çıkarılan (bir nesnenin serisini kaldırma tamamlandığında)OnDeserialized (when finished deserializing an object)
  • Onserileştirilme (bir nesne seri hale getirilmeye Başlarken)OnSerializing (when beginning to serialize an object)
  • Onserileştirilmiş (bir nesne serileştirildiğinde)OnSerialized (when finished serializing an object)

System.Text.Json' De, özel bir dönüştürücü yazarak geri çağırmaların benzetimini yapabilirsiniz.In System.Text.Json, you can simulate callbacks by writing a custom converter. Aşağıdaki örnek bir POCO için özel dönüştürücüyü gösterir.The following example shows a custom converter for a POCO. Dönüştürücü, bir geri aramaya karşılık gelen her bir noktada bir ileti görüntüleyen kodu içerir Newtonsoft.Json .The converter includes code that displays a message at each point that corresponds to a Newtonsoft.Json callback.

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

namespace SystemTextJsonSamples
{
    public class WeatherForecastCallbacksConverter : JsonConverter<WeatherForecast>
    {
        public override WeatherForecast Read(
            ref Utf8JsonReader reader,
            Type type,
            JsonSerializerOptions options)
        {
            // Place "before" code here (OnDeserializing),
            // but note that there is no access here to the POCO instance.
            Console.WriteLine("OnDeserializing");

            // Don't pass in options when recursively calling Deserialize.
            WeatherForecast forecast = JsonSerializer.Deserialize<WeatherForecast>(ref reader);

            // Place "after" code here (OnDeserialized)
            Console.WriteLine("OnDeserialized");

            return forecast;
        }

        public override void Write(
            Utf8JsonWriter writer,
            WeatherForecast forecast, JsonSerializerOptions options)
        {
            // Place "before" code here (OnSerializing)
            Console.WriteLine("OnSerializing");

            // Don't pass in options when recursively calling Serialize.
            JsonSerializer.Serialize(writer, forecast);

            // Place "after" code here (OnSerialized)
            Console.WriteLine("OnSerialized");
        }
    }
}

Dönüştürücüyü koleksiyona ekleyerek bu özel dönüştürücüyü kaydedin Converters .Register this custom converter by adding the converter to the Converters collection.

Önceki örneği takip eden özel bir dönüştürücü kullanıyorsanız:If you use a custom converter that follows the preceding sample:

  • OnDeserializingKodun yenı POCO örneğine erişimi yok.The OnDeserializing code doesn't have access to the new POCO instance. Yeni POCO örneğini serisini kaldırma başlangıcında işlemek için, bu kodu POCO yapıcısına koyun.To manipulate the new POCO instance at the start of deserialization, put that code in the POCO constructor.
  • Özyinelemeli bir döngüden kaçınarak, Seçenekler nesnesine dönüştürücüyü kaydederek ve yinelemeli olarak ya da çağrılırken Options nesnesine geçirmekten kaçının Serialize Deserialize .Avoid an infinite loop by registering the converter in the options object and not passing in the options object when recursively calling Serialize or Deserialize.

Yinelemeli olarak çağıran özel dönüştürücüler hakkında daha fazla bilgi Serialize için Deserialize , bu makalenin önceki kısımlarında yer alan gerekli özellikler bölümüne bakın.For more information about custom converters that recursively call Serialize or Deserialize, see the Required properties section earlier in this article.

Ortak ve genel olmayan alanlarPublic and non-public fields

Newtonsoft.Jsonalanları seri hale getirmek ve seri durumdan çıkarmak için özellikleri.Newtonsoft.Json can serialize and deserialize fields as well as properties. System.Text.Jsonyalnızca ortak özelliklerle birlikte kullanılabilir.System.Text.Json only works with public properties. Özel dönüştürücüler, bu işlevselliği sağlayabilir.Custom converters can provide this functionality.

İç ve özel özellik ayarlayıcıları ve alıcılarInternal and private property setters and getters

Newtonsoft.Jsonözniteliği aracılığıyla özel ve iç özellik ayarlayıcıları ve alıcıları öğeleri kullanılabilir JsonProperty .Newtonsoft.Json can use private and internal property setters and getters via the JsonProperty attribute. System.Text.Jsonyalnızca genel ayarlayıcıları destekler.System.Text.Json supports only public setters. Özel dönüştürücüler, bu işlevselliği sağlayabilir.Custom converters can provide this functionality.

Mevcut nesneleri doldurPopulate existing objects

JsonConvert.PopulateObjectİçindeki yöntemi, BIR Newtonsoft.Json JSON belgesini, yeni bir örnek oluşturmak yerine, bir sınıfın varolan bir örneğine kaldırma.The JsonConvert.PopulateObject method in Newtonsoft.Json deserializes a JSON document to an existing instance of a class, instead of creating a new instance. System.Text.Jsonher zaman varsayılan genel parametresiz oluşturucuyu kullanarak hedef türün yeni bir örneğini oluşturur.System.Text.Json always creates a new instance of the target type by using the default public parameterless constructor. Özel dönüştürücüler, var olan bir örneğe serisini kaldıramıyor.Custom converters can deserialize to an existing instance.

Özellikleri değiştirmek yerine yeniden kullanReuse rather than replace properties

Newtonsoft.Json ObjectCreationHandling Ayar, özellikleri içindeki nesnelerin seri durumundan çıkarma sırasında yerine kullanılması gerektiğini belirtmenize olanak tanır.The Newtonsoft.Json ObjectCreationHandling setting lets you specify that objects in properties should be reused rather than replaced during deserialization. System.Text.Jsonher zaman özelliklerde nesneleri değiştirir.System.Text.Json always replaces objects in properties. Özel dönüştürücüler, bu işlevselliği sağlayabilir.Custom converters can provide this functionality.

Ayarlayıcısız koleksiyonlara EkleAdd to collections without setters

Seri durumundan çıkarma sırasında, Newtonsoft.Json özelliğin ayarlayıcısı olmasa bile nesneleri bir koleksiyona ekler.During deserialization, Newtonsoft.Json adds objects to a collection even if the property has no setter. System.Text.Jsonayarlayıcıları olmayan özellikleri yoksayar.System.Text.Json ignores properties that don't have setters. Özel dönüştürücüler, bu işlevselliği sağlayabilir.Custom converters can provide this functionality.

JsonSerializer 'ın Şu anda desteklemediği senaryolarScenarios that JsonSerializer currently doesn't support

Aşağıdaki senaryolar için geçici çözümler pratik veya mümkün değildir.For the following scenarios, workarounds are not practical or possible. Bu özelliklerden yararlandıysanız Newtonsoft.Json geçiş önemli değişiklikler yapılmadan mümkün olmayacaktır.If you rely on these Newtonsoft.Json features, migration will not be possible without significant changes.

Nesne başvurularını koruma ve döngüleri işlemePreserve object references and handle loops

Varsayılan olarak, Newtonsoft.Json değere göre serileştirir.By default, Newtonsoft.Json serializes by value. Örneğin, bir nesne aynı nesneye bir başvuru içeren iki özellik içeriyorsa Person , bu Person nesnenin ÖZELLIKLERININ değerleri JSON içinde yinelenir.For example, if an object contains two properties that contain a reference to the same Person object, the values of that Person object's properties are duplicated in the JSON.

Newtonsoft.Json, PreserveReferencesHandling JsonSerializerSettings başvuruya göre serileştirmenize olanak sağlayan üzerinde bir ayarı vardır:Newtonsoft.Json has a PreserveReferencesHandling setting on JsonSerializerSettings that lets you serialize by reference:

  • İlk nesne için oluşturulan JSON 'a bir tanımlayıcı meta verileri eklenir Person .An identifier metadata is added to the JSON created for the first Person object.
  • İkinci nesne için oluşturulan JSON, Person özellik değerleri yerine bu tanımlayıcıya bir başvuru içerir.The JSON that is created for the second Person object contains a reference to that identifier instead of property values.

Newtonsoft.JsonAyrıca, ReferenceLoopHandling bir özel durum oluşturmak yerine döngüsel başvuruları yoksaymanıza imkan tanıyan bir ayara sahiptir.Newtonsoft.Json also has a ReferenceLoopHandling setting that lets you ignore circular references rather than throw an exception.

System.Text.Jsonyalnızca değere göre serileştirme destekler ve döngüsel başvurular için bir özel durum oluşturur.System.Text.Json only supports serialization by value and throws an exception for circular references.

System. Runtime. Serialization öznitelikleriSystem.Runtime.Serialization attributes

System.Text.JsonSystem.Runtime.Serialization, ve gibi ad alanındaki öznitelikleri desteklemez DataMemberAttribute IgnoreDataMemberAttribute .System.Text.Json doesn't support attributes from the System.Runtime.Serialization namespace, such as DataMemberAttribute and IgnoreDataMemberAttribute.

Sekizlik sayılarOctal numbers

Newtonsoft.Jsonsayıları, sekizli sayı olarak önünde sıfır ile değerlendirir.Newtonsoft.Json treats numbers with a leading zero as octal numbers. System.Text.JsonRFC 8259 belirtimi bunlara izin vermediğinden önde gelen sıfıra izin vermez.System.Text.Json doesn't allow leading zeroes because the RFC 8259 specification doesn't allow them.

MissingMemberHandlingMissingMemberHandling

Newtonsoft.JsonJSON, hedef türünde eksik olan özellikler içeriyorsa, seri durumdan çıkarma sırasında özel durumlar atmak üzere yapılandırılabilir.Newtonsoft.Json can be configured to throw exceptions during deserialization if the JSON includes properties that are missing in the target type. System.Text.Json[Jsonextensiondata] özniteliğinikullandığınız durumlar dışında, JSON 'daki ek özellikleri yoksayar.System.Text.Json ignores extra properties in the JSON, except when you use the [JsonExtensionData] attribute. Eksik üye özelliği için geçici çözüm yoktur.There's no workaround for the missing member feature.

TraceWriterTraceWriter

Newtonsoft.Json``TraceWriterserileştirme veya seri durumdan çıkarma tarafından oluşturulan günlükleri görüntülemek için kullanarak hata ayıklamanıza olanak sağlar.Newtonsoft.Json lets you debug by using a TraceWriter to view logs that are generated by serialization or deserialization. System.Text.Jsongünlüğe kaydetme yapmaz.System.Text.Json doesn't do logging.

JToken (JObject, JArray gibi) ile karşılaştırılan JsonDocument ve JsonElementJsonDocument and JsonElement compared to JToken (like JObject, JArray)

System.Text.Json.JsonDocument, var olan JSON yüklerden salt okunurdur belge nesne MODELI (DOM) ayrıştırabilme ve derleme olanağı sağlar.System.Text.Json.JsonDocument provides the ability to parse and build a read-only Document Object Model (DOM) from existing JSON payloads. DOM, bir JSON yükünde verilere rastgele erişim sağlar.The DOM provides random access to data in a JSON payload. Yükü oluşturan JSON öğelerine tür aracılığıyla erişilebilir JsonElement .The JSON elements that compose the payload can be accessed via the JsonElement type. JsonElementTürü, JSON metnini ortak .net türlerine dönüştürmek Için API 'ler sağlar.The JsonElement type provides APIs to convert JSON text to common .NET types. JsonDocumentbir RootElement özellik sunar.JsonDocument exposes a RootElement property.

JsonDocument, IDisposableJsonDocument is IDisposable

JsonDocumenthavuza alınmış arabellekte verilerin bellek içi bir görünümünü oluşturur.JsonDocument builds an in-memory view of the data into a pooled buffer. Bu nedenle, veya öğelerinden farklı olarak JObject JArray Newtonsoft.Json , JsonDocument türü, IDisposable bir using bloğu içinde kullanılması gerekir.Therefore, unlike JObject or JArray from Newtonsoft.Json, the JsonDocument type implements IDisposable and needs to be used inside a using block.

Yalnızca API 'nizden JsonDocument , yaşam süresi sahipliğini aktarmak ve arayan sorumluluğunu atmak istiyorsanız ' ı geri döndürün.Only return a JsonDocument from your API if you want to transfer lifetime ownership and dispose responsibility to the caller. Çoğu senaryoda, bu gerekli değildir.In most scenarios, that isn't necessary. Çağıranın tüm JSON belgesi ile çalışması gerekiyorsa, Clone RootElement ' ın ' i döndürün JsonElement .If the caller needs to work with the entire JSON document, return the Clone of the RootElement, which is a JsonElement. Çağıranın JSON belgesi içinde belirli bir öğeyle çalışması gerekiyorsa, ' ın ' i döndürün Clone JsonElement .If the caller needs to work with a particular element within the JSON document, return the Clone of that JsonElement. Ya da bir RootElement alt öğeyi doğrudan bir olmadan geri Clone döndürülürsünüz, çağıran, JsonElement JsonDocument kendisine ait olan öğesinden sonra döndürülen öğesine erişemez.If you return the RootElement or a sub-element directly without making a Clone, the caller won't be able to access the returned JsonElement after the JsonDocument that owns it is disposed.

İşte şunları yapmanızı gerektiren bir örnek Clone :Here's an example that requires you to make a Clone:

public JsonElement LookAndLoad(JsonElement source)
{
    string json = File.ReadAllText(source.GetProperty("fileName").GetString());

    using (JsonDocument doc = JsonDocument.Parse(json))
    {
        return doc.RootElement.Clone();
    }
}

Yukarıdaki kod, bir özellik içeren bir için bekliyor JsonElement fileName .The preceding code expects a JsonElement that contains a fileName property. JSON dosyasını açar ve bir oluşturur JsonDocument .It opens the JSON file and creates a JsonDocument. Yöntemi, çağıranın tüm belge ile çalışmak istediğini varsayar, bu yüzden öğesinin öğesini döndürür Clone RootElement .The method assumes that the caller wants to work with the entire document, so it returns the Clone of the RootElement.

Bir alır ve bir JsonElement alt öğe döndürüyorsa, alt öğenin bir kısmını döndürmek gerekli değildir Clone .If you receive a JsonElement and are returning a sub-element, it's not necessary to return a Clone of the sub-element. Çağıran, JsonDocument geçirilen ' ın ait olduğu canlı tutmanın sorumluluğundadır JsonElement .The caller is responsible for keeping alive the JsonDocument that the passed-in JsonElement belongs to. Örnek:For example:

public JsonElement ReturnFileName(JsonElement source)
{
   return source.GetProperty("fileName");
}

JsonDocument salt okunurdurJsonDocument is read-only

System.Text.JsonDom, JSON öğeleri ekleyemez, kaldıramaz veya değiştiremez.The System.Text.Json DOM can't add, remove, or modify JSON elements. Bu, performans için bu şekilde tasarlanmıştır ve ortak JSON yük boyutlarını (yani, < 1 MB) ayrıştırmak için ayırmaları azaltır.It's designed this way for performance and to reduce allocations for parsing common JSON payload sizes (that is, < 1 MB). Senaryonuz Şu anda değiştirilebilir bir DOM kullanıyorsa, aşağıdaki geçici çözümlerden biri uygulanabilir olabilir:If your scenario currently uses a modifiable DOM, one of the following workarounds might be feasible:

  • Sıfırdan bir oluşturmak için JsonDocument (diğer bir deyişle, varolan BIR JSON yükünü Parse yöntemine geçirmeden), kullanarak JSON metnini yazın Utf8JsonWriter ve yeni bir yapmak için çıktıyı ayrıştırın JsonDocument .To build a JsonDocument from scratch (that is, without passing in an existing JSON payload to the Parse method), write the JSON text by using the Utf8JsonWriter and parse the output from that to make a new JsonDocument.
  • Varolan bir değişikliği değiştirmek için JsonDocument , JSON metni yazmak, yazarken değişiklikler yapmak ve yeni bir hale getirmek için bu çıkışı ayrıştırmak üzere kullanın JsonDocument .To modify an existing JsonDocument, use it to write JSON text, making changes while you write, and parse the output from that to make a new JsonDocument.
  • Var olan JSON belgelerini, veya API 'leri ile eşdeğer olacak şekilde birleştirmek için JObject.Merge JContainer.Merge Newtonsoft.Json Bu GitHub sorununabakın.To merge existing JSON documents, equivalent to the JObject.Merge or JContainer.Merge APIs from Newtonsoft.Json, see this GitHub issue.

JsonElement bir UNION yapısıJsonElement is a union struct

JsonDocumentbir RootElement JsonElement UNION, HERHANGI bir JSON öğesini kapsayan yapı türü olan türü bir özellik olarak gösterir.JsonDocument exposes the RootElement as a property of type JsonElement, which is a union, struct type that encompasses any JSON element. Newtonsoft.Json,, ve gibi adanmış sıradüzenli türler kullanır JObject JArray JToken .Newtonsoft.Json uses dedicated hierarchical types like JObject,JArray, JToken, and so forth. JsonElementüzerinde arama ve listeleme yapabilecekleriniz vardır ve JsonElement JSON öğelerini .net türlerine getirmek için kullanabilirsiniz.JsonElement is what you can search and enumerate over, and you can use JsonElement to materialize JSON elements into .NET types.

Bir JsonDocument ve JsonElement öğelerini alt öğeler için aramaHow to search a JsonDocument and JsonElement for sub-elements

JObject JArray Bazı sözlüklerde arama yapıldığından, ya da ' dan veya ' den yararlanarak JSON belirteçlerini arar Newtonsoft.Json .Searches for JSON tokens using JObject or JArray from Newtonsoft.Json tend to be relatively fast because they're lookups in some dictionary. Karşılaştırmayla, ' deki aramalar JsonElement Özellikler için sıralı bir arama gerektirir ve bu nedenle nispeten yavaş olur (örneğin, kullanılırken TryGetProperty ).By comparison, searches on JsonElement require a sequential search of the properties and hence is relatively slow (for example when using TryGetProperty). System.Text.JsonArama süresi yerine ilk ayrıştırma süresini en aza indirmek için tasarlanmıştır.System.Text.Json is designed to minimize initial parse time rather than lookup time. Bu nedenle, bir nesnede arama yaparken performansı iyileştirmek için aşağıdaki yaklaşımları kullanın JsonDocument :Therefore, use the following approaches to optimize performance when searching through a JsonDocument object:

  • EnumerateArray EnumerateObject Kendi dizin oluşturma veya döngülerinizi yapmak yerine yerleşik numaralandırıcıları (ve) kullanın.Use the built-in enumerators (EnumerateArray and EnumerateObject) rather than doing your own indexing or loops.
  • Kullanarak her bir özelliğin tamamında sıralı bir arama yapmayın JsonDocument RootElement .Don't do a sequential search on the whole JsonDocument through every property by using RootElement. Bunun yerine, JSON verilerinin bilinen yapısına bağlı olarak iç içe geçmiş JSON nesnelerinde arama yapın.Instead, search on nested JSON objects based on the known structure of the JSON data. Örneğin, Grade nesnelerde bir özelliği arıyorsanız Student , özellikler için arama yapmak yerine nesneler üzerinde döngü yapın Student ve Grade her biri için değerini alın JsonElement Grade .For example, if you're looking for a Grade property in Student objects, loop through the Student objects and get the value of Grade for each, rather than searching through all JsonElement objects looking for Grade properties. İkincisini yapmak, aynı verilerin üzerinde gereksiz bir şekilde geçiş oluşmasına neden olur.Doing the latter will result in unnecessary passes over the same data.

Kod örneği için bkz. veri erişimi Için JsonDocument kullanma.For a code example, see Use JsonDocument for access to data.

Utf8JsonReader, JsonTextReader ile karşılaştırılırUtf8JsonReader compared to JsonTextReader

System.Text.Json.Utf8JsonReader, UTF-8 kodlu JSON metnine yönelik yüksek performanslı, düşük bir ayırma, Salt ilet okuyucu, Readonlyspan <byte> veya readonlysequence <byte> tarafından okunabilir.System.Text.Json.Utf8JsonReader is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a ReadOnlySpan<byte> or ReadOnlySequence<byte>. , Utf8JsonReader Özel Çözümleyicileri ve seri hale getiriciler oluşturmak için kullanılabilen alt düzey bir türdür.The Utf8JsonReader is a low-level type that can be used to build custom parsers and deserializers.

Aşağıdaki bölümlerde, kullanımı için önerilen programlama düzenleri açıklanmaktadır Utf8JsonReader .The following sections explain recommended programming patterns for using Utf8JsonReader.

Utf8JsonReader bir başvuru yapısıUtf8JsonReader is a ref struct

Utf8JsonReaderTür bir başvuru yapısıolduğundan, belirli sınırlamalarvardır.Because the Utf8JsonReader type is a ref struct, it has certain limitations. Örneğin, bir sınıf veya yapı üzerinde bir başvuru yapısı dışında bir alan olarak depolanamaz.For example, it can't be stored as a field on a class or struct other than a ref struct. Yüksek performans elde etmek için, bu tür bir ref struct başvuru yapısı olan giriş <byte> readonlyspan' i önbelleğe alma gerektirdiğinden bir olmalıdır.To achieve high performance, this type must be a ref struct since it needs to cache the input ReadOnlySpan<byte>, which itself is a ref struct. Ayrıca, bu tür durum taşıdığı için değişebilir olur.In addition, this type is mutable since it holds state. Bu nedenle, bunu değere göre değil ref 'e geçirin .Therefore, pass it by ref rather than by value. Değere göre geçirmek bir yapı kopyasının oluşmasına neden olur ve durum değişiklikleri arayan tarafından görülemez.Passing it by value would result in a struct copy and the state changes would not be visible to the caller. Bu, öğesinden bu yana farklılık gösterir Newtonsoft.Json Newtonsoft.Json JsonTextReader .This differs from Newtonsoft.Json since the Newtonsoft.Json JsonTextReader is a class. Başvuru yapıları kullanma hakkında daha fazla bilgi için bkz. Write Safe ve verimli C# kodu.For more information about how to use ref structs, see Write safe and efficient C# code.

UTF-8 metnini okuRead UTF-8 text

Kullanırken en iyi performansı elde etmek için Utf8JsonReader , UTF-16 dizeleri yerine zaten UTF-8 ile KODLANMıŞ JSON yüklerini okuyun.To achieve the best possible performance while using the Utf8JsonReader, read JSON payloads already encoded as UTF-8 text rather than as UTF-16 strings. Kod örneği için bkz. Utf8JsonReader kullanarak filtre verileri.For a code example, see Filter data using Utf8JsonReader.

Stream veya Pıpereader ile okumaRead with a Stream or PipeReader

, Utf8JsonReader UTF-8 kodlamalı Readonlyspan <byte> veya <byte> readonlysequence (bir öğesinden okuma sonucu) ile okumayı destekler PipeReader .The Utf8JsonReader supports reading from a UTF-8 encoded ReadOnlySpan<byte> or ReadOnlySequence<byte> (which is the result of reading from a PipeReader).

Zaman uyumlu okuma için, akışın sonuna kadar bir bayt dizisine kadar JSON yükünü okuyabilir ve bunu okuyucuya geçirebilirsiniz.For synchronous reading, you could read the JSON payload until the end of the stream into a byte array and pass that into the reader. Dizeden okumak için (UTF-16 olarak kodlanır), çağırın UTF8 .GetBytesFor reading from a string (which is encoded as UTF-16), call UTF8.GetBytes İlk olarak dizeyi bir UTF-8 kodlu bayt dizisine dönüştürme.to first transcode the string to a UTF-8 encoded byte array. Ardından bunu öğesine geçirin Utf8JsonReader .Then pass that to the Utf8JsonReader.

Utf8JsonReaderGIRIŞIN JSON metni olduğunu düşündüğü IÇIN UTF-8 bayt sırası işareti (BOM) GEÇERSIZ JSON olarak kabul edilir.Since the Utf8JsonReader considers the input to be JSON text, a UTF-8 byte order mark (BOM) is considered invalid JSON. Çağıranın verileri okuyucuya geçirmeden önce onu filtrelemeniz gerekir.The caller needs to filter that out before passing the data to the reader.

Kod örnekleri için bkz. Use Utf8JsonReader.For code examples, see Use Utf8JsonReader.

Çok kesimli ReadOnlySequence ile okuRead with multi-segment ReadOnlySequence

JSON girdisi Readonlyspan <byte> ise, ValueSpan okuma döngüsüne gittiğinizde her JSON öğesine okuyucudaki özellikten erişilebilir.If your JSON input is a ReadOnlySpan<byte>, each JSON element can be accessed from the ValueSpan property on the reader as you go through the read loop. Ancak, giriş, Readonlysequence <byte> ise (bir öğesinden okunması sonucu PipeReader ), bazı JSON öğeleri nesnenin birden fazla segmentine Straddle ReadOnlySequence<byte> .However, if your input is a ReadOnlySequence<byte> (which is the result of reading from a PipeReader), some JSON elements might straddle multiple segments of the ReadOnlySequence<byte> object. Bu öğelere ValueSpan , bir ardışık bellek bloğunun içinden erişilemez.These elements would not be accessible from ValueSpan in a contiguous memory block. Bunun yerine, giriş olarak çok bölgeli her seferinde, ReadOnlySequence<byte> HasValueSequence geçerli JSON öğesine nasıl erişebileceğinizi anlamak için okuyucudaki özelliği yoklayın.Instead, whenever you have a multi-segment ReadOnlySequence<byte> as input, poll the HasValueSequence property on the reader to figure out how to access the current JSON element. Önerilen bir model aşağıda verilmiştir:Here's a recommended pattern:

while (reader.Read())
{
    switch (reader.TokenType)
    {
        // ...
        ReadOnlySpan<byte> jsonElement = reader.HasValueSequence ?
            reader.ValueSequence.ToArray() :
            reader.ValueSpan;
        // ...
    }
}

Özellik adı aramaları için ValueTextEquals kullanınUse ValueTextEquals for property name lookups

ValueSpanÖzellik adı aramalarını çağırarak bayt başına karşılaştırmalar yapmak için kullanmayın SequenceEqual .Don't use ValueSpan to do byte-by-byte comparisons by calling SequenceEqual for property name lookups. ValueTextEqualsBunun yerine çağırın, çünkü bu yöntem JSON 'da kaçan tüm karakterleri kaldırır.Call ValueTextEquals instead, because that method unescapes any characters that are escaped in the JSON. "Ad" adlı bir özelliğin nasıl aranacağını gösteren bir örnek aşağıda verilmiştir:Here's an example that shows how to search for a property that is named "name":

private static readonly byte[] s_nameUtf8 = Encoding.UTF8.GetBytes("name");
while (reader.Read())
{
    JsonTokenType tokenType = reader.TokenType;

    switch (tokenType)
    {
        case JsonTokenType.StartObject:
            total++;
            break;
        case JsonTokenType.PropertyName:
            if (reader.ValueTextEquals(s_nameUtf8))
            {
                count++;
            }
            break;
    }

Null değerleri null yapılabilir değer türlerine okuRead null values into nullable value types

Newtonsoft.Jsondöndüren API 'Ler sağlar; örneğin Nullable<T> ReadAsBoolean , Null TokenType bir döndürür bool? .Newtonsoft.Json provides APIs that return Nullable<T>, such as ReadAsBoolean, which handles a Null TokenType for you by returning a bool?. Yerleşik System.Text.Json API 'ler yalnızca null yapılamayan değer türleri döndürüyor.The built-in System.Text.Json APIs return only non-nullable value types. Örneğin, Utf8JsonReader.GetBoolean bir döndürür bool .For example, Utf8JsonReader.GetBoolean returns a bool. JSON içinde bulursa bir özel durum oluşturur Null .It throws an exception if it finds Null in the JSON. Aşağıdaki örneklerde, bir tane null yapılabilir değer türü döndürerek ve bir tane varsayılan değeri döndürerek, null değerlerini işlemek için iki yol gösterilmektedir:The following examples show two ways to handle nulls, one by returning a nullable value type and one by returning the default value:

public bool? ReadAsNullableBoolean()
{
    _reader.Read();
    if (_reader.TokenType == JsonTokenType.Null)
    {
        return null;
    }
    if (_reader.TokenType != JsonTokenType.True && _reader.TokenType != JsonTokenType.False)
    {
        throw new JsonException();
    }
    return _reader.GetBoolean();
}
public bool ReadAsBoolean(bool defaultValue)
{
    _reader.Read();
    if (_reader.TokenType == JsonTokenType.Null)
    {
        return defaultValue;
    }
    if (_reader.TokenType != JsonTokenType.True && _reader.TokenType != JsonTokenType.False)
    {
        throw new JsonException();
    }
    return _reader.GetBoolean();
}

Çoklu hedeflemeMulti-targeting

Newtonsoft.JsonBelirli hedef çerçeveler için kullanmaya devam etmeniz gerekiyorsa, çoklu hedefleyebilir ve iki uygulamanız vardır.If you need to continue to use Newtonsoft.Json for certain target frameworks, you can multi-target and have two implementations. Ancak, bu önemsiz değildir ve bazı #ifdefs ve kaynak yinelemesi gerektirir.However, this is not trivial and would require some #ifdefs and source duplication. Mümkün olduğunca çok kodu paylaşmanın bir yolu, ref struct ve etrafında bir sarmalayıcı oluşturmaktır Utf8JsonReader Newtonsoft.Json JsonTextReader .One way to share as much code as possible is to create a ref struct wrapper around Utf8JsonReader and Newtonsoft.Json JsonTextReader. Bu sarmalayıcı, davranış farklarını yalıtma sırasında genel yüzey alanını birleştirecektir.This wrapper would unify the public surface area while isolating the behavioral differences. Bu, değişiklikleri öncelikle tür oluşturma ile birlikte ayırmanızı sağlar ve yeni türü başvuruya göre geçirerek.This lets you isolate the changes mainly to the construction of the type, along with passing the new type around by reference. Bu, Microsoft. Extensions. DependencyModel kitaplığı 'nın izlediği düzendir:This is the pattern that the Microsoft.Extensions.DependencyModel library follows:

Utf8JsonWriter, JsonTextWriter ile karşılaştırılırUtf8JsonWriter compared to JsonTextWriter

System.Text.Json.Utf8JsonWriter, ve gibi ortak .NET türlerinden UTF-8 kodlu JSON metni yazmanın yüksek performanslı bir yoludur String Int32 DateTime .System.Text.Json.Utf8JsonWriter is a high-performance way to write UTF-8 encoded JSON text from common .NET types like String, Int32, and DateTime. Yazıcı, özel serileştiriciler oluşturmak için kullanılabilen alt düzey bir türdür.The writer is a low-level type that can be used to build custom serializers.

Aşağıdaki bölümlerde, kullanımı için önerilen programlama düzenleri açıklanmaktadır Utf8JsonWriter .The following sections explain recommended programming patterns for using Utf8JsonWriter.

UTF-8 metniyle yazmaWrite with UTF-8 text

Kullanırken en iyi performansı elde etmek için Utf8JsonWriter , WRITE JSON YÜKLERINI UTF-16 dizeleri yerıne UTF-8 ile kodlanmış olarak yazın.To achieve the best possible performance while using the Utf8JsonWriter, write JSON payloads already encoded as UTF-8 text rather than as UTF-16 strings. JsonEncodedTextBilinen dize özellik adlarını ve değerlerini sıra olarak önbelleğe almak ve önceden kodlamak için kullanın ve UTF-16 dize sabit değerleri kullanmak yerine yazıcıya geçirin.Use JsonEncodedText to cache and pre-encode known string property names and values as statics, and pass those to the writer, rather than using UTF-16 string literals. Bu, önbelleğe alma ve UTF-8 bayt dizilerini kullanmayla daha hızlıdır.This is faster than caching and using UTF-8 byte arrays.

Özel kaçış yapmanız gerekiyorsa bu yaklaşım da geçerlidir.This approach also works if you need to do custom escaping. System.Text.Jsonbir dize yazarken kaçış özelliğini devre dışı bırakmanızı sağlar.System.Text.Json doesn't let you disable escaping while writing a string. Bununla birlikte, yazıcıya kendi özel JavaScriptEncoder bir seçenek olarak geçirebilirsiniz ya da JsonEncodedText kaçış yapmak için kendi uygulamanızı kullanarak kendi JavascriptEncoder öğesini oluşturabilir ve sonra JsonEncodedText dize yerine yazın.However, you could pass in your own custom JavaScriptEncoder as an option to the writer, or create your own JsonEncodedText that uses your JavascriptEncoder to do the escaping, and then write the JsonEncodedText instead of the string. Daha fazla bilgi için bkz. karakter kodlamasını özelleştirme.For more information, see Customize character encoding.

Ham değerleri yazWrite raw values

Newtonsoft.Json WriteRawValue Yöntemi, bir değerin beklenildiği ham JSON yazar.The Newtonsoft.Json WriteRawValue method writes raw JSON where a value is expected. System.Text.Jsondoğrudan eşdeğeri yoktur, ancak şu şekilde yalnızca geçerli JSON yazılmasını sağlayan bir geçici çözüm verilmiştir:System.Text.Json has no direct equivalent, but here's a workaround that ensures only valid JSON is written:

using JsonDocument doc = JsonDocument.Parse(string);
doc.WriteTo(writer);

Karakter kaçış 'yi özelleştirmeCustomize character escaping

Stringescapehandling AYARı, JsonTextWriter ASCII olmayan tüm karakterleri veya HTML karakterlerinin kaçış seçeneklerini sunar.The StringEscapeHandling setting of JsonTextWriter offers options to escape all non-ASCII characters or HTML characters. Varsayılan olarak, Utf8JsonWriter ASCII olmayan ve HTML karakterlerinin hepsini çıkar.By default, Utf8JsonWriter escapes all non-ASCII and HTML characters. Bu kaçış, derinlemesine savunma güvenlik nedenleriyle yapılır.This escaping is done for defense-in-depth security reasons. Farklı bir kaçış ilkesi belirtmek için, oluşturun JavaScriptEncoder ve ayarlayın JsonWriterOptions.Encoder .To specify a different escaping policy, create a JavaScriptEncoder and set JsonWriterOptions.Encoder. Daha fazla bilgi için bkz. karakter kodlamasını özelleştirme.For more information, see Customize character encoding.

JSON biçimini ÖzelleştirCustomize JSON format

JsonTextWritereşdeğeri olmayan, için aşağıdaki ayarları içerir Utf8JsonWriter :JsonTextWriter includes the following settings, for which Utf8JsonWriter has no equivalent:

  • Girintileme -girintilemek için kaç karakter kullanılacağını belirtir.Indentation - Specifies how many characters to indent. Utf8JsonWriterher zaman 2 karakterlik girintileme yapar.Utf8JsonWriter always does 2-character indentation.
  • Inztchar -girintileme için kullanılacak karakteri belirtir.IndentChar - Specifies the character to use for indentation. Utf8JsonWriterher zaman boşluk kullanır.Utf8JsonWriter always uses whitespace.
  • QuoteChar -dize değerlerini çevrelemek için kullanılacak karakteri belirtir.QuoteChar - Specifies the character to use to surround string values. Utf8JsonWriterher zaman çift tırnak kullanır.Utf8JsonWriter always uses double quotes.
  • QUOTENAME -özellik adlarının tırnak işaretleriyle saranıp çevrelenmeyeceğini belirtir.QuoteName - Specifies whether or not to surround property names with quotes. Utf8JsonWriterher zaman tırnak işaretleriyle çevreler.Utf8JsonWriter always surrounds them with quotes.

Tarafından üretilen JSON 'yi bu şekillerde özelleştirmenizi sağlayan geçici çözümler yoktur Utf8JsonWriter .There are no workarounds that would let you customize the JSON produced by Utf8JsonWriter in these ways.

Null değerleri yazWrite null values

Kullanarak null değerler yazmak için Utf8JsonWriter şunu çağırın:To write null values by using Utf8JsonWriter, call:

  • WriteNulldeğer olarak null ile bir anahtar-değer çifti yazmak.WriteNull to write a key-value pair with null as the value.
  • WriteNullValueJSON dizisinin bir öğesi olarak null yazmak için.WriteNullValue to write null as an element of a JSON array.

Dize özelliği için, dize null ise ve WriteString WriteStringValue WriteNull ile eşdeğerdir WriteNullValue .For a string property, if the string is null, WriteString and WriteStringValue are equivalent to WriteNull and WriteNullValue.

TimeSpan, Uri veya Char değerlerini yazWrite Timespan, Uri, or char values

JsonTextWriter``WriteValue TimeSpan, Urive char değerleri için yöntemler sağlar.JsonTextWriter provides WriteValue methods for TimeSpan, Uri, and char values. Utf8JsonWritereşdeğer yöntemlere sahip değildir.Utf8JsonWriter doesn't have equivalent methods. Bunun yerine, bu değerleri dizeler olarak biçimlendirin ( ToString() Örneğin, çağırarak) ve çağırın WriteStringValue .Instead, format these values as strings (by calling ToString(), for example) and call WriteStringValue.

Çoklu hedeflemeMulti-targeting

Newtonsoft.JsonBelirli hedef çerçeveler için kullanmaya devam etmeniz gerekiyorsa, çoklu hedefleyebilir ve iki uygulamanız vardır.If you need to continue to use Newtonsoft.Json for certain target frameworks, you can multi-target and have two implementations. Ancak, bu önemsiz değildir ve bazı #ifdefs ve kaynak yinelemesi gerektirir.However, this is not trivial and would require some #ifdefs and source duplication. Mümkün olduğunca çok kodu paylaşmanın bir yolu, ve etrafında bir sarmalayıcı oluşturmaktır Utf8JsonWriter Newtonsoft JsonTextWriter .One way to share as much code as possible is to create a wrapper around Utf8JsonWriter and Newtonsoft JsonTextWriter. Bu sarmalayıcı, davranış farklarını yalıtma sırasında genel yüzey alanını birleştirecektir.This wrapper would unify the public surface area while isolating the behavioral differences. Bu, değişiklikleri genellikle türün yapılacağı şekilde yalıtmanızı sağlar.This lets you isolate the changes mainly to the construction of the type. Microsoft. Extensions. DependencyModel kitaplığı aşağıdaki gibidir:Microsoft.Extensions.DependencyModel library follows:

Ek kaynaklarAdditional resources