Newtonsoft.Json para C# (.NET): guia completo com exemplos

O que é Newtonsoft.Json e para que serve?

\n\n

Newtonsoft.Json (frequentemente chamado apenas de Json.NET) é a biblioteca mais popular e poderosa para trabalhar com o formato JSON no ecossistema .NET. Ela fornece aos desenvolvedores em C# ferramentas de alto desempenho e flexíveis para serialização (conversão de objetos C# em string JSON) e desserialização (conversão de string JSON de volta para objetos C#).

\n\n

Para que serve? JSON (JavaScript Object Notation) tornou-se o padrão de facto para troca de dados entre servidores web e clientes, em arquivos de configuração, em APIs e bancos de dados (por exemplo, NoSQL). Newtonsoft.Json permite:

\n

\n
• Integrar-se facilmente com qualquer REST API — enviar e receber dados no formato JSON.
\n
• Trabalhar com configurações — ler e escrever arquivos JSON de configuração.
\n
• Gerenciar estruturas complexas — suporta objetos aninhados, arrays, dicionários e tipos dinâmicos.
\n
• Personalizar o processo de serialização — com atributos e configurações (contratos, ignorar propriedades, formatação de datas, etc.).
\n

\n\n

Instalação do Newtonsoft.Json

\n\n

Ao contrário do Python (onde se usa pip install) ou Node.js (npm install), no ecossistema .NET usa-se o gerenciador de pacotes NuGet. A biblioteca pode ser instalada de várias formas:

\n\n

Método 1: Através do console do gerenciador de pacotes (Visual Studio)

\n

Abra Ferramentas → Gerenciador de Pacotes NuGet → Console do Gerenciador de Pacotes e execute o comando:

\n

Install-Package Newtonsoft.Json

\n\n

Método 2: Através do .NET CLI (multiplataforma)

\n

Se você usa .NET Core / .NET 5+ e trabalha a partir do terminal, execute:

\n

dotnet add package Newtonsoft.Json

\n\n

Método 3: Através da interface do Visual Studio

\n

Clique com o botão direito no projeto → "Gerenciar Pacotes NuGet" → na aba "Navegar", encontre Newtonsoft.Json e clique em "Instalar".

\n\n

Após a instalação, adicione ao início do arquivo de código a diretiva using Newtonsoft.Json;.

\n\n

Início rápido: exemplo de código

\n\n

Vamos ver imediatamente como a biblioteca funciona com um exemplo simples. Suponha que temos a classe Person:

\n\n

using System;\nusing Newtonsoft.Json;\n\npublic class Person\n{\n    public string Name { get; set; }\n    public int Age { get; set; }\n    public string Email { get; set; }\n}\n\nclass Program\n{\n    static void Main()\n    {\n        // 1. Criando um objeto\n        var person = new Person\n        {\n            Name = "Ana",\n            Age = 30,\n            Email = "ana@example.com"\n        };\n\n        // 2. Serialização: objeto -> JSON\n        string json = JsonConvert.SerializeObject(person, Formatting.Indented);\n        Console.WriteLine("JSON serializado:");\n        Console.WriteLine(json);\n\n        // 3. Desserialização: JSON -> objeto\n        string jsonInput = @"{'Name':'João','Age':25,'Email':'joao@example.com'}";\n        Person deserializedPerson = JsonConvert.DeserializeObject<Person>(jsonInput);\n        Console.WriteLine($"\\nObjeto desserializado: {deserializedPerson.Name}, {deserializedPerson.Age}");\n    }\n}

\n\n

Saída:

\n

JSON serializado:\n{\n  "Name": "Ana",\n  "Age": 30,\n  "Email": "ana@example.com"\n}\n\nObjeto desserializado: João, 25

\n\n

Principais métodos e funções do Newtonsoft.Json

\n\n

Abaixo estão 10 métodos/funções principais da biblioteca com descrição detalhada e exemplos.

\n\n

1. JsonConvert.SerializeObject()

\n

O que faz: Converte um objeto .NET em uma string JSON.

\n

Parâmetros:

\n

\n
• value (object) — objeto para serializar.
\n
• formatting (Nullable<Form