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.
GO TO FULL VERSION