.NET içinde JSON ve seri hale getirme (sıralama ve kaldırma)How to serialize and deserialize (marshal and unmarshal) JSON in .NET

Bu makalede, System.Text.Json JavaScript nesne gösterimi (JSON) ve öğesinden seri hale getirmek ve seri durumdan çıkarmak için ad alanı kullanımı gösterilmektedir.This article shows how to use the System.Text.Json namespace to serialize and deserialize to and from JavaScript Object Notation (JSON). İçinden mevcut kodu aktarıyorsanız Newtonsoft.Json , bkz. nasıl geçiş System.Text.Json yapılacağı .If you're porting existing code from Newtonsoft.Json, see How to migrate to System.Text.Json.

Yönergeler ve örnek kod, kitaplığı, ASP.NET Coregibi bir çerçeve aracılığıyla değil, doğrudan kullanır.The directions and sample code use the library directly, not through a framework such as ASP.NET Core.

Serileştirme örnek kodunun çoğu, JsonSerializerOptions.WriteIndented true JSON (girintileme ve insanlar okunabilirlik için boşluk) olarak ayarlanır.Most of the serialization sample code sets JsonSerializerOptions.WriteIndented to true to "pretty-print" the JSON (with indentation and whitespace for human readability). Üretim kullanımı için genellikle bu ayar için varsayılan değerini kabul etmiş olursunuz false .For production use, you would typically accept the default value of false for this setting.

Kod örnekleri, aşağıdaki sınıfa ve türevlerini ifade eder:The code examples refer to the following class and variants of it:

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

Ad alanlarıNamespaces

System.Text.JsonAd alanı tüm giriş noktalarını ve ana türleri içerir.The System.Text.Json namespace contains all the entry points and the main types. System.Text.Json.SerializationAd alanı, serileştirme ve seri durumdan çıkarma ile ilgili gelişmiş senaryolar ve özelleştirme için öznitelikler ve API 'leri içerir.The System.Text.Json.Serialization namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. Bu makalede gösterilen kod örnekleri, using Bu ad alanlarından biri veya her ikisi için yönergeler gerektirir:The code examples shown in this article require using directives for one or both of these namespaces:

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

System.Runtime.SerializationAd alanındaki öznitelikler Şu anda sürümünde desteklenmemektedir System.Text.Json .Attributes from the System.Runtime.Serialization namespace aren't currently supported in System.Text.Json.

.NET nesnelerini JSON 'a yazma (serileştirme)How to write .NET objects to JSON (serialize)

JSON 'yi bir dizeye veya bir dosyaya yazmak için JsonSerializer.Serialize yöntemini çağırın.To write JSON to a string or to a file, call the JsonSerializer.Serialize method.

Aşağıdaki örnek bir dize olarak JSON oluşturur:The following example creates JSON as a string:

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

Aşağıdaki örnek, bir JSON dosyası oluşturmak için zaman uyumlu kod kullanır:The following example uses synchronous code to create a JSON file:

jsonString = JsonSerializer.Serialize(weatherForecast);
File.WriteAllText(fileName, jsonString);

Aşağıdaki örnek, bir JSON dosyası oluşturmak için zaman uyumsuz kod kullanır:The following example uses asynchronous code to create a JSON file:

using (FileStream fs = File.Create(fileName))
{
    await JsonSerializer.SerializeAsync(fs, weatherForecast);
}

Önceki örneklerde, serileştirilmekte olan türün tür çıkarımı kullanılır.The preceding examples use type inference for the type being serialized. Öğesinin aşırı yüklemesi Serialize() genel bir tür parametresi alır:An overload of Serialize() takes a generic type parameter:

jsonString = JsonSerializer.Serialize<WeatherForecastWithPOCOs>(weatherForecast);

Serileştirme örneğiSerialization example

Aşağıda, koleksiyonları ve iç içe yerleştirilmiş bir sınıfı içeren örnek bir sınıf verilmiştir:Here's an example class that contains collections and a nested class:

public class WeatherForecastWithPOCOs
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public string SummaryField;
    public IList<DateTimeOffset> DatesAvailable { get; set; }
    public Dictionary<string, HighLowTemps> TemperatureRanges { get; set; }
    public string[] SummaryWords { get; set; }
}

public class HighLowTemps
{
    public int High { get; set; }
    public int Low { get; set; }
}

Önceki türün bir örneğinin serileştirilmesi için JSON çıktısı aşağıdaki örnekteki gibi görünür.The JSON output from serializing an instance of the preceding type looks like the following example. JSON çıktısı varsayılan olarak Mini olarak belirlenir:The JSON output is minified by default:

{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot","DatesAvailable":["2019-08-01T00:00:00-07:00","2019-08-02T00:00:00-07:00"],"TemperatureRanges":{"Cold":{"High":20,"Low":-10},"Hot":{"High":60,"Low":20}},"SummaryWords":["Cool","Windy","Humid"]}

Aşağıdaki örnek, biçimlendirilen aynı JSON 'ı gösterir (yani, boşluk ve girintileme ile düzgün şekilde yazdırılır):The following example shows the same JSON, formatted (that is, pretty-printed with whitespace and indentation):

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "DatesAvailable": [
    "2019-08-01T00:00:00-07:00",
    "2019-08-02T00:00:00-07:00"
  ],
  "TemperatureRanges": {
    "Cold": {
      "High": 20,
      "Low": -10
    },
    "Hot": {
      "High": 60,
      "Low": 20
    }
  },
  "SummaryWords": [
    "Cool",
    "Windy",
    "Humid"
  ]
}

UTF-8 ' e serileştirmeSerialize to UTF-8

UTF-8 ' e seri hale getirmek için JsonSerializer.SerializeToUtf8Bytes yöntemini çağırın:To serialize to UTF-8, call the JsonSerializer.SerializeToUtf8Bytes method:

byte[] jsonUtf8Bytes;
var options = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast, options);

' İ Serialize alan bir aşırı yükleme Utf8JsonWriter de mevcuttur.A Serialize overload that takes a Utf8JsonWriter is also available.

UTF-8 ' i seri hale getirmek, dize tabanlı yöntemler kullanmaktan daha hızlı% 5-10 daha hızlıdır.Serializing to UTF-8 is about 5-10% faster than using the string-based methods. Aradaki fark, baytların (UTF-8 olarak) dizelere dönüştürülmesi gerekmez (UTF-16).The difference is because the bytes (as UTF-8) don't need to be converted to strings (UTF-16).

Serileştirme davranışıSerialization behavior

Desteklenen türler şunlardır:Supported types include:

  • Sayısal türler, dizeler ve Boole gibi JavaScript temel elemanlarına eşleyen .NET temel türleri..NET primitives that map to JavaScript primitives, such as numeric types, strings, and Boolean.
  • Kullanıcı tanımlı düz eskı clr nesneleri (POCOs).User-defined Plain Old CLR Objects (POCOs).
  • Tek boyutlu ve pürüzlü Diziler ( ArrayName[][] ).One-dimensional and jagged arrays (ArrayName[][]).
  • Dictionary<string,TValue> Burada TValue , object JsonElement veya bir poco.Dictionary<string,TValue> where TValue is object, JsonElement, or a POCO.
  • Aşağıdaki ad alanlarından Koleksiyonlar.Collections from the following namespaces.

Ek türleri işlemek veya yerleşik dönüştürücüler tarafından desteklenmeyen işlevler sağlamak için özel dönüştürücüler uygulayabilirsiniz .You can implement custom converters to handle additional types or to provide functionality that isn't supported by the built-in converters.

JSON 'ı .NET Objects 'e okuma (serisini kaldırma)How to read JSON into .NET objects (deserialize)

Bir dizeden veya dosyadan seri durumdan çıkarmak için JsonSerializer.Deserialize yöntemini çağırın.To deserialize from a string or a file, call the JsonSerializer.Deserialize method.

Aşağıdaki örnek, bir dizeden JSON okur ve WeatherForecast daha önce serileştirme örneğiiçin gösterilen sınıfının bir örneğini oluşturur:The following example reads JSON from a string and creates an instance of the WeatherForecast class shown earlier for the serialization example:

weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithPOCOs>(jsonString);

Zaman uyumlu kod kullanarak bir dosyadan seri durumdan çıkarmak için, aşağıdaki örnekte gösterildiği gibi dosyayı bir dizeye okuyun:To deserialize from a file by using synchronous code, read the file into a string, as shown in the following example:

jsonString = File.ReadAllText(fileName);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString);

Zaman uyumsuz kod kullanarak bir dosyadan seri durumdan çıkarmak için yöntemini çağırın DeserializeAsync :To deserialize from a file by using asynchronous code, call the DeserializeAsync method:

using (FileStream fs = File.OpenRead(fileName))
{
    weatherForecast = await JsonSerializer.DeserializeAsync<WeatherForecast>(fs);
}

UTF-8 ' den serisini kaldırmaDeserialize from UTF-8

UTF-8 ' den seri durumdan çıkarmak için, JsonSerializer.Deserialize Utf8JsonReader ReadOnlySpan<byte> Aşağıdaki örneklerde gösterildiği gibi bir veya içeren bir aşırı yükleme çağırın.To deserialize from UTF-8, call a JsonSerializer.Deserialize overload that takes a Utf8JsonReader or a ReadOnlySpan<byte>, as shown in the following examples. Örnekler, JSON 'ın jsonUtf8Bytes adlı bir bayt dizisinde olduğunu varsayar.The examples assume the JSON is in a byte array named jsonUtf8Bytes.

var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan);
var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader);

Seri durumdan çıkarma davranışıDeserialization behavior

Yerleşik dönüştürücüler tarafından desteklenmeyen işlevselliği sağlamak için özel dönüştürücüler uygulayabilirsiniz .You can implement custom converters to provide functionality that isn't supported by the built-in converters.

Biçimlendirilen JSON 'a serileştirmeSerialize to formatted JSON

JSON çıkışını gerçekten yazdırmak için şu JsonSerializerOptions.WriteIndented şekilde ayarlayın true :To pretty-print the JSON output, set JsonSerializerOptions.WriteIndented to true:

var options = new JsonSerializerOptions
{
    WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Aşağıda, seri hale getirilebilir ve düzgün şekilde yazdırılan JSON çıkışının örnek bir türü verilmiştir:Here's an example type to be serialized and pretty-printed JSON output:

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

JSON adlarını ve değerlerini özelleştirmeCustomize JSON names and values

Varsayılan olarak, özellik adları ve sözlük anahtarları, büyük/küçük harf gibi JSON çıktısında değiştirilmez.By default, property names and dictionary keys are unchanged in the JSON output, including case. Sabit listesi değerleri sayı olarak temsil edilir.Enum values are represented as numbers. Bu bölümde nasıl yapılacağı açıklanmaktadır:This section explains how to:

JSON özellik adlarını ve değerlerini özel olarak işleme gerektiren diğer senaryolar için özel dönüştürücüler uygulayabilirsiniz.For other scenarios that require special handling of JSON property names and values, you can implement custom converters.

Bireysel özellik adlarını özelleştirmeCustomize individual property names

Ayrı özelliklerin adını ayarlamak için [Jsonpropertyname] özniteliğini kullanın.To set the name of individual properties, use the [JsonPropertyName] attribute.

Serileştirme ve sonuç JSON için örnek bir tür aşağıda verilmiştir:Here's an example type to serialize and resulting JSON:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "Wind": 35
}

Bu öznitelik tarafından ayarlanan özellik adı:The property name set by this attribute:

  • Serileştirme ve seri durumundan çıkarma için her iki yönde de geçerlidir.Applies in both directions, for serialization and deserialization.
  • Özellik adlandırma ilkelerine göre önceliklidir.Takes precedence over property naming policies.

Tüm JSON Özellik adları için ortası Case kullanınUse camel case for all JSON property names

Tüm JSON Özellik adları için ortası durumunu kullanmak için, JsonSerializerOptions.PropertyNamingPolicy JsonNamingPolicy.CamelCase Aşağıdaki örnekte gösterildiği gibi olarak ayarlanır:To use camel case for all JSON property names, set JsonSerializerOptions.PropertyNamingPolicy to JsonNamingPolicy.CamelCase, as shown in the following example:

var serializeOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);

Seri hale getirmek ve JSON çıktısı için örnek bir sınıf aşağıda verilmiştir:Here's an example class to serialize and JSON output:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
  "Wind": 35
}

Ortası durum özelliği adlandırma ilkesi:The camel case property naming policy:

  • Serileştirme ve seri durumdan çıkarma için geçerlidir.Applies to serialization and deserialization.
  • Öznitelikleri tarafından geçersiz kılınır [JsonPropertyName] .Is overridden by [JsonPropertyName] attributes. Bu nedenle, örnekteki JSON Özellik adının Wind ortası durum olmaması neden olur.This is why the JSON property name Wind in the example is not camel case.

Özel bir JSON Özellik adlandırma ilkesi kullanmaUse a custom JSON property naming policy

Özel bir JSON Özellik adlandırma ilkesi kullanmak için, JsonNamingPolicy ConvertName Aşağıdaki örnekte gösterildiği gibi yönteminden türeten bir sınıf oluşturun ve yöntemi geçersiz kılın:To use a custom JSON property naming policy, create a class that derives from JsonNamingPolicy and override the ConvertName method, as shown in the following example:

using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class UpperCaseNamingPolicy : JsonNamingPolicy
    {
        public override string ConvertName(string name) =>
            name.ToUpper();
    }
}

Daha sonra JsonSerializerOptions.PropertyNamingPolicy özelliği, adlandırma ilkesi sınıfınızın bir örneğine ayarlayın:Then set the JsonSerializerOptions.PropertyNamingPolicy property to an instance of your naming policy class:

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = new UpperCaseNamingPolicy(),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Seri hale getirmek ve JSON çıktısı için örnek bir sınıf aşağıda verilmiştir:Here's an example class to serialize and JSON output:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "DATE": "2019-08-01T00:00:00-07:00",
  "TEMPERATURECELSIUS": 25,
  "SUMMARY": "Hot",
  "Wind": 35
}

JSON özelliği adlandırma ilkesi:The JSON property naming policy:

  • Serileştirme ve seri durumdan çıkarma için geçerlidir.Applies to serialization and deserialization.
  • Öznitelikleri tarafından geçersiz kılınır [JsonPropertyName] .Is overridden by [JsonPropertyName] attributes. Bu, örnekteki JSON Özellik adının Wind büyük harfle değil.This is why the JSON property name Wind in the example is not upper case.

Camel durum sözlüğü anahtarlarıCamel case dictionary keys

Seri hale getirilecek bir nesnenin özelliği tür ise Dictionary<string,TValue> , string anahtarlar ortası duruma dönüştürülebilir.If a property of an object to be serialized is of type Dictionary<string,TValue>, the string keys can be converted to camel case. Bunu yapmak için, DictionaryKeyPolicy JsonNamingPolicy.CamelCase Aşağıdaki örnekte gösterildiği gibi öğesini olarak ayarlayın:To do that, set DictionaryKeyPolicy to JsonNamingPolicy.CamelCase, as shown in the following example:

var options = new JsonSerializerOptions
{
    DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Anahtar-değer çiftlerine sahip adlı bir sözlük ile bir nesneyi serileştirmek TemperatureRanges "ColdMinTemp", 20 ve "HotMinTemp", 40 Aşağıdaki örnekte olduğu gibi JSON çıktısına neden olur:Serializing an object with a dictionary named TemperatureRanges that has key-value pairs "ColdMinTemp", 20 and "HotMinTemp", 40 would result in JSON output like the following example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "TemperatureRanges": {
    "coldMinTemp": 20,
    "hotMinTemp": 40
  }
}

Sözlük anahtarları için ortası örnek adlandırma ilkesi yalnızca serileştirme için geçerlidir.The camel case naming policy for dictionary keys applies to serialization only. Bir sözlüğün serisini kaldırırsanız, için belirtseniz bile anahtarlar JSON dosyasıyla eşleşir JsonNamingPolicy.CamelCase DictionaryKeyPolicy .If you deserialize a dictionary, the keys will match the JSON file even if you specify JsonNamingPolicy.CamelCase for the DictionaryKeyPolicy.

Dizeler dize olarak numaralandırmalarEnums as strings

Varsayılan olarak, numaralandırmalar sayı olarak serileştirilir.By default, enums are serialized as numbers. Sabit listesi adlarını dizeler olarak seri hale getirmek için öğesini kullanın JsonStringEnumConverter .To serialize enum names as strings, use the JsonStringEnumConverter.

Örneğin, bir sabit listesi olan aşağıdaki sınıfı seri hale getirmeniz gerektiğini varsayalım:For example, suppose you need to serialize the following class that has an enum:

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

public enum Summary
{
    Cold, Cool, Warm, Hot
}

Özet ise Hot , varsayılan olarak SERILEŞTIRILMIŞ JSON sayısal değer 3 ' ü içerir:If the Summary is Hot, by default the serialized JSON has the numeric value 3:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": 3
}

Aşağıdaki örnek kod, sayısal değerler yerine enum adlarını seri hale getirir ve adları ortası örneğine dönüştürür:The following sample code serializes the enum names instead of the numeric values, and converts the names to camel case:

options = new JsonSerializerOptions();
options.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));
options.WriteIndented = true;
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Elde edilen JSON aşağıdaki örneğe benzer şekilde görünür:The resulting JSON looks like the following example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "hot"
}

Aşağıdaki örnekte gösterildiği gibi, sabit listesi dize adları da seri durumdan çıkarılmış olabilir:Enum string names can be deserialized as well, as shown in the following example:

options = new JsonSerializerOptions();
options.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithEnum>(jsonString, options);

Özellikleri serileştirme dışında tutExclude properties from serialization

Varsayılan olarak, tüm ortak özellikler serileştirilir.By default, all public properties are serialized. Bir kısmının JSON çıktısında görünmesini istemiyorsanız, birkaç seçeneğiniz vardır.If you don't want some of them to appear in the JSON output, you have several options. Bu bölümde nasıl hariç tutulacak açıklanmaktadır:This section explains how to exclude:

Bireysel özellikleri DışlaExclude individual properties

Ayrı özellikleri yoksaymak için [Jsonıgnore] özniteliğini kullanın.To ignore individual properties, use the [JsonIgnore] attribute.

Seri hale getirmek ve JSON çıktısı için örnek bir tür aşağıda verilmiştir:Here's an example type to serialize and JSON output:

public class WeatherForecastWithIgnoreAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    [JsonIgnore]
    public string Summary { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
}

Tüm salt okuma özelliklerini DışlaExclude all read-only properties

Bir özellik, genel bir alıcı içeriyorsa ancak genel bir ayarlayıcı içermiyorsa salt okunurdur.A property is read-only if it contains a public getter but not a public setter. Tüm salt okunurdur özelliklerini hariç tutmak için, JsonSerializerOptions.IgnoreReadOnlyProperties true Aşağıdaki örnekte gösterildiği gibi öğesini olarak ayarlayın:To exclude all read-only properties, set the JsonSerializerOptions.IgnoreReadOnlyProperties to true, as shown in the following example:

var options = new JsonSerializerOptions
{
    IgnoreReadOnlyProperties = true,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Seri hale getirmek ve JSON çıktısı için örnek bir tür aşağıda verilmiştir:Here's an example type to serialize and JSON output:

public class WeatherForecastWithROProperty
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public int WindSpeedReadOnly { get; private set; } = 35;
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
}

Bu seçenek yalnızca serileştirme için geçerlidir.This option applies only to serialization. Seri durumdan çıkarma sırasında salt okuma özellikleri varsayılan olarak yoksayılır.During deserialization, read-only properties are ignored by default.

Tüm null değer özelliklerini DışlaExclude all null value properties

Tüm null değer özelliklerini dışlamak için, IgnoreNullValues true Aşağıdaki örnekte gösterildiği gibi özelliğini olarak ayarlayın:To exclude all null value properties, set the IgnoreNullValues property to true, as shown in the following example:

var options = new JsonSerializerOptions
{
    IgnoreNullValues = true,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Seri hale getirmek ve JSON çıktısı için örnek bir nesne aşağıda verilmiştir:Here's an example object to serialize and JSON output:

ÖzellikProperty DeğerValue
TarihDate 8/1/2019 12:00:00-07:008/1/2019 12:00:00 AM -07:00
TemperatureCelsiusTemperatureCelsius 2525
ÖzetSummary nullnull
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25
}

Bu ayar serileştirme ve seri durumdan çıkarma için geçerlidir.This setting applies to serialization and deserialization. Seri durumdan çıkarma üzerindeki etkisi hakkında daha fazla bilgi için bkz. serisi kaldırılırken null değeri yoksay.For information about its effect on deserialization, see Ignore null when deserializing.

Karakter kodlamasını özelleştirmeCustomize character encoding

Varsayılan olarak, seri hale getirici ASCII olmayan tüm karakterleri çıkar.By default, the serializer escapes all non-ASCII characters. Diğer bir deyişle, bu, \uxxxx karakterin Unicode kodunun bulunduğu konum ile değiştirilir xxxx .That is, it replaces them with \uxxxx where xxxx is the Unicode code of the character. Örneğin, Summary özelliği Kiril жарко olarak ayarlandıysa, WeatherForecast nesne şu örnekte gösterildiği gibi serileştirilir:For example, if the Summary property is set to Cyrillic жарко, the WeatherForecast object is serialized as shown in this example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "\u0436\u0430\u0440\u043A\u043E"
}

Dil karakter kümelerini serileştirmeSerialize language character sets

Bir veya daha fazla dilin karakter kümesini kaçış olmadan seri hale getirmek için, aşağıdaki örnekte gösterildiği gibi bir örneği oluştururken Unicode aralığı belirtin System.Text.Encodings.Web.JavaScriptEncoder :To serialize the character set(s) of one or more languages without escaping, specify Unicode range(s) when creating an instance of System.Text.Encodings.Web.JavaScriptEncoder, as shown in the following example:

using System;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;
options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.Create(UnicodeRanges.BasicLatin, UnicodeRanges.Cyrillic),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Bu kod, Kiril veya Yunan karakterlerinden kaçış yapmaz.This code doesn't escape Cyrillic or Greek characters. SummaryÖzellik Kiril жарко olarak ayarlandıysa, WeatherForecast nesne şu örnekte gösterildiği gibi serileştirilir:If the Summary property is set to Cyrillic жарко, the WeatherForecast object is serialized as shown in this example:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "жарко"
}

Tüm dil kümelerini kaçış olmadan seri hale getirmek için kullanın UnicodeRanges.All .To serialize all language sets without escaping, use UnicodeRanges.All.

Belirli karakterleri serileştirmeSerialize specific characters

Diğer bir seçenek de, kaçırılmadan, izin vermek istediğiniz tek tek karakterleri belirtmektir.An alternative is to specify individual characters that you want to allow through without being escaped. Aşağıdaki örnek, жарко 'in yalnızca ilk iki karakterini seri hale getirir:The following example serializes only the first two characters of жарко:

using System;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;
var encoderSettings = new TextEncoderSettings();
encoderSettings.AllowCharacters('\u0436', '\u0430');
encoderSettings.AllowRange(UnicodeRanges.BasicLatin);
options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.Create(encoderSettings),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Yukarıdaki kod tarafından üretilen JSON örneği aşağıda verilmiştir:Here's an example of JSON produced by the preceding code:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "жа\u0440\u043A\u043E"
}

Tüm karakterleri seri hale getirmeSerialize all characters

JavaScriptEncoder.UnsafeRelaxedJsonEscapingAşağıdaki örnekte gösterildiği gibi, kullanarak kaçı en aza indirin:To minimize escaping you can use JavaScriptEncoder.UnsafeRelaxedJsonEscaping, as shown in the following example:

using System;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Unicode;
options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Dikkat

Varsayılan kodlayıcıyla karşılaştırıldığında kodlayıcı, UnsafeRelaxedJsonEscaping karakterlerin kaçışsız geçmesine izin verme konusunda daha fazla izne sahiptir:Compared to the default encoder, the UnsafeRelaxedJsonEscaping encoder is more permissive about allowing characters to pass through unescaped:

  • ,, Ve gibi HTML 'ye duyarlı karakterleri atmaz < > & ' .It doesn't escape HTML-sensitive characters such as <, >, &, and '.
  • Bu, XSS veya bilgi açıklama saldırılarına karşı ek derinlemesine savunma korumaları sunmaz, örneğin, karakterkümesinde istemci ve sunucu disagreeing neden olabilir.It doesn't offer any additional defense-in-depth protections against XSS or information disclosure attacks, such as those which might result from the client and server disagreeing on the charset.

Güvenli olmayan kodlayıcıyı yalnızca istemcinin, elde edilen yükü UTF-8 ile kodlanmış JSON olarak yorumladığı bilindiğinde kullanın.Use the unsafe encoder only when it's known that the client will be interpreting the resulting payload as UTF-8 encoded JSON. Örneğin, sunucu yanıt üst bilgisini gönderiyorsa onu kullanabilirsiniz Content-Type: application/json; charset=utf-8 .For example, you can use it if the server is sending the response header Content-Type: application/json; charset=utf-8. Ham UnsafeRelaxedJsonEscaping çıkışın BIR HTML sayfasına veya bir öğeye yayılmasın <script> .Never allow the raw UnsafeRelaxedJsonEscaping output to be emitted into an HTML page or a <script> element.

Türetilmiş sınıfların serileştirme özellikleriSerialize properties of derived classes

Çok biçimli bir tür hiyerarşisinin serileştirilmesi desteklenmiyor.Serialization of a polymorphic type hierarchy is not supported. Örneğin, bir özellik bir arabirim ya da soyut sınıf olarak tanımlanmışsa, çalışma zamanı türü ek özelliklere sahip olsa bile yalnızca arabirim veya soyut sınıf üzerinde tanımlanan özellikler serileştirilir.For example, if a property is defined as an interface or an abstract class, only the properties defined on the interface or abstract class are serialized, even if the runtime type has additional properties. Bu davranışın istisnaları, bu bölümde açıklanmaktadır.The exceptions to this behavior are explained in this section.

Örneğin, bir WeatherForecast sınıfınız ve türetilmiş bir sınıfınız olduğunu varsayalım WeatherForecastDerived :For example, suppose you have a WeatherForecast class and a derived class WeatherForecastDerived:

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

Ve derleme zamanında yöntemin tür bağımsız değişkeninin Serialize Şu olduğunu varsayalım WeatherForecast :And suppose the type argument of the Serialize method at compile time is WeatherForecast:

var options = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize<WeatherForecast>(weatherForecast, options);

Bu senaryoda, WindSpeed weatherForecast nesne gerçekten bir nesne olsa bile Özellik serileştirilmez WeatherForecastDerived .In this scenario, the WindSpeed property is not serialized even if the weatherForecast object is actually a WeatherForecastDerived object. Yalnızca temel sınıf özellikleri serileştirilir:Only the base class properties are serialized:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Bu davranış, türetilmiş çalışma zamanında oluşturulan bir türdeki verilerin yanlışlıkla açıklanmasını önlemeye yardımcı olmak için tasarlanmıştır.This behavior is intended to help prevent accidental exposure of data in a derived runtime-created type.

Yukarıdaki örnekteki türetilmiş türün özelliklerini seri hale getirmek için aşağıdaki yaklaşımlardan birini kullanın:To serialize the properties of the derived type in the preceding example, use one of the following approaches:

  • SerializeÇalışma zamanında türü belirtmenize olanak sağlayan aşırı yüklemesini çağırın:Call an overload of Serialize that lets you specify the type at run time:

    options = new JsonSerializerOptions
    {
        WriteIndented = true
    };
    jsonString = JsonSerializer.Serialize(weatherForecast, weatherForecast.GetType(), options);
    
  • Seri hale getirilecek nesneyi bildirin object .Declare the object to be serialized as object.

    options = new JsonSerializerOptions
    {
        WriteIndented = true
    };
    jsonString = JsonSerializer.Serialize<object>(weatherForecast, options);
    

Yukarıdaki örnek senaryoda, her iki yaklaşım WindSpeed ÖZELLIĞIN JSON çıktısına dahil olmasına neden olur:In the preceding example scenario, both approaches cause the WindSpeed property to be included in the JSON output:

{
  "WindSpeed": 35,
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Önemli

Bu yaklaşımlar yalnızca kök nesnenin seri hale getirilmesi için, bu kök nesnenin özellikleri için değil, polimorfik serileştirme sağlar.These approaches provide polymorphic serialization only for the root object to be serialized, not for properties of that root object.

Bunları tür olarak tanımlarsanız alt düzey nesneler için polimorfik serileştirme alabilirsiniz object .You can get polymorphic serialization for lower-level objects if you define them as type object. Örneğin, WeatherForecast sınıfınızın, tür olarak tanımlanabilen adında bir özelliği olduğunu varsayalım PreviousForecast WeatherForecast object :For example, suppose your WeatherForecast class has a property named PreviousForecast that can be defined as type WeatherForecast or object:

public class WeatherForecastWithPrevious
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public WeatherForecast PreviousForecast { get; set; }
}
public class WeatherForecastWithPreviousAsObject
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public object PreviousForecast { get; set; }
}

PreviousForecastÖzelliği bir örneği içeriyorsa WeatherForecastDerived :If the PreviousForecast property contains an instance of WeatherForecastDerived:

  • Serileştirmede JSON çıktısı WeatherForecastWithPrevious içermez WindSpeed .The JSON output from serializing WeatherForecastWithPrevious doesn't include WindSpeed.
  • Serileştirmede JSON çıktısı WeatherForecastWithPreviousAsObject dahildir WindSpeed .The JSON output from serializing WeatherForecastWithPreviousAsObject includes WindSpeed.

Seri hale getirmek için WeatherForecastWithPreviousAsObject , Serialize<object> ya da GetType kök nesnesi türetilmiş bir tür olabilecek bir nesne olmadığından çağırmak gerekmez.To serialize WeatherForecastWithPreviousAsObject, it isn't necessary to call Serialize<object> or GetType because the root object isn't the one that may be of a derived type. Aşağıdaki kod örneği, Serialize<object> veya çağırmaz GetType :The following code example doesn't call Serialize<object> or GetType:

options = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecastWithPreviousAsObject, options);

Yukarıdaki kod doğru şekilde serileştirir WeatherForecastWithPreviousAsObject :The preceding code correctly serializes WeatherForecastWithPreviousAsObject:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "PreviousForecast": {
    "WindSpeed": 35,
    "Date": "2019-08-01T00:00:00-07:00",
    "TemperatureCelsius": 25,
    "Summary": "Hot"
  }
}

Özellikleri, arabirimler ile birlikte tanımlamaya yönelik aynı yaklaşım object .The same approach of defining properties as object works with interfaces. Aşağıdaki arabirime ve uygulamaya sahip olduğunuzu ve uygulama örnekleri içeren özelliklerle bir sınıfı seri hale getirmek istediğinizi varsayalım:Suppose you have the following interface and implementation, and you want to serialize a class with properties that contain implementation instances:

using System;

namespace SystemTextJsonSamples
{
    public interface IForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string Summary { get; set; }
    }

    public class Forecast : IForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string Summary { get; set; }
        public int WindSpeed { get; set; }
    }

    public class Forecasts
    {
        public IForecast Monday { get; set; }
        public object Tuesday { get; set; }
    }
}

Bir örneğini serileştirçalıştığınızda Forecasts , yalnızca Tuesday WindSpeed özelliğini gösterir, çünkü Tuesday Şu şekilde tanımlanır object :When you serialize an instance of Forecasts, only Tuesday shows the WindSpeed property, because Tuesday is defined as object:

var forecasts = new Forecasts
{
    Monday = new Forecast
    {
        Date = DateTime.Parse("2020-01-06"),
        TemperatureCelsius = 10,
        Summary = "Cool",
        WindSpeed = 8
    },
    Tuesday = new Forecast
    {
        Date = DateTime.Parse("2020-01-07"),
        TemperatureCelsius = 11,
        Summary = "Rainy",
        WindSpeed = 10
    }
};

options = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(forecasts, options);

Aşağıdaki örnek, önceki koddan elde edilen JSON 'u göstermektedir:The following example shows the JSON that results from the preceding code:

{
  "Monday": {
    "Date": "2020-01-06T00:00:00-08:00",
    "TemperatureCelsius": 10,
    "Summary": "Cool"
  },
  "Tuesday": {
    "Date": "2020-01-07T00:00:00-08:00",
    "TemperatureCelsius": 11,
    "Summary": "Rainy",
    "WindSpeed": 10
  }
}

Polimorfik serileştirmehakkında daha fazla bilgi için ve serisini kaldırmahakkında bilgi için, bkz. ' den Newtonsoft.Json System.Text.Json ' ye geçiş .For more information about polymorphic serialization, and for information about deserialization, see How to migrate from Newtonsoft.Json to System.Text.Json.

Yorumlara ve sondaki virgülleri izin verAllow comments and trailing commas

Varsayılan olarak, JSON 'da yorumlara ve sondaki virgüllerin kullanımına izin verilmez.By default, comments and trailing commas are not allowed in JSON. JSON 'da açıklamalara izin vermek için JsonSerializerOptions.ReadCommentHandling özelliğini olarak ayarlayın JsonCommentHandling.Skip .To allow comments in the JSON, set the JsonSerializerOptions.ReadCommentHandling property to JsonCommentHandling.Skip. Ve sondaki virgüllerin kullanılmasına izin vermek için JsonSerializerOptions.AllowTrailingCommas özelliğini olarak ayarlayın true .And to allow trailing commas, set the JsonSerializerOptions.AllowTrailingCommas property to true. Aşağıdaki örnek, her ikisine de izin vermeyi göstermektedir:The following example shows how to allow both:

var options = new JsonSerializerOptions
{
    ReadCommentHandling = JsonCommentHandling.Skip,
    AllowTrailingCommas = true,
};
var weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString, options);

Yorumlar ve sondaki virgülden oluşan örnek JSON aşağıda verilmiştir:Here's example JSON with comments and a trailing comma:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25, // Fahrenheit 77
  "Summary": "Hot", /* Zharko */
}

Büyük/küçük harfe duyarsız Özellik eşleştirmeCase-insensitive property matching

Varsayılan olarak, seri durumdan çıkarma JSON ile hedef nesne özellikleri arasındaki büyük/küçük harfe duyarlı Özellik adı eşleşmelerini arar.By default, deserialization looks for case-sensitive property name matches between JSON and the target object properties. Bu davranışı değiştirmek için şu JsonSerializerOptions.PropertyNameCaseInsensitive şekilde ayarlayın true :To change that behavior, set JsonSerializerOptions.PropertyNameCaseInsensitive to true:

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
};
var weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString, options);

Aşağıda, ortası Case özellik adlarına sahip JSON örneği verilmiştir.Here's example JSON with camel case property names. Bu,, Pascal case özellik adlarına sahip olan aşağıdaki türde seri durumdan çıkarılmış olabilir.It can be deserialized into the following type that has Pascal case property names.

{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
}
public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}

Tutamaç taşması JSONHandle overflow JSON

Seri durumdan çıkarma sırasında, JSON 'da hedef türünün özellikleriyle temsil edilmeyen verileri alabilirsiniz.While deserializing, you might receive data in the JSON that is not represented by properties of the target type. Örneğin, hedef türünün bu olduğunu varsayalım:For example, suppose your target type is this:

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

Ve seri durumdan çıkarılacak JSON şu şekilde yapılır:And the JSON to be deserialized is this:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "Summary": "Hot",
  "DatesAvailable": [
    "2019-08-01T00:00:00-07:00",
    "2019-08-02T00:00:00-07:00"
  ],
  "SummaryWords": [
    "Cool",
    "Windy",
    "Humid"
  ]
}

Gösterilen türde gösterilen JSON serisini kaldırırsanız, DatesAvailable ve SummaryWords özellikleri nonereye gidebileceği ve kaybediliyor.If you deserialize the JSON shown into the type shown, the DatesAvailable and SummaryWords properties have nowhere to go and are lost. Bu özellikler gibi ek verileri yakalamak için, Jsonextensiondata özniteliğini veya türünde bir özelliğe uygulayın Dictionary<string,object> Dictionary<string,JsonElement> :To capture extra data such as these properties, apply the JsonExtensionData attribute to a property of type Dictionary<string,object> or Dictionary<string,JsonElement>:

public class WeatherForecastWithExtensionData
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    [JsonExtensionData]
    public Dictionary<string, object> ExtensionData { get; set; }
}

Daha önce Bu örnek türünde gösterilen JSON serisini kaldırdığınızda, ek veri özelliğin anahtar-değer çiftleri haline gelir ExtensionData :When you deserialize the JSON shown earlier into this sample type, the extra data becomes key-value pairs of the ExtensionData property:

ÖzellikProperty DeğerValue NotlarNotes
TarihDate 8/1/2019 12:00:00-07:008/1/2019 12:00:00 AM -07:00
TemperatureCelsiusTemperatureCelsius 00 Büyük/küçük harfe duyarlı uyuşmazlık ( temperatureCelsius JSON 'da), bu nedenle özellik ayarlanmadı.Case-sensitive mismatch (temperatureCelsius in the JSON), so the property isn't set.
ÖzetSummary Sık ErişimliHot
ExtensionDataExtensionData temperatureCelsius: 25temperatureCelsius: 25 Büyük/küçük harf eşleşmediğinden, bu JSON özelliği çok fazla olur ve sözlükte anahtar-değer çifti olur.Since the case didn't match, this JSON property is an extra and becomes a key-value pair in the dictionary.
DatesAvailable:DatesAvailable:
8/1/2019 12:00:00-07:008/1/2019 12:00:00 AM -07:00
8/2/2019 12:00:00-07:008/2/2019 12:00:00 AM -07:00
JSON 'dan fazladan özellik, değer nesnesi olarak bir dizi ile anahtar-değer çifti haline gelir.Extra property from the JSON becomes a key-value pair, with an array as the value object.
SummaryWords:SummaryWords:
Seyrek ErişimliCool
RüzgarlıWindy
İnsankimliğiHumid
JSON 'dan fazladan özellik, değer nesnesi olarak bir dizi ile anahtar-değer çifti haline gelir.Extra property from the JSON becomes a key-value pair, with an array as the value object.

Hedef nesne serileştirildiğinde, uzantı veri anahtarı değer çiftleri, gelen JSON 'da olduğu gibi JSON özellikleri olur:When the target object is serialized, the extension data key value pairs become JSON properties just as they were in the incoming JSON:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 0,
  "Summary": "Hot",
  "temperatureCelsius": 25,
  "DatesAvailable": [
    "2019-08-01T00:00:00-07:00",
    "2019-08-02T00:00:00-07:00"
  ],
  "SummaryWords": [
    "Cool",
    "Windy",
    "Humid"
  ]
}

ExtensionDataÖzellik ADıNıN JSON içinde görünmediğine dikkat edin.Notice that the ExtensionData property name doesn't appear in the JSON. Bu davranış, JSON 'nin seri durumdan çıkarılmazsız ek verileri kaybetmeden bir gidiş dönüş yapmasını sağlar.This behavior lets the JSON make a round trip without losing any extra data that otherwise wouldn't be deserialized.

Seri durumdan çıkarılırken null değeri yoksayIgnore null when deserializing

Varsayılan olarak, JSON 'daki bir özellik null ise, hedef nesnedeki karşılık gelen özellik null olarak ayarlanır.By default, if a property in JSON is null, the corresponding property in the target object is set to null. Bazı senaryolarda, target özelliği varsayılan bir değere sahip olabilir ve varsayılan değeri geçersiz kılmak için null değer istemezsiniz.In some scenarios, the target property might have a default value, and you don't want a null value to override the default.

Ö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 aşağıdaki JSON öğesinin seri durumdan çıkarıldığını varsayalım:And suppose the following JSON is deserialized:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": null
}

Seri durumdan çıktıktan sonra, Summary nesnesinin özelliği WeatherForecastWithDefault null olur.After deserialization, the Summary property of the WeatherForecastWithDefault object is null.

Bu davranışı değiştirmek için, JsonSerializerOptions.IgnoreNullValues true Aşağıdaki örnekte gösterildiği gibi öğesini olarak ayarlayın:To change this behavior, set JsonSerializerOptions.IgnoreNullValues to true, as shown in the following example:

var options = new JsonSerializerOptions
{
    IgnoreNullValues = true
};
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithDefault>(jsonString, options);

Bu seçenekle Summary nesnenin özelliği, WeatherForecastWithDefault serisini kaldırma işleminden sonra varsayılan "Özet yok" değeridir.With this option, the Summary property of the WeatherForecastWithDefault object is the default value "No summary" after deserialization.

JSON içindeki null değerler yalnızca geçerli olmaları durumunda yok sayılır.Null values in the JSON are ignored only if they are valid. Nullable değer türleri için null değerler özel durumlara neden olur.Null values for non-nullable value types cause exceptions.

Utf8JsonReader, Utf8JsonWriter ve JsonDocumentUtf8JsonReader, Utf8JsonWriter, and JsonDocument

System.Text.Json.Utf8JsonReader , bir veya ' dan okunan UTF-8 kodlu JSON metin için yüksek performanslı, düşük bir ayırma, Salt ilet okuyucu olur ReadOnlySpan<byte> ReadOnlySequence<byte> .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. JsonSerializer.DeserializeYöntemi Utf8JsonReader , kapakların altında kullanır.The JsonSerializer.Deserialize method uses Utf8JsonReader under the covers.

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. JsonSerializer.SerializeYöntemi Utf8JsonWriter , kapakların altında kullanır.The JsonSerializer.Serialize method uses Utf8JsonWriter under the covers.

System.Text.Json.JsonDocument kullanarak salt okunurdur Belge Nesne Modeli (DOM) oluşturma yeteneği sağlar Utf8JsonReader .System.Text.Json.JsonDocument provides the ability to build a read-only Document Object Model (DOM) by using Utf8JsonReader. 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 'lerle birlikte dizi ve nesne numaralandırıcıları sağlar.The JsonElement type provides array and object enumerators along with APIs to convert JSON text to common .NET types. JsonDocument bir RootElement özellik sunar.JsonDocument exposes a RootElement property.

Aşağıdaki bölümlerde, bu araçların JSON okuma ve yazma için nasıl kullanılacağı gösterilmektedir.The following sections show how to use these tools for reading and writing JSON.

Veri erişimi için JsonDocument kullanınUse JsonDocument for access to data

Aşağıdaki örnek, JsonDocument BIR JSON dizesindeki verilere rastgele erişim için sınıfının nasıl kullanılacağını gösterir:The following example shows how to use the JsonDocument class for random access to data in a JSON string:

double sum = 0;
int count = 0;

using (JsonDocument document = JsonDocument.Parse(jsonString))
{
    JsonElement root = document.RootElement;
    JsonElement studentsElement = root.GetProperty("Students");
    foreach (JsonElement student in studentsElement.EnumerateArray())
    {
        if (student.TryGetProperty("Grade", out JsonElement gradeElement))
        {
            sum += gradeElement.GetDouble();
        }
        else
        {
            sum += 70;
        }
        count++;
    }
}

double average = sum / count;
Console.WriteLine($"Average grade : {average}");

Yukarıdaki kod:The preceding code:

  • Analiz edilecek JSON 'in adlı bir dizede olduğunu varsayar jsonString .Assumes the JSON to analyze is in a string named jsonString.

  • Özelliği olan bir dizideki nesneler için Ortalama bir sınıf hesaplar Students Grade .Calculates an average grade for objects in a Students array that have a Grade property.

  • Bir sınıfa sahip olmayan öğrenciler için varsayılan bir 70 sınıfı atar.Assigns a default grade of 70 for students who don't have a grade.

  • Her yinelemeyle bir değişkeni arttırarak öğrencileri sayar count .Counts students by incrementing a count variable with each iteration. GetArrayLengthAşağıdaki örnekte gösterildiği gibi bir alternatif çağrdır:An alternative is to call GetArrayLength, as shown in the following example:

    double sum = 0;
    int count = 0;
    
    using (JsonDocument document = JsonDocument.Parse(jsonString))
    {
        JsonElement root = document.RootElement;
        JsonElement studentsElement = root.GetProperty("Students");
    
        count = studentsElement.GetArrayLength();
    
        foreach (JsonElement student in studentsElement.EnumerateArray())
        {
            if (student.TryGetProperty("Grade", out JsonElement gradeElement))
            {
                sum += gradeElement.GetDouble();
            }
            else
            {
                sum += 70;
            }
        }
    }
    
    double average = sum / count;
    Console.WriteLine($"Average grade : {average}");
    

Bu kodun işlediği JSON örneğine bir örnek aşağıda verilmiştir:Here's an example of the JSON that this code processes:

{
  "Class Name": "Science",
  "Teacher\u0027s Name": "Jane",
  "Semester": "2019-01-01",
  "Students": [
    {
      "Name": "John",
      "Grade": 94.3
    },
    {
      "Name": "James",
      "Grade": 81.0
    },
    {
      "Name": "Julia",
      "Grade": 91.9
    },
    {
      "Name": "Jessica",
      "Grade": 72.4
    },
    {
      "Name": "Johnathan"
    }
  ],
  "Final": true
}

JSON yazmak için JsonDocument kullanınUse JsonDocument to write JSON

Aşağıdaki örnek, öğesinden nasıl JSON yazılacağını göstermektedir JsonDocument :The following example shows how to write JSON from a JsonDocument:

string jsonString = File.ReadAllText(inputFileName);

var writerOptions = new JsonWriterOptions
{
    Indented = true
};

var documentOptions = new JsonDocumentOptions
{
    CommentHandling = JsonCommentHandling.Skip
};

using FileStream fs = File.Create(outputFileName);
using var writer = new Utf8JsonWriter(fs, options: writerOptions);
using JsonDocument document = JsonDocument.Parse(jsonString, documentOptions);

JsonElement root = document.RootElement;

if (root.ValueKind == JsonValueKind.Object)
{
    writer.WriteStartObject();
}
else
{
    return;
}

foreach (JsonProperty property in root.EnumerateObject())
{
    property.WriteTo(writer);
}

writer.WriteEndObject();

writer.Flush();

Yukarıdaki kod:The preceding code:

  • Bir JSON dosyasını okur, verileri bir JsonDocument dosyasına yükler ve bir dosyaya biçimli (düzgün yazdırılmış) JSON yazar.Reads a JSON file, loads the data into a JsonDocument, and writes formatted (pretty-printed) JSON to a file.
  • JsonDocumentOptionsJSON girişi içindeki açıklamalara izin verildiğini ancak yok sayılacağını belirtmek için kullanır.Uses JsonDocumentOptions to specify that comments in the input JSON are allowed but ignored.
  • İşiniz bittiğinde, Flush Yazıcı üzerindeki çağrılar.When finished, calls Flush on the writer. Diğer bir seçenek de yazıcı boşaltıatıldığı zaman yazıcının temizlemesini sağlar.An alternative is to let the writer autoflush when it's disposed.

Örnek kod tarafından işlenecek JSON girişi örneği aşağıda verilmiştir:Here's an example of JSON input to be processed by the example code:

{"Class Name": "Science","Teacher's Name": "Jane","Semester": "2019-01-01","Students": [{"Name": "John","Grade": 94.3},{"Name": "James","Grade": 81.0},{"Name": "Julia","Grade": 91.9},{"Name": "Jessica","Grade": 72.4},{"Name": "Johnathan"}],"Final": true}

Sonuç, aşağıdaki düzgün yazdırılmış JSON çıktıdır:The result is the following pretty-printed JSON output:

{
  "Class Name": "Science",
  "Teacher\u0027s Name": "Jane",
  "Semester": "2019-01-01",
  "Students": [
    {
      "Name": "John",
      "Grade": 94.3
    },
    {
      "Name": "James",
      "Grade": 81.0
    },
    {
      "Name": "Julia",
      "Grade": 91.9
    },
    {
      "Name": "Jessica",
      "Grade": 72.4
    },
    {
      "Name": "Johnathan"
    }
  ],
  "Final": true
}

Utf8JsonWriter kullanmaUse Utf8JsonWriter

Aşağıdaki örnek sınıfının nasıl kullanılacağını gösterir Utf8JsonWriter :The following example shows how to use the Utf8JsonWriter class:

var options = new JsonWriterOptions
{
    Indented = true
};

using (var stream = new MemoryStream())
{
    using (var writer = new Utf8JsonWriter(stream, options))
    {
        writer.WriteStartObject();
        writer.WriteString("date", DateTimeOffset.UtcNow);
        writer.WriteNumber("temp", 42);
        writer.WriteEndObject();
    }

    string json = Encoding.UTF8.GetString(stream.ToArray());
    Console.WriteLine(json);
}

Utf8JsonReader kullanmaUse Utf8JsonReader

Aşağıdaki örnek sınıfının nasıl kullanılacağını gösterir Utf8JsonReader :The following example shows how to use the Utf8JsonReader class:

var options = new JsonReaderOptions
{
    AllowTrailingCommas = true,
    CommentHandling = JsonCommentHandling.Skip
};
Utf8JsonReader reader = new Utf8JsonReader(jsonUtf8Bytes, options);

while (reader.Read())
{
    Console.Write(reader.TokenType);

    switch (reader.TokenType)
    {
        case JsonTokenType.PropertyName:
        case JsonTokenType.String:
            {
                string text = reader.GetString();
                Console.Write(" ");
                Console.Write(text);
                break;
            }

        case JsonTokenType.Number:
            {
                int intValue = reader.GetInt32();
                Console.Write(" ");
                Console.Write(intValue);
                break;
            }

            // Other token types elided for brevity
    }
    Console.WriteLine();
}

Yukarıdaki kod, jsonUtf8 DEĞIŞKENIN UTF-8 olarak kodlanmış GEÇERLI JSON içeren bir bayt dizisi olduğunu varsayar.The preceding code assumes that the jsonUtf8 variable is a byte array that contains valid JSON, encoded as UTF-8.

Utf8JsonReader kullanarak verileri filtrelemeFilter data using Utf8JsonReader

Aşağıdaki örnek, bir dosyanın zaman uyumlu olarak nasıl okunacağını ve bir değerin nasıl aranacağını gösterir:The following example shows how to read a file synchronously and search for a value:

using System;
using System.IO;
using System.Text;
using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class Utf8ReaderFromFile
    {
        private static readonly byte[] s_nameUtf8 = Encoding.UTF8.GetBytes("name");
        private static ReadOnlySpan<byte> Utf8Bom => new byte[] { 0xEF, 0xBB, 0xBF };
        public static void Run()
        {
            // ReadAllBytes if the file encoding is UTF-8:
            string fileName = "UniversitiesUtf8.json";
            ReadOnlySpan<byte> jsonReadOnlySpan = File.ReadAllBytes(fileName);

            // Read past the UTF-8 BOM bytes if a BOM exists.
            if (jsonReadOnlySpan.StartsWith(Utf8Bom))
            {
                jsonReadOnlySpan = jsonReadOnlySpan.Slice(Utf8Bom.Length);
            }

            // Or read as UTF-16 and transcode to UTF-8 to convert to a ReadOnlySpan<byte>
            //string fileName = "Universities.json";
            //string jsonString = File.ReadAllText(fileName);
            //ReadOnlySpan<byte> jsonReadOnlySpan = Encoding.UTF8.GetBytes(jsonString);


            int count = 0;
            int total = 0;

            var reader = new Utf8JsonReader(jsonReadOnlySpan);

            while (reader.Read())
            {
                JsonTokenType tokenType = reader.TokenType;

                switch (tokenType)
                {
                    case JsonTokenType.StartObject:
                        total++;
                        break;
                    case JsonTokenType.PropertyName:
                        if (reader.ValueTextEquals(s_nameUtf8))
                        {
                            // Assume valid JSON, known schema
                            reader.Read();
                            if (reader.GetString().EndsWith("University"))
                            {
                                count++;
                            }
                        }
                        break;
                }
            }
            Console.WriteLine($"{count} out of {total} have names that end with 'University'");
        }
    }
}

Yukarıdaki kod:The preceding code:

  • JSON 'un bir nesne dizisi içerdiğini ve her nesne dize türünde bir "ad" özelliği içerebildiği varsayılır.Assumes the JSON contains an array of objects and each object may contain a "name" property of type string.

  • "University" ile biten nesneleri ve "ad" özellik değerlerini sayar.Counts objects and "name" property values that end with "University".

  • Dosyanın UTF-16 olarak kodlandığını varsayar ve bunu UTF-8 ' e dönüştürür.Assumes the file is encoded as UTF-16 and transcodes it into UTF-8. Aşağıdaki kod kullanılarak UTF-8 olarak kodlanmış bir dosya doğrudan bir ile okunabilir ReadOnlySpan<byte> :A file encoded as UTF-8 can be read directly into a ReadOnlySpan<byte>, by using the following code:

    ReadOnlySpan<byte> jsonReadOnlySpan = File.ReadAllBytes(fileName);
    

    Dosya bir UTF-8 bayt sırası işareti (BOM) içeriyorsa, okuyucu metin gerektirdiğinden, baytları öğesine geçirmeden önce kaldırın Utf8JsonReader .If the file contains a UTF-8 byte order mark (BOM), remove it before passing the bytes to the Utf8JsonReader, since the reader expects text. Aksi takdirde, BOM geçersiz JSON olarak değerlendirilir ve okuyucu bir özel durum oluşturur.Otherwise, the BOM is considered invalid JSON, and the reader throws an exception.

Yukarıdaki kodun okuya, bir JSON örneği aşağıda verilmiştir.Here's a JSON sample that the preceding code can read. Sonuçtaki Özet ileti "2 ' den 4 ' ün" University "ile biten adlara sahiptir:The resulting summary message is "2 out of 4 have names that end with 'University'":

[
  {
    "web_pages": [ "https://contoso.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "contoso.edu" ],
    "name": "Contoso Community College"
  },
  {
    "web_pages": [ "http://fabrikam.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "fabrikam.edu" ],
    "name": "Fabrikam Community College"
  },
  {
    "web_pages": [ "http://www.contosouniversity.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "contosouniversity.edu" ],
    "name": "Contoso University"
  },
  {
    "web_pages": [ "http://www.fabrikamuniversity.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "fabrikamuniversity.edu" ],
    "name": "Fabrikam University"
  }
]

Utf8JsonReader kullanarak akıştan okumaRead from a stream using Utf8JsonReader

Büyük bir dosyayı (örneğin, boyutu bir gigabayt veya daha fazla) okurken, dosyanın tamamını aynı anda belleğe yükleme zorunluluğunu ortadan kaldırmak isteyebilirsiniz.When reading a large file (a gigabyte or more in size, for example), you might want to avoid having to load the entire file into memory at once. Bu senaryo için bir kullanabilirsiniz FileStream .For this scenario, you can use a FileStream.

Utf8JsonReaderBir akıştan okumak için kullanırken, aşağıdaki kurallar geçerlidir:When using the Utf8JsonReader to read from a stream, the following rules apply:

  • Kısmi JSON yükünün bulunduğu arabellek en az, onun içindeki en büyük JSON belirteci kadar büyük olmalıdır, böylece okuyucu ilerlemeye devam edebilir.The buffer containing the partial JSON payload must be at least as big as the largest JSON token within it so that the reader can make forward progress.
  • Arabellek en az JSON içindeki boşluk olan en büyük dizi kadar büyük olmalıdır.The buffer must be at least as big as the largest sequence of white space within the JSON.
  • Okuyucu, JSON yükünde bir sonrakini tamamen okuuncaya kadar okuduğu verileri takip etmez TokenType .The reader doesn't keep track of the data it has read until it completely reads the next TokenType in the JSON payload. Bu nedenle, arabellekte kalan baytlar varsa, bunları okuyucuya yeniden geçirmeniz gerekir.So when there are bytes left over in the buffer, you have to pass them to the reader again. BytesConsumedKaç baytın kaldığını anlamak için kullanabilirsiniz.You can use BytesConsumed to determine how many bytes are left over.

Aşağıdaki kod bir akıştan nasıl okunacağını gösterir.The following code illustrates how to read from a stream. Örnek bir gösterir MemoryStream .The example shows a MemoryStream. Benzer kod, FileStream FileStream Başlangıç AŞAMASıNDA bir UTF-8 bom içerdiğinde, ile birlikte çalışır.Similar code will work with a FileStream, except when the FileStream contains a UTF-8 BOM at the start. Bu durumda, kalan baytları öğesine geçirmeden önce bu üç baytı arabellekten çıkarmanız gerekir Utf8JsonReader .In that case, you need to strip those three bytes from the buffer before passing the remaining bytes to the Utf8JsonReader. Aksi halde, BOM JSON 'ın geçerli bir parçası olarak kabul edilmediğinden okuyucu bir özel durum oluşturur.Otherwise the reader would throw an exception, since the BOM is not considered a valid part of the JSON.

Örnek kod, bir 4KB arabelleğiyle başlar ve boyutun, bir bütün JSON belirtecine sığamayacak kadar büyük olmadığını bulduğu her seferinde arabellek boyutunu iki katına çıkarır. Bu, okuyucunun JSON yükünde ilerlemesinin ilerlemesini sağlamak için gereklidir.The sample code starts with a 4KB buffer and doubles the buffer size each time it finds that the size is not big enough to fit a complete JSON token, which is required for the reader to make forward progress on the JSON payload. Kod parçacığında belirtilen JSON örneği, yalnızca çok küçük bir başlangıç arabelleği boyutu ayarlarsanız (örneğin, 10 bayt) bir arabellek boyutunu tetikler.The JSON sample provided in the snippet triggers a buffer size increase only if you set a very small initial buffer size, for example, 10 bytes. Başlangıçtaki arabellek boyutunu 10 olarak ayarlarsanız, Console.WriteLine deyimler arabellek boyutunun arttığı nedeni ve etkisini gösterir.If you set the initial buffer size to 10, the Console.WriteLine statements illustrate the cause and effect of buffer size increases. 4 KB ilk arabellek boyutunda, tüm örnek JSON her biri tarafından gösterilir Console.WriteLine ve arabellek boyutunun hiçbir zaman artırılması gerekmez.At the 4KB initial buffer size, the entire sample JSON is shown by each Console.WriteLine, and the buffer size never has to be increased.

using System;
using System.IO;
using System.Text;
using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class Utf8ReaderPartialRead
    {
        public static void Run()
        {
            var jsonString = @"{
                ""Date"": ""2019-08-01T00:00:00-07:00"",
                ""Temperature"": 25,
                ""TemperatureRanges"": {
                    ""Cold"": { ""High"": 20, ""Low"": -10 },
                    ""Hot"": { ""High"": 60, ""Low"": 20 }
                },
                ""Summary"": ""Hot"",
            }";

            byte[] bytes = Encoding.UTF8.GetBytes(jsonString);
            var stream = new MemoryStream(bytes);

            var buffer = new byte[4096];

            // Fill the buffer.
            // For this snippet, we're assuming the stream is open and has data.
            // If it might be closed or empty, check if the return value is 0.
            stream.Read(buffer);

            var reader = new Utf8JsonReader(buffer, isFinalBlock: false, state: default);
            Console.WriteLine($"String in buffer is: {Encoding.UTF8.GetString(buffer)}");

            // Search for "Summary" property name
            while (reader.TokenType != JsonTokenType.PropertyName || !reader.ValueTextEquals("Summary"))
            {
                if (!reader.Read())
                {
                    // Not enough of the JSON is in the buffer to complete a read.
                    GetMoreBytesFromStream(stream, ref buffer, ref reader);
                }
            }

            // Found the "Summary" property name.
            Console.WriteLine($"String in buffer is: {Encoding.UTF8.GetString(buffer)}");
            while (!reader.Read())
            {
                // Not enough of the JSON is in the buffer to complete a read.
                GetMoreBytesFromStream(stream, ref buffer, ref reader);
            }
            // Display value of Summary property, that is, "Hot".
            Console.WriteLine($"Got property value: {reader.GetString()}");
        }

        private static void GetMoreBytesFromStream(MemoryStream stream, ref byte[] buffer, ref Utf8JsonReader reader)
        {
            int bytesRead;
            if (reader.BytesConsumed < buffer.Length)
            {
                ReadOnlySpan<byte> leftover = buffer.AsSpan((int)reader.BytesConsumed);

                if (leftover.Length == buffer.Length)
                {
                    Array.Resize(ref buffer, buffer.Length * 2);
                    Console.WriteLine($"Increased buffer size to {buffer.Length}");
                }

                leftover.CopyTo(buffer);
                bytesRead = stream.Read(buffer.AsSpan(leftover.Length));
            }
            else
            {
                bytesRead = stream.Read(buffer);
            }
            Console.WriteLine($"String in buffer is: {Encoding.UTF8.GetString(buffer)}");
            reader = new Utf8JsonReader(buffer, isFinalBlock: bytesRead == 0, reader.CurrentState);
        }
    }
}

Yukarıdaki örnek, arabelleğin ne kadar büyüeceği hakkında sınır yoktur.The preceding example sets no limit to how big the buffer can grow. Belirteç boyutu çok büyükse, kod bir OutOfMemoryException özel durumla başarısız olabilir.If the token size is too large, the code could fail with an OutOfMemoryException exception. Bu, JSON 1 GB veya daha fazla boyuttaki bir belirteç içeriyorsa, 1 GB boyutunun, arabelleğe sığamayacak kadar büyük bir boyuta neden olduğundan bu durum oluşabilir int32 .This can happen if the JSON contains a token that is around 1 GB or more in size, because doubling the 1 GB size results in a size that is too large to fit into an int32 buffer.

Ek kaynaklarAdditional resources