Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / C#

JsonSerializerOptions — configurar la lectura y escritura de JSON

System.Text.Json.JsonSerializerOptions controla cómo se convierten los objetos .NET a JSON y cómo se leen desde JSON. Permite configurar los nombres de las propiedades, los comentarios, las propiedades desconocidas, el tratamiento de los números y la omisión de valores null. Configure una instancia antes de usarla por primera vez y reutilícela después.

Versión: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Sintaxis

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 proporciona configuración a JsonSerializer.Serialize y JsonSerializer.Deserialize. El ejemplo está destinado a .NET 10; UnmappedMemberHandling está disponible desde .NET 8. No se necesita ninguna característica del lenguaje en versión preliminar. new JsonSerializerOptions() sin más configuración conserva los nombres de las propiedades, distingue entre mayúsculas y minúsculas al leer y aplica un tratamiento estricto de los números; los valores predeterminados de las aplicaciones web pueden ser distintos.

JsonNamingPolicy representa una regla de conversión de nombres. PropertyNamingPolicy = JsonNamingPolicy.CamelCase convierte ItemCount en itemCount tanto al escribir como al leer. Esto no habilita la comparación sin distinguir mayúsculas y minúsculas: para eso se usa PropertyNameCaseInsensitive. El atributo [JsonPropertyName] tiene prioridad sobre la regla.

ReadCommentHandling utiliza JsonCommentHandling: el valor predeterminado Disallow rechaza los comentarios, mientras que Skip los acepta y los ignora. El valor Allow, destinado a un lector, no es compatible con esta opción del serializador. UnmappedMemberHandling utiliza JsonUnmappedMemberHandling: el valor predeterminado Skip ignora las propiedades JSON sin correspondencia, salvo que se recojan como datos de extensión. Si el valor efectivo para un tipo es Disallow, una propiedad JSON sin correspondencia provoca una JsonException. La configuración específica de un tipo puede prevalecer sobre el valor definido en las opciones del serializador. Si Disallow se establece solo en las opciones, un miembro marcado con [JsonExtensionData] puede recoger las propiedades sin correspondencia sin que se lance una excepción. Este ajuste no exige que todas las propiedades del modelo aparezcan en la entrada.

NumberHandling utiliza las marcas de JsonNumberHandling. El valor predeterminado Strict requiere tokens numéricos; AllowReadingFromString también permite leer "3" como número, pero sigue escribiéndolo como 3. La marca independiente WriteAsString escribe los números entre comillas. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull omite al escribir las propiedades cuyo valor es null; no omite 0 ni false, ni impide leer null.

Configure las opciones antes de la primera serialización o deserialización: después, la instancia pasa a ser inmutable. Reutilícela para conservar sus cachés de metadatos; compartirla entre varios subprocesos es seguro. El ejemplo omite un comentario, lee un número entre comillas y escribe el objeto sin Note. Una propiedad JSON sin correspondencia provocaría una JsonException al deserializar el tipo Payload del ejemplo.

Ejemplos

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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes