CodeGym /Cursos /C# SELF /Imersão profunda em System.Text.Json

Imersão profunda em System.Text.Json

C# SELF
Nível 47, Lição 1
Disponível

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
[JsonIgnore]
Exclui a propriedade da serialização/desserialização
[JsonPropertyName("nome")]
Usa outro nome no JSON
[JsonInclude]
Inclui propriedade/field não público na serialização
[JsonNumberHandling]
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
WriteIndented
true — formatação com indentação
PropertyNameCaseInsensitive
true — ignorar case dos nomes na desserialização
PropertyNamingPolicy
JsonNamingPolicy.CamelCase
DefaultIgnoreCondition
Regras para ignorar null/valores padrão
ReferenceHandler
Preserve
,
IgnoreCycles
AllowTrailingCommas
true — permitir vírgula no final do array
NumberHandling
Conversão de números para strings/volta (e outros)
Converters
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.

2
Tarefa
C# SELF, nível 47, lição 1
Bloqueado
Serialização de objeto com configurações de JsonSerializerOptions
Serialização de objeto com configurações de JsonSerializerOptions
Comentários
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION