CodeGym /Cursos /C# SELF /Profundizando en Newtonsoft.Json

Profundizando en Newtonsoft.Json

C# SELF
Nivel 47, Lección 2
Disponible

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
NullValueHandling
Cómo tratar propiedades null (omitirlas o escribir explicitamente null)
DefaultValueHandling
Omitir valores por defecto o no
ReferenceLoopHandling
Qué hacer con referencias cíclicas
DateFormatString
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.

2
Tarea
C# SELF, nivel 47, lección 2
Bloqueada
Trabajo con estructuras anidadas
Trabajo con estructuras anidadas
Comentarios
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION