1. Introducción
Si acabas de empezar con la serialización en .NET, es natural preguntarse: ¿para qué otra biblioteca si ya existe System.Text.Json? La respuesta es simple: Newtonsoft.Json surgió antes y con los años se convirtió en la herramienta más flexible para JSON en .NET.
Se volvió el estándar de facto porque soporta escenarios complejos: contratos personalizados, converters potentes, serialización de campos privados, LINQ a JSON, objetos dinámicos (JObject), manejo flexible de referencias cíclicas y muchos formatos de fecha/hora. Muchas librerías y API aún usan Json.NET “bajo el capó”.
Importante: en ciertos escenarios el incorporado System.Text.Json aún se queda corto frente a las capacidades de Newtonsoft.Json, así que aprender Json.NET sigue siendo relevante.
Cómo añadir Newtonsoft.Json (Json.NET)
Instala el paquete vía NuGet:
dotnet add package Newtonsoft.Json
Importa el namespace:
using Newtonsoft.Json;
2. Serialización con Newtonsoft.Json
Tomemos la clase tradicional Person:
public class Person
{
public string Name { get; set; }
public int Age { get; set; }
}
Serializar un objeto a una cadena JSON
Person person = new Person { Name = "Ivan", Age = 30 };
// Serialización a JSON
string json = JsonConvert.SerializeObject(person);
Console.WriteLine(json);
// Salida: {"Name":"Ivan","Age":30}
Deserializar JSON de vuelta a un objeto
string json = "{\"Name\":\"Ivan\",\"Age\":30}";
Person person = JsonConvert.DeserializeObject<Person>(json);
Console.WriteLine($"{person.Name}, {person.Age}");
// Salida: Ivan, 30
¿Qué ocurre "bajo el capó"?
Newtonsoft.Json recorre todas las propiedades públicas (public), las serializa a JSON y las escribe en la cadena. Al deserializar, empareja las claves del JSON con los nombres de las propiedades y rellena el objeto.
3. Serialización de colecciones de objetos
Serializar colecciones y arrays
Con colecciones todo funciona “out of the box”.
List<Person> people = new List<Person>
{
new Person { Name = "Ivan", Age = 30 },
new Person { Name = "Maria", Age = 25 }
};
string json = JsonConvert.SerializeObject(people);
// Salida: [{"Name":"Ivan","Age":30},{"Name":"Maria","Age":25}]
List<Person> deserialized = JsonConvert.DeserializeObject<List<Person>>(json);
// ¡Ahora tienes de nuevo una lista de Person!
Particularidades al serializar y deserializar diccionarios
var dict = new Dictionary<string, int>
{
["apple"] = 2,
["banana"] = 5
};
string json = JsonConvert.SerializeObject(dict);
// Salida: {"apple":2,"banana":5}
var deserializedDict = JsonConvert.DeserializeObject<Dictionary<string,int>>(json);
// ¡Todo funciona!
Si las claves no son strings (por ejemplo, Dictionary<int,string>), Json.NET convierte las claves a strings al serializar y al deserializar intentará convertirlas de nuevo. Para claves complejas (por ejemplo, Guid) es más fiable usar Dictionary<string, TValue>.
4. Trabajo con objetos anidados y jerarquías
public class Order
{
public int Id { get; set; }
public Person Customer { get; set; }
public List<Product> Products { get; set; }
}
public class Product
{
public string Title { get; set; }
public double Price { get; set; }
}
Order order = new Order
{
Id = 123,
Customer = new Person { Name = "Ivan", Age = 30 },
Products = new List<Product>
{
new Product { Title = "Portátil", Price = 50000.0 },
new Product { Title = "Ratón", Price = 1500.0 }
}
};
string json = JsonConvert.SerializeObject(order);
Console.WriteLine(json);
Resultado: los objetos anidados se representarán correctamente dentro de la estructura JSON.
5. Configurar la serialización con atributos
Ignorar una propiedad
public class Person
{
public string Name { get; set; }
[JsonIgnore]
public int Age { get; set; }
}
Ahora Age no aparecerá en el JSON.
Renombrar una propiedad
public class Person
{
[JsonProperty("full_name")]
public string Name { get; set; }
}
En el JSON el nombre será "full_name".
6. Configuración flexible: JsonSerializerSettings
Formateo (JSON bonito en varias líneas):
string json = JsonConvert.SerializeObject(
people,
Formatting.Indented
);
Resultado:
[
{
"Name": "Ivan",
"Age": 30
},
{
"Name": "Maria",
"Age": 25
}
]
Configuraciones comunes:
| Propiedad | Descripción |
|---|---|
|
Cómo tratar propiedades null (omitirlas o escribir explicitamente null) |
|
Omitir valores por defecto o no |
|
Qué hacer con referencias cíclicas |
|
Formato de cadena para fechas y horas |
Ejemplo omitiendo null:
string json = JsonConvert.SerializeObject(
person,
new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore }
);
7. Trabajo con estructuras JSON dinámicas: JObject, JArray y otros
Cuando la estructura JSON es desconocida, usa tipos de Newtonsoft.Json.Linq:
using Newtonsoft.Json.Linq;
string json = @"{
'Name': 'Ivan',
'Age': 30,
'Skills': ['C#', 'SQL', 'JSON']
}";
JObject obj = JObject.Parse(json);
Console.WriteLine(obj["Name"]); // Ivan
Console.WriteLine(obj["Skills"][0]); // C#
Crear JSON “al vuelo”:
var jObj = new JObject
{
["Status"] = "Success",
["Result"] = new JArray("item1", "item2", "item3")
};
Console.WriteLine(jObj.ToString(Formatting.Indented));
JObject y JArray son representaciones de objeto y array JSON, en esencia colecciones convenientes.
8. Matices útiles
Referencias cíclicas
Newtonsoft.Json puede manejarlas de forma flexible:
var settings = new JsonSerializerSettings
{
ReferenceLoopHandling = ReferenceLoopHandling.Ignore
};
string json = JsonConvert.SerializeObject(obj, settings);
Así los ciclos se omiten. Para preservar referencias puedes usar ReferenceLoopHandling.Serialize junto con [JsonObject(IsReference = true)].
Serialización de objetos anónimos y dinámicos
var anon = new { Foo = 42, Bar = "Hello" };
string json = JsonConvert.SerializeObject(anon);
// {"Foo":42,"Bar":"Hello"}
Validación y manejo de errores
try
{
Person p = JsonConvert.DeserializeObject<Person>(brokenJson);
}
catch (JsonSerializationException ex)
{
Console.WriteLine("Error al deserializar: " + ex.Message);
}
Comparación Newtonsoft.Json vs System.Text.Json
| Newtonsoft.Json (Json.NET) | System.Text.Json (.NET) | |
|---|---|---|
| Soporte .NET | .NET Framework/Standard/6+ | .NET Core 3.0+ / .NET 5/6/9 |
| LINQ a JSON (JObject/JArray) | Sí | No |
| Configuración flexible | Muy amplia | Limitada |
| Atributos ([JsonProperty], ...) | Sí | Sí (parcialmente, menos capacidades) |
| Soporte de propiedades privadas | Sí | No |
| Velocidad | Más lento en algunos escenarios | Más rápido |
| Converters complejos | Sí | Sí (menos flexible por ahora) |
| Soporte DataTable, DataSet | Sí | No |
| Documentación y ejemplos | Montones | En crecimiento |
9. Errores de novato y trampas típicas
Error #1: las propiedades quedan en null después de deserializar.
A menudo la propiedad no tiene setter o falta un constructor sin parámetros — el serializador no tiene cómo rellenar el objeto.
Error #2: nombres de propiedades no coinciden entre JSON y la clase.
Si en el JSON el campo es "fullName", y en la clase es FullName, usa [JsonProperty] o configura un ContractResolver para mapear los nombres.
Error #3: por defecto la serialización sólo trabaja con propiedades públicas.
Campos/propiedades privadas no se serializan sin ajustes adicionales. Necesitas converters o resolvers/contracts especiales.
Error #4: referencias cíclicas provocan StackOverflowException.
Referencias mutuas entre objetos pueden enredar la serialización sin configuración. Ajusta el manejo de referencias (por ejemplo, ReferenceLoopHandling) o cambia el modelo de datos.
GO TO FULL VERSION