CKTIS / C#
JsonSerializerOptions — configurar a leitura e a escrita de JSON
System.Text.Json.JsonSerializerOptions controla a conversão de objectos .NET para JSON e a leitura a partir de JSON. Permite configurar os nomes das propriedades, os comentários, as propriedades desconhecidas, o tratamento dos números e a omissão de valores null. Configure uma instância antes da primeira utilização e reutilize-a posteriormente.
Versão: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Sintaxe
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 fornece configuração a JsonSerializer.Serialize e JsonSerializer.Deserialize. O exemplo destina-se ao .NET 10; UnmappedMemberHandling está disponível desde o .NET 8. Não é necessária nenhuma funcionalidade da linguagem em pré-visualização. new JsonSerializerOptions() sem outras definições mantém os nomes das propriedades, distingue maiúsculas de minúsculas durante a leitura e aplica um tratamento estrito dos números; as predefinições das aplicações Web podem ser diferentes.
JsonNamingPolicy representa uma regra de conversão de nomes. PropertyNamingPolicy = JsonNamingPolicy.CamelCase converte ItemCount em itemCount tanto na escrita como na leitura. Isto não activa a correspondência sem distinção entre maiúsculas e minúsculas: para isso, utilize PropertyNameCaseInsensitive. O atributo [JsonPropertyName] tem prioridade sobre a regra.
ReadCommentHandling utiliza JsonCommentHandling: o valor predefinido Disallow rejeita comentários, enquanto Skip aceita-os e ignora-os. O valor Allow, destinado a um leitor, não é suportado por esta opção do serializador. UnmappedMemberHandling utiliza JsonUnmappedMemberHandling: o valor predefinido Skip ignora as propriedades JSON sem correspondência, a menos que sejam recolhidas como dados de extensão. Se a definição em vigor para um tipo for Disallow, uma propriedade JSON sem correspondência provoca uma JsonException. A configuração específica de um tipo pode prevalecer sobre a definição nas opções do serializador. Se Disallow estiver definido apenas nas opções, um membro marcado com [JsonExtensionData] pode recolher as propriedades sem correspondência sem que seja lançada uma excepção. Esta definição não exige que todas as propriedades do modelo estejam presentes na entrada.
NumberHandling utiliza as flags de JsonNumberHandling. O valor predefinido Strict exige tokens numéricos; AllowReadingFromString também permite ler "3" como número, mas continua a escrevê-lo como 3. A flag separada WriteAsString escreve os números entre aspas. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull omite, durante a escrita, as propriedades cujo valor é null; não omite 0 nem false e não impede a leitura de null.
Configure as opções antes da primeira serialização ou desserialização: depois disso, a instância torna-se imutável. Reutilize-a para manter as respectivas caches de metadados; é seguro partilhá-la entre threads. O exemplo ignora um comentário, lê um número entre aspas e escreve o objecto sem Note. Uma propriedade JSON sem correspondência provocaria uma JsonException ao desserializar o tipo Payload do exemplo.
Exemplos
#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; }
}
Resultado
{"itemCount":3}O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.
Fontes
- .NET API browser
- JsonSerializerOptions Class
- How to instantiate JsonSerializerOptions instances with System.Text.Json
- How to customize property names and values with System.Text.Json
- JsonSerializerOptions.ReadCommentHandling Property
- Handle unmapped members during deserialization
- JsonNumberHandling Enum
- JsonIgnoreCondition Enum