1. Introdução
Newtonsoft.Json é meio que um dinossauro no bom sentido. Foi o padrão de fato pra trabalhar com JSON no ecossistema .NET por muitos anos, muito antes do System.Text.Json existir. Milhões de projetos, milhares de bibliotecas e frameworks (até partes do ASP.NET Core por bastante tempo) usaram o Json.NET.
As vantagens dele são:
- Rico em recursos e muito flexível: o Json.NET oferece uma porrada de configurações, atributos e possibilidades pra customizar a serialização/desserialização. Ele faz coisas que o System.Text.Json ou faz com muito custo, ou não faz.
- Tolerante a JSON "não perfeito": dados vindos de sistemas externos nem sempre são bonitos — o Json.NET costuma ser mais permissivo e facilita desserializar sem dor de cabeça.
- Compatibilidade: se um projeto ou biblioteca depende do Json.NET, saber usar ele continua sendo importante.
Claro que o System.Text.Json é mais rápido e foi pensado para requisitos modernos. Mas o Newtonsoft.Json ainda é uma ferramenta poderosa, especialmente quando você precisa de lógica específica ou máxima flexibilidade.
Como instalar o Newtonsoft.Json?
Como é uma biblioteca externa, adicione o pacote via NuGet:
- Abra o projeto.
- Clique com o botão direito no projeto no Solution Explorer.
- Selecione "Manage NuGet Packages...".
- Na busca, digite Newtonsoft.Json.
- Escolha o pacote e clique em "Install".
Depois de instalar vai aparecer a nova dependência — aí é só usar o Json.NET!
Comparação das capacidades: Newtonsoft.Json vs System.Text.Json
| Funcionalidade | System.Text.Json | Newtonsoft.Json |
|---|---|---|
| Serialização/desserialização simples | Sim | Sim |
| Suporte a atributos para propriedades | Parcialmente | Completo |
| Conversores customizados | Sim | Sim |
| Trabalhar com campos privados | Não | Sim |
| Trabalhar com estruturas dinâmicas | Limitado | Sim |
| LINQ to JSON (JObject/JArray) | Não | Sim |
| Reference Loop Handling | Sim | Sim |
| Suporte a DataTable, DataSet e tipos complexos | Não | Sim |
| Desempenho | Melhor | Bom |
2. Exemplo de serialização e desserialização de um objeto simples
Vamos pegar uma estrutura de jogo genérica que a gente vai usar ao longo das aulas:
public class Player
{
public string Name { get; set; }
public int Health { get; set; }
public bool IsAlive { get; set; }
public List<string> Inventory { get; set; }
public Position Position { get; set; }
}
public class Position
{
public int X { get; set; }
public int Y { get; set; }
}
Agora vamos salvar um objeto Player em JSON e restaurá-lo:
using Newtonsoft.Json;
Player player1 = new Player
{
Name = "Aragorn",
Health = 100,
IsAlive = true,
Inventory = new List<string> { "sword", "bow", "healing potion" },
Position = new Position { X = 10, Y = 25 }
};
// Serialização para string JSON
string json = JsonConvert.SerializeObject(player1, Formatting.Indented);
Console.WriteLine(json);
// Desserialização de volta para o objeto Player
Player player2 = JsonConvert.DeserializeObject<Player>(json);
Console.WriteLine($"Nome: {player2.Name}, vida: {player2.Health}");
Tudo? Quase, mas isso é só a ponta do iceberg. Vamos ver por que o Newtonsoft.Json é mais interessante e flexível que outras libs.
3. Formatação, configurações e parâmetros avançados
Quando você serializa um objeto, pode gerar uma string compacta ou um JSON bonito e formatado. O comportamento é controlado por parâmetros e configurações.
Exemplo: Diferentes modos de formatação
// JSON bonito e legível
string prettyJson = JsonConvert.SerializeObject(player1, Formatting.Indented);
// JSON compacto (minified)
string compactJson = JsonConvert.SerializeObject(player1, Formatting.None);
Configurações de serialização
Se precisar, passe um JsonSerializerSettings para ajustes finos:
var settings = new JsonSerializerSettings
{
NullValueHandling = NullValueHandling.Ignore, // Ignorar campos com valor null
DefaultValueHandling = DefaultValueHandling.Ignore, // Ignorar campos com valor padrão
Formatting = Formatting.Indented
};
string customJson = JsonConvert.SerializeObject(player1, settings);
Você tem controle total sobre o formato de saída: quer pular campos vazios — sem problemas. Precisa serializar até propriedades privadas — configure o contrato.
4. Controle de campos e propriedades com atributos
Newtonsoft.Json suporta um sistema poderoso de atributos que ajustam a serialização direto na classe.
JsonProperty — Renomear propriedades
Se o protocolo JSON exigir um nome diferente para o campo:
public class Player
{
[JsonProperty("player_name")]
public string Name { get; set; }
// ...
}
JSON resultante:
{ "player_name": "Aragorn", ... }
JsonIgnore — Ignorar propriedade
public class Player
{
[JsonIgnore]
public int Health { get; set; }
}
Agora o campo Health vai sumir na serialização.
JsonConverter — Conversões customizadas
Permite especificar qual converter tratará um campo específico.
public class Player
{
[JsonConverter(typeof(InventoryToStringConverter))]
public List<string> Inventory { get; set; }
}
(Mais sobre converters — abaixo.)
5. Trabalhando com objetos aninhados e coleções
O Json.NET lida muito bem com objetos aninhados, arrays, coleções e dicionários.
Exemplo: Dicionários
public class GameStats
{
public Dictionary<string, int> Scores { get; set; }
}
GameStats stats = new GameStats
{
Scores = new Dictionary<string, int>
{
["Alice"] = 1023,
["Bob"] = 999
}
};
string statsJson = JsonConvert.SerializeObject(stats, Formatting.Indented);
Console.WriteLine(statsJson);
O JSON vai ficar assim:
{
"Scores": {
"Alice": 1023,
"Bob": 999
}
}
6. Estruturas complexas: referências cíclicas, Self-Referencing Objects
Às vezes objetos se referenciam entre si. O Newtonsoft.Json suporta serializar essas estruturas via configurações especiais.
Exemplo: Lidando com referências cíclicas
public class Person
{
public string Name { get; set; }
public Person Parent { get; set; }
public List<Person> Children { get; set; }
}
// Configurando serialização para ciclos
var settings = new JsonSerializerSettings
{
ReferenceLoopHandling = ReferenceLoopHandling.Ignore // ou .Serialize
};
Person p1 = new Person { Name = "Pai" };
Person p2 = new Person { Name = "Filho", Parent = p1 };
p1.Children = new List<Person> { p2 };
string json = JsonConvert.SerializeObject(p1, settings);
Console.WriteLine(json);
Por padrão, se deixar ReferenceLoopHandling = Error, você vai receber uma exceção. Isso protege contra serialização infinita acidental.
7. Trabalhando com estruturas dinâmicas: JObject, JArray
Quando a estrutura do JSON não é conhecida de antemão ou muda dinamicamente, use objetos dinâmicos sem tipagem rígida em C#.
Tipos principais:
- JObject — representação de um objeto JSON.
- JArray — representação de um array.
using Newtonsoft.Json.Linq;
// Converter string para JObject
string json = @"{ 'name': 'Aragorn', 'health': 100 }";
JObject obj = JObject.Parse(json);
Console.WriteLine((string)obj["name"]); // Aragorn
Console.WriteLine((int)obj["health"]); // 100
// Adição dinâmica de propriedades
obj["class"] = "Ranger";
Console.WriteLine(obj.ToString());
Iterando um array
string jsonArr = @"['apple', 'banana', 'cherry']";
JArray array = JArray.Parse(jsonArr);
foreach (JToken item in array)
{
Console.WriteLine(item);
}
8. Suporte a versionamento e campos obrigatórios
O formato JSON pode mudar, campos podem sumir. Use atributos e configurações:
- [JsonProperty(Required = Required.Always)] — exigir presença do campo (caso contrário lança exceção).
- [JsonProperty(DefaultValueHandling = DefaultValueHandling.Populate)] — preencher com valor padrão se o campo estiver ausente.
public class Player
{
[JsonProperty(Required = Required.Always)]
public string Name { get; set; }
[JsonProperty(DefaultValueHandling = DefaultValueHandling.Populate)]
[DefaultValue(50)]
public int Health { get; set; }
}
9. Conversão de datas e formatos de tempo
Trabalhar com datas frequentemente exige um formato explícito.
var dateSettings = new JsonSerializerSettings
{
DateFormatString = "yyyy-MM-dd"
};
string json = JsonConvert.SerializeObject(DateTime.Now, dateSettings);
Console.WriteLine(json); // "2024-06-15"
E para desserializar de volta:
string dateJson = "\"2024-06-15\""; // Atenção: isso é uma string entre aspas!
DateTime dt = JsonConvert.DeserializeObject<DateTime>(dateJson);
Console.WriteLine(dt);
GO TO FULL VERSION