CodeGym /Cursos /C# SELF /Configuración de la serialización ( JsonSerializerOptions...

Configuración de la serialización ( JsonSerializerOptions)

C# SELF
Nivel 45, Lección 3
Disponible

1. Introducción

Todo va bien si tus necesidades coinciden con el comportamiento por defecto. Pero con bastante frecuencia el cliente (o un backend de terceros) exige un formato estricto: todo en camelCase, fechas — ISO 8601, omitir null, converters custom, y otras alegrías del integrador.

Ahí es donde aparece nuestro nuevo amigo — la clase JsonSerializerOptions.

Si la serialización fuera una cocina, esta clase serían tus especias, ollas e ingredientes secretos que puedes usar para sazonar la serialización a tu gusto.

Cómo usar JsonSerializerOptions

Para customizar el proceso de serialización o deserialización, simplemente pasamos el objeto de opciones a los métodos del serializer:

using System.Text.Json;

var options = new JsonSerializerOptions
{
    // Aquí irán tus ajustes
};

string json = JsonSerializer.Serialize(myObject, options);
var obj = JsonSerializer.Deserialize<MyType>(json, options);

Ese patrón aparece por todas partes: creas JsonSerializerOptions, las configuras a tu gusto (ver más abajo), y las pasas a los métodos del serializer Serialize/Deserialize.

Importante: Es perfectamente válido (y recomendable) reutilizar el mismo objeto JsonSerializerOptions para múltiples serializaciones.

2. Ajustes principales de JsonSerializerOptions

Veamos las "perillas" y "switches" más populares de esta clase.

Formateo JSON — WriteIndented

¿Te molestan las líneas JSON en una sola línea? No pasa nada — activa un bonito formateo con indentación.

var options = new JsonSerializerOptions
{
    WriteIndented = true // JSON bonito, "para humanos"
};

var person = new Person { Name = "Anna", Age = 30 };
string json = JsonSerializer.Serialize(person, options);

Console.WriteLine(json);

Salida:

{
  "Name": "Anna",
  "Age": 30
}

Sin WriteIndented = true obtendrías el aburrido {"Name":"Anna","Age":30}. En producción suelen usar JSON "minificado" (ocupa menos), y para debugging o logs — el formateado.

Naming de propiedades — PropertyNamingPolicy

A menudo un API exige que los nombres de propiedades estén en estilo camelCase (por ejemplo, firstName en vez de FirstName). En .NET las propiedades normalmente se nombran en PascalCase, y aquí viene bien la propiedad PropertyNamingPolicy:

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

var person = new Person { Name = "Oleg", Age = 25 };
string json = JsonSerializer.Serialize(person, options);
Console.WriteLine(json); // {"name":"Oleg","age":25}

Si necesitas un estilo propio (por ejemplo, TODO EN MAYÚSCULAS), puedes implementar tu propia JsonNamingPolicy. Normalmente CamelCase es suficiente.

3. Ignorar propiedades

Omitir o no omitir valores null — DefaultIgnoreCondition

A veces hace falta que los campos con valores vacíos (null) no aparezcan en el JSON. La razón: JSON más compacto, o porque el sistema externo no soporta null.

Para eso usamos la propiedad DefaultIgnoreCondition:

using System.Text.Json.Serialization;

var options = new JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

var person = new Person { Name = null, Age = 22 };
string json = JsonSerializer.Serialize(person, options);
Console.WriteLine(json); // {"Age":22}

Si quieres ignorar no sólo null, sino también valores por defecto (por ejemplo, int=0), usa WhenWritingDefault:

options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault;

Incluir fields privados — IncludeFields y [JsonInclude]

Por defecto se serializan sólo las propiedades públicas con setter público. Si quieres serializar también campos (fields), puedes activar:

var options = new JsonSerializerOptions
{
    IncludeFields = true
};

Ejemplo de clase:

public class Item
{
    public string Name;
    public int Id { get; set; }
}

var item = new Item { Name = "Book", Id = 12 };
string json = JsonSerializer.Serialize(item, options);
// {"Name":"Book","Id":12}

Para serializar campos/propiedades privadas puedes usar el atributo [JsonInclude], pero eso es tema para otra lección.

4. Conversión de valores

Formateo de fechas — Converters

Por defecto System.Text.Json serializa fechas estrictamente en formato ISO 8601 (por ejemplo, "2023-12-27T15:30:45.123Z"), que casi siempre está bien. Pero hay situaciones donde el formato de fecha/hora debe ser especial.

Para eso se enchufan converters custom. Ejemplo básico:

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

public class CustomDateTimeConverter : JsonConverter<DateTime>
{
    private string _format = "yyyyMMdd";

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        var date = reader.GetString();
        return DateTime.ParseExact(date, _format, null);
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(_format));
    }
}

// Usamos el converter
var options = new JsonSerializerOptions();
options.Converters.Add(new CustomDateTimeConverter());

var dateObj = new { Date = new DateTime(2022, 1, 5) };
string json = JsonSerializer.Serialize(dateObj, options); // {"Date":"20220105"}

5. Consejos útiles

No distinguir mayúsculas/minúsculas en nombres al deserializar — PropertyNameCaseInsensitive

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true
};

var json = "{\"name\":\"Vasya\",\"age\":33}";
var person = JsonSerializer.Deserialize<Person>(json, options);
// person.Name == "Vasya"

Controlar la profundidad y el nivel máximo de objetos — MaxDepth

var options = new JsonSerializerOptions
{
    MaxDepth = 32 // Por defecto 64
};

Pero si tus objetos pueden ser infinitamente anidados — por ejemplo, un árbol con referencias a padres e hijos — es mejor diseñar el modelo de otra forma.

Comentarios en JSON — ReadCommentHandling (deserialización)

JSON oficialmente no soporta comentarios, pero a veces te topas con archivos "creativos" que usan comentarios //.

var options = new JsonSerializerOptions
{
    ReadCommentHandling = JsonCommentHandling.Skip
};

string json = "{\n  \"Name\": \"Ivan\", // Nombre de usuario\n  \"Age\": 30\n}";
var person = JsonSerializer.Deserialize<Person>(json, options);

Soporte para caracteres especiales — Encoder

A veces necesitas controlar cómo el serializer hace escape de caracteres (por ejemplo, para no convertir cirílico a \uXXXX). Puedes especificar tu encoder:

using System.Text.Encodings.Web;

var options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};

Úsalo con cuidado, si no tus emojis/ideogramas pueden terminar convertidos a secuencias Unicode.

6. Errores típicos al configurar la serialización

Error №1: se olvida el setter público. Un campo o propiedad no se serializa porque no tiene setter público, o es privado.

Error №2: ignorar mal los valores null. Con DefaultIgnoreCondition activado, las propiedades con null no aparecerán en el JSON aunque no lo esperes.

Error №3: formato de fecha incorrecto. La fecha se serializa de forma distinta a la esperada — enchufa un converter custom (JsonConverter).

Error №4: esperar un orden fijo de propiedades. El estándar JSON no garantiza orden de campos. Si el API requiere un orden estricto, tendrás que cambiar el modelo o usar librerías de terceros.

Error №5: diferentes opciones al serializar y deserializar. Si no usas las mismas JsonSerializerOptions para escribir y leer JSON, pueden aparecer problemas, por ejemplo con mayúsculas/minúsculas en nombres o formatos.

2
Tarea
C# SELF, nivel 45, lección 3
Bloqueada
Configuración del formato de fechas en JSON
Configuración del formato de fechas en JSON
Comentarios
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION