1. Introdução
Neste curso vamos dar um passo além de "só me salva a lista" para uma serialização flexível, precisa e performática usando System.Text.Json. Em projetos .NET modernos o JSON é o padrão de fato para troca de dados. Chamadas básicas Serialize/Deserialize são simples, mas cenários reais pedem ajustes finos: ignorar/renomear campos, controlar formatos de data, proteger contra ciclos, lidar com grandes volumes, conversores personalizados etc.
Vamos estudar não só os métodos do JsonSerializer, mas também parâmetros via JsonSerializerOptions, atributos, trabalho com Stream, gestão de memória e injeção de regras próprias de serialização através de JsonConverter.
Breve história e posicionamento do System.Text.Json
Por muito tempo no .NET dominou o Newtonsoft.Json (Json.NET) — flexível e maduro, mas nem sempre o mais rápido ou leve em dependências. Com o .NET Core 3.0 surgiu o built-in System.Text.Json: alta performance, mínimo de dependências (faz parte da plataforma), integração estreita com ASP.NET Core e evolução contínua com os releases do .NET.
2. Classes e métodos principais
O elemento base é a classe estática JsonSerializer, que dá duas direções:
- Serialização: objeto → string JSON (Serialize)
- Desserialização: string JSON → objeto do tipo desejado (Deserialize)
Exemplo de serialização de um objeto simples
using System.Text.Json;
var person = new Person { Name = "Ivan", Age = 30 };
string jsonString = JsonSerializer.Serialize(person);
Console.WriteLine(jsonString); // {"Name":"Ivan","Age":30}
Exemplo de desserialização
var json = "{\"Name\":\"Anna\",\"Age\":22}";
var anna = JsonSerializer.Deserialize<Person>(json);
Console.WriteLine(anna.Name); // Anna
Observação: o tipo Person já foi implementado em palestras anteriores — usamos ele aqui também.
3. Controle da serialização: JsonSerializerOptions
Em projetos reais quase sempre precisamos de configurações: nomes de propriedades em camelCase, formatos de data, tratamento de ciclos, valores padrão etc. Tudo isso é controlado via JsonSerializerOptions.
Exemplo de configuração
var options = new JsonSerializerOptions
{
WriteIndented = true, // Formatar o JSON de forma bonita (adiciona espaços e quebras)
PropertyNameCaseInsensitive = true, // Ignorar case dos nomes de propriedades na desserialização
PropertyNamingPolicy = JsonNamingPolicy.CamelCase // camelCase para propriedades (em vez de PascalCase)
};
string json = JsonSerializer.Serialize(person, options);
/*
{
"name": "Ivan",
"age": 30
}
*/
Por que isso importa? A maioria dos frameworks front-end espera camelCase, não o PascalCase do .NET.
4. Atributos: System.Text.Json.Serialization
Às vezes é mais prático controlar a serialização direto no modelo usando atributos. Eles são colocados em campos/propriedades para influenciar nomes, inclusão/exclusão e tratamento de valores.
Atributos principais
| Atributo | O que faz |
|---|---|
|
Exclui a propriedade da serialização/desserialização |
|
Usa outro nome no JSON |
|
Inclui propriedade/field não público na serialização |
|
Controla o tratamento de valores numéricos |
Exemplo: controlar propriedades via atributos
using System.Text.Json.Serialization;
public class Person
{
[JsonPropertyName("full_name")]
public string Name { get; set; }
[JsonIgnore]
public int SecretCode { get; set; }
public int Age { get; set; }
}
var person = new Person { Name = "Petr", Age = 45, SecretCode = 123 };
string json = JsonSerializer.Serialize(person);
// {"full_name":"Petr","Age":45}
Repare: SecretCode não entrou no JSON, e Name foi serializado como "full_name".
5. Serialização de coleções e objetos aninhados
Coleções — é tranquilo
var numbers = new List<int> { 1, 2, 3 };
string json = JsonSerializer.Serialize(numbers); // [1,2,3]
var people = new List<Person> {
new Person { Name = "Anna", Age = 20 },
new Person { Name = "Maxim", Age = 40 }
};
string jsonList = JsonSerializer.Serialize(people);
// [{"Name":"Anna","Age":20},{"Name":"Maxim","Age":40}]
Estruturas aninhadas
public class Group
{
public string Name { get; set; }
public List<Person> Members { get; set; }
}
var group = new Group
{
Name = "Desenvolvedores",
Members = new List<Person>
{
new Person { Name = "Sasha", Age = 23 },
new Person { Name = "Masha", Age = 28 }
}
};
string jsonGroup = JsonSerializer.Serialize(group, options);
/*
{
"name": "Desenvolvedores",
"members": [
{ "name": "Sasha", "age": 23 },
{ "name": "Masha", "age": 28 }
]
}
*/
6. Desserialização: o que é importante saber?
var json = "[{\"Name\":\"Ivan\",\"Age\":21}]";
var list = JsonSerializer.Deserialize<List<Person>>(json);
Console.WriteLine(list[0].Name); // Ivan
Cenário comum: se um campo estiver ausente no JSON, a propriedade correspondente recebe o valor padrão. Campos extras no JSON que não existem no modelo são ignorados. Mas se os tipos não baterem (por exemplo, chegou uma string onde era esperado um número) — a desserialização vai lançar uma exceção.
7. Tratamento de datas, horários, formatos e valores numéricos
public class Meeting
{
public string Topic { get; set; }
public DateTime Time { get; set; }
}
var meeting = new Meeting { Topic = "Reunião", Time = DateTime.Now };
string json = JsonSerializer.Serialize(meeting);
// {"Topic":"Reunião","Time":"2024-06-06T20:30:00.0000000+03:00"}
Por padrão DateTime é serializado em ISO 8601. Precisa de outro formato (por exemplo só a data)? Use uma propriedade separada ou um converter customizado (veja abaixo).
FAQ: Para serializar números como strings (ex.: telefones ou IDs grandes), use o atributo [JsonNumberHandling(JsonNumberHandling.WriteAsString)].
8. Streams e trabalho com arquivos
Você pode trabalhar não só com strings, mas também com Stream — isso é importante para dados grandes (arquivos, rede).
Exemplo de escrita em arquivo
using var fs = File.Create("person.json");
JsonSerializer.Serialize(fs, person);
// Não esqueça de chamar fs.Flush() ou usar using!
Exemplo de leitura de arquivo
using var fs = File.OpenRead("person.json");
var restored = JsonSerializer.Deserialize<Person>(fs);
Com streams existem métodos assíncronos SerializeAsync/DeserializeAsync — úteis em serviços de alta carga.
9. Conversores customizados
Se as regras padrão não servem (formatos de data/número não padrões, valores complexos, estruturas próprias) — escrevemos um JsonConverter.
Exemplo: data só como "dd.MM.yyyy"
public class CustomDateConverter : JsonConverter<DateTime>
{
public override DateTime Read(
ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
return DateTime.ParseExact(reader.GetString(), "dd.MM.yyyy", null);
}
public override void Write(
Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
{
writer.WriteStringValue(value.ToString("dd.MM.yyyy"));
}
}
var options = new JsonSerializerOptions();
options.Converters.Add(new CustomDateConverter());
var dt = new DateTime(2024, 6, 1);
string json = JsonSerializer.Serialize(dt, options); // "01.06.2024"
Conversores customizados são úteis para serializar coordenadas, vetores, cores, datas/moedas não padrão, vários formatos de ID, etc.
10. Nuances úteis
Tratamento de referências cíclicas e hierarquias profundas
var options = new JsonSerializerOptions
{
ReferenceHandler = ReferenceHandler.Preserve, // Preserva objetos com $id/$ref
WriteIndented = true
};
Importante: no JSON vão aparecer propriedades internas $id e $ref. Para troca com sistemas externos que não entendem isso, pode não ser adequado.
Diferenças entre System.Text.Json e Newtonsoft.Json
System.Text.Json já é bem potente, mas ainda não cobre todos os cenários do Newtonsoft.Json (construtores privados, objetos dinâmicos complexos etc.). Para a maioria das tarefas padrão recomendamos o serializer embutido — ele é mais rápido e sem dependências extras.
Trabalho interativo com JSON: DOM API
Quando você precisa "percorrer" o JSON sem ter um modelo completo, use JsonDocument e JsonElement.
using var doc = JsonDocument.Parse(jsonString);
JsonElement root = doc.RootElement;
if (root.TryGetProperty("Name", out var nameProperty))
{
Console.WriteLine(nameProperty.GetString());
}
11. Opções úteis e seus efeitos
| Propriedade | Valor/Propósito |
|---|---|
|
true — formatação com indentação |
|
true — ignorar case dos nomes na desserialização |
|
|
|
Regras para ignorar null/valores padrão |
|
, |
|
true — permitir vírgula no final do array |
|
Conversão de números para strings/volta (e outros) |
|
Lista de conversores customizados |
12. Erros comuns e dicas práticas
Erro #1: tipo errado na desserialização. Se serializou uma lista, desserialize exatamente para uma lista: List<T>, não para um objeto único.
Erro #2: case dos nomes de propriedades. Sem configuração de case-insensitive as propriedades podem "não ser encontradas". Use PropertyNameCaseInsensitive ou configure PropertyNamingPolicy.
Erro #3: tratamento incorreto de datas. O formato padrão é ISO 8601. Precisa outro? Crie e aplique um converter (JsonConverter<DateTime>).
Erro #4: esperar serialização de campos privados/estáticos. Por padrão só propriedades públicas são consideradas. Para casos não padrão use os atributos apropriados (por ex., [JsonInclude]).
Erro #5: não entender valores padrão. Campo ausente no JSON → valor padrão na propriedade. Leve isso em conta na lógica.
Erro #6: gerenciamento incorreto de streams. Feche recursos com using ou await using para evitar leaks e bloqueios.
GO TO FULL VERSION