Visão geral das classes padrão de serialização no .NET

1. Introdução

Já que decidimos "desmontar a minifigura de LEGO em peças", vamos entender quais ferramentas temos no .NET para isso. Ou seja — quais classes padrão ajudam a serializar e desserializar objetos em vários formatos e o que existe por trás de cada uma.

Como é organizado o ecossistema de serialização do .NET

No momento atual (2025) o .NET oferece alguns enfoques principais para serialização, cada um com seu conjunto de classes e ferramentas. Os principais e mais comuns:

• Serialização JSON — a opção principal e mais moderna, usada na maioria dos projetos.
• Serialização XML — um pouco mais antiquada, mas ainda muito usada.
• Serialização binária — só para casos especiais e normalmente via soluções modernas de terceiros.

Muitos exemplos e a maior parte do código em .NET 9 usam justamente JSON, e isso não é moda — é o padrão da indústria. Mas o .NET também suporta outras opções — por precaução.

Os protagonistas da serialização no .NET

System.Text.Json

System.Xml.Serialization.XmlSerializer

Breve descrição de cada um

• System.Text.Json: Novo padrão para serialização JSON no .NET, apareceu no .NET Core 3.0, virou padrão no .NET 5+. Rápido, leve, seguro, vem "out of the box" no .NET 9. Documentação
• XmlSerializer: Alternativa antiga e testada para serializar em XML. Fácil de usar, mas com limitações (por exemplo, precisa de classe public e propriedades públicas). Bom para compatibilidade e contratos de dados rígidos. Documentação
• Newtonsoft.Json: Durante muito tempo foi o padrão de fato para JSON até o surgimento do System.Text.Json. Usado frequentemente para cenários complexos (dinâmica, propriedades privadas etc.). Documentação

Cadê o BinaryFormatter?

Se você encontrar na internet instruções para usar BinaryFormatter — provavelmente é um tutorial antigo. Não use BinaryFormatter: ele foi removido do .NET 9 por questões de segurança. A serialização binária moderna fica por conta de soluções de terceiros — por exemplo, Protobuf ou MessagePack.

2. Exemplos simples

Vamos aplicar na prática serialização e desserialização usando nosso já conhecido exemplo da classe Player do universo de jogos.

Preparemos a classe para serializar

// Player.cs
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; }
}

a) Serialização e desserialização em JSON com System.Text.Json

using System.Text.Json;

Player aragorn = 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 objeto Player para uma string JSON
string json = JsonSerializer.Serialize(aragorn);
// Mostra o JSON na tela
Console.WriteLine(json);

// Desserializa a string JSON de volta para um objeto Player
Player? aragornClone = JsonSerializer.Deserialize<Player>(json);
// Vamos checar se o clone funciona :)
Console.WriteLine(aragornClone?.Name); // Deve imprimir "Aragorn"

Viu como é simples — sem "danças com chocalho" e sem atributos mágicos. Agora — como fica em XML.

b) Serialização e desserialização em XML com XmlSerializer

using System.Xml.Serialization;

// Preparamos o serializer para a classe Player
XmlSerializer serializer = new XmlSerializer(typeof(Player));

// Serialização para arquivo
using FileStream fs = new FileStream("aragorn.xml", FileMode.Create);
serializer.Serialize(fs, aragorn); // Salvamos Aragorn no arquivo XML

// Desserialização do arquivo
using FileStream fs = new FileStream("aragorn.xml", FileMode.Open);
Player aragornFromXml = (Player) serializer.Deserialize(fs)!;
Console.WriteLine(aragornFromXml.Name); // Deve imprimir "Aragorn"

Atenção! XmlSerializer exige que classes e suas propriedades sejam públicas e tenham um construtor padrão sem parâmetros (se você sobrescrever o construtor — faça um public sem parâmetros). Caso contrário a serialização vai falhar.

c) Serialização e desserialização em JSON com Newtonsoft.Json

using Newtonsoft.Json; // Não esqueça de adicionar o pacote Newtonsoft.Json via NuGet!

// Serialização
string json2 = JsonConvert.SerializeObject(aragorn);

// Desserialização
Player? aragornFromNewtonsoft = JsonConvert.DeserializeObject<Player>(json2);

Console.WriteLine(aragornFromNewtonsoft?.Name); // De novo "Aragorn"

Parece quase igual, mas o Newtonsoft.Json tem muitas opções extras — por exemplo, dá pra serializar campos privados, customizar formatação e resolver cenários não triviais.

4. Nuances úteis

Serializadores padrão e o que eles conseguem

System.Text.Json

Newtonsoft.Json

XmlSerializer

Como escolher qual usar?

Se você não sabe por que precisaria de XML — quase sempre escolha JSON e System.Text.Json. É mais rápido, mais simples e segue práticas modernas.

XML faz sentido quando:

• Você integra com sistemas legados que exigem explicitamente XML.
• Precisa de um esquema rígido e validação da estrutura de dados.
• As estruturas são grandes, estáveis e a compatibilidade formal importa (configs, troca com sistemas enterprise).

JSON — quando:

• Você está criando uma aplicação moderna, falando com web e mobile.
• Quer simplicidade, legibilidade e compactação.
• Não quer puxar dependências extras.

Newtonsoft.Json — quando:

• Precisa serializar campos privados, customizações especiais, flexibilidade completa.
• Ou o projeto já usa essa biblioteca e migrar não é viável agora.

5. Erros típicos e armadilhas

Codificação. As classes de serialização padrão (especialmente ao trabalhar com arquivos) usam UTF-8 por padrão. Se aparecerem "caracteres estranhos", verifique como você está lendo/escrevendo os arquivos e se a codificação foi explicitamente definida. Documentação sobre configuração de encoding.

Tipos não suportados. Alguns serializadores padrão (principalmente XML) não conseguem serializar, por exemplo, dicionários (Dictionary), campos privados/protected, events, delegates e interfaces. Normalmente são suportadas classes públicas com propriedades simples públicas.

Versões das classes. Se você mudar a estrutura de uma classe (adicionar/renomear/remover propriedades), dados antigos podem não ser lidos ou desserializados incorretamente. Planeje versionamento de formato.

Valores null. Ao desserializar, se algum campo estiver ausente nos dados, a propriedade correspondente vai receber o valor padrão (para tipos de referência — null). Lembre-se de checar isso.

Atributos. Para ajustes finos costuma-se usar atributos como [JsonIgnore], [XmlElement] etc. Eles permitem excluir propriedades, alterar nomes de elementos e controlar o formato — detalhes nas próximas aulas.