CodeGym /Cursos /C# SELF /Uso do Newtonsoft.Json

Uso do Newtonsoft.Json

C# SELF
Nível 44, Lição 4
Disponível

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:

  1. Abra o projeto.
  2. Clique com o botão direito no projeto no Solution Explorer.
  3. Selecione "Manage NuGet Packages...".
  4. Na busca, digite Newtonsoft.Json.
  5. 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);
2
Tarefa
C# SELF, nível 44, lição 4
Bloqueado
Uso dos atributos JsonProperty e JsonIgnore
Uso dos atributos JsonProperty e JsonIgnore
1
Pesquisa/teste
Classes padrão de serialização, nível 44, lição 4
Indisponível
Classes padrão de serialização
Classes e bibliotecas pra serialização
Comentários
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION