База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / C#

JsonSerializerOptions — конфигуриране на четенето и записването на JSON

System.Text.Json.JsonSerializerOptions управлява преобразуването на .NET обекти в JSON и четенето им от JSON. С него можете да конфигурирате имената на свойствата, коментарите, непознатите свойства, обработката на числа и пропускането на стойности null. Настройте екземпляра преди първата му употреба и го използвайте повторно.

Версия: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Синтаксис

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, ReadCommentHandling = JsonCommentHandling.Skip, UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, NumberHandling = JsonNumberHandling.AllowReadingFromString, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
var value = JsonSerializer.Deserialize<T>(json, options);
string result = JsonSerializer.Serialize(value, options);

System.Text.Json.JsonSerializerOptions предоставя конфигурация на JsonSerializer.Serialize и JsonSerializer.Deserialize. Примерът е предназначен за .NET 10; UnmappedMemberHandling е налично от .NET 8. Не е необходима езикова функция в предварителна версия. Обикновеното new JsonSerializerOptions() запазва имената на свойствата, различава главни и малки букви при четене и използва строго обработване на числата; настройките по подразбиране за уеб приложения може да са различни.

JsonNamingPolicy представя правило за преобразуване на имена. PropertyNamingPolicy = JsonNamingPolicy.CamelCase преобразува ItemCount в itemCount както при записване, така и при четене. Това не включва сравнение без разлика между главни и малки букви: за него използвайте PropertyNameCaseInsensitive. Атрибутът [JsonPropertyName] има предимство пред правилото.

ReadCommentHandling използва JsonCommentHandling: стойността по подразбиране Disallow отхвърля коментарите, а Skip ги приема и игнорира. Стойността Allow, предназначена за четец, не се поддържа от тази опция на сериализатора. UnmappedMemberHandling използва JsonUnmappedMemberHandling: стойността по подразбиране Skip игнорира свойствата в JSON без съответствие в типа, освен ако не бъдат събрани като данни за разширение. Ако за даден тип се прилага Disallow, свойство в JSON без съответствие предизвиква изключение JsonException. Конфигурацията на конкретния тип може да има предимство пред настройката в опциите на сериализатора. Ако Disallow е зададено само в опциите, член с атрибута [JsonExtensionData] може да събере свойствата без съответствие, без да се хвърли изключение. Тази настройка не изисква всяко свойство на модела да присъства във входните данни.

NumberHandling използва флаговете на JsonNumberHandling. Стойността по подразбиране Strict изисква числови токени; AllowReadingFromString позволява също "3" да бъде прочетено като число, но го записва като 3. Отделният флаг WriteAsString записва числата в кавички. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull пропуска при записване свойствата със стойност null; не пропуска 0 или false и не възпрепятства четенето на null.

Конфигурирайте опциите преди първата сериализация или десериализация: след това екземплярът става неизменяем. Използвайте го повторно, за да запазите кешовете с метаданни; споделянето между нишки е безопасно. Примерът пропуска коментар, прочита число в кавички и записва обекта без Note. При десериализация на типа Payload от примера свойство в JSON без съответствие би предизвикало изключение JsonException.

Примери

#nullable enable
using System;
using System.Text.Json;
using System.Text.Json.Serialization;

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    ReadCommentHandling = JsonCommentHandling.Skip,
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
    NumberHandling = JsonNumberHandling.AllowReadingFromString,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

const string json = "{ /* input */ \"itemCount\": \"3\", \"note\": null }";
var value = JsonSerializer.Deserialize<Payload>(json, options)
    ?? throw new InvalidOperationException();
Console.WriteLine(JsonSerializer.Serialize(value, options));

public sealed class Payload
{
    public int ItemCount { get; set; }
    public string? Note { get; set; }
}

Резултат

{"itemCount":3}

Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.

Източници