1. Introdução
Você já sabe que o .NET pode serializar e desserializar objetos para XML por padrão, com base em campos e propriedades públicas. Mas quando você quer fazer um XML bonito, compatível com programas/padrões alheios, ou quando não quer incluir certos detalhes internos no XML, precisa de ajustes finos.
Em C# existem atributos de serialização — "marcas" especiais que colocamos em classes, propriedades ou campos. Graças a esses atributos podemos controlar literalmente tudo: quais campos vão para o XML, quais serão ignorados, como um elemento será chamado, tornar algo atributo, ter estrutura complexa e até a ordem dos elementos!
Imagine que a serialização padrão é como preencher um formulário automaticamente: nome-sobrenome-meioNome em suas caixas, o resto — como cair. Com atributos você é tipo um funcionário chique do cartório: decide exatamente qual linha vai em qual caixa, o que pular, o que marcar em vermelho e o que esconder numa seção secreta.
Mapeamento entre objeto e XML
| Classe/Propriedade | Atributo | Resultado em XML |
|---|---|---|
|
Classe UserList | |
|
|
|
|
|
id="..." (atributo) |
|
|
|
|
|
|
|
[XmlIgnore] (ver RegisteredAtString) | - |
|
|
|
|
|
|
2. Visão geral dos principais atributos de serialização XML
Vamos passar pelos atributos mais populares que a galera do .NET tem usado por gerações!
Atributo [XmlElement] — Nome do elemento
Muda o nome do elemento no XML ou marca a propriedade/campo como um elemento XML.
public class Person
{
[XmlElement("FullName")]
public string Name { get; set; }
}
XML:
<Person>
<FullName>Vasiliy Petrov</FullName>
</Person>
Se não declarar o atributo — por padrão o nome do elemento coincide com o nome da propriedade/campo.
Atributo [XmlAttribute] — Serialização como atributo XML
Permite serializar a propriedade/campo como um atributo XML, em vez de como elemento.
public class Person
{
[XmlAttribute("id")]
public int Id { get; set; }
}
XML:
<Person id="123"></Person>
Em APIs XML reais costumam usar atributos para identificadores, datas, flags etc.
Atributo [XmlIgnore] — Ignorar campo/propriedade
O sonho de qualquer paranoico: excluir totalmente uma propriedade do processo de serialização e desserialização! Tudo que tiver esse atributo simplesmente não aparecerá no XML final.
public class Person
{
[XmlIgnore]
public string InternalNote { get; set; }
}
XML: (a propriedade InternalNote não existe e não vai existir aqui)
Atributos [XmlArray] e [XmlArrayItem] — controle sobre coleções
Atributos especiais para arrays e coleções. [XmlArray] define o nome do wrapper externo, e [XmlArrayItem] — o nome de cada item.
public class Person
{
[XmlArray("Phones")]
[XmlArrayItem("Phone")]
public string[] PhoneNumbers { get; set; }
}
XML:
<Person>
<Phones>
<Phone>+12951234567</Phone>
<Phone>+12876543210</Phone>
</Phones>
</Person>
Atributo [XmlRoot] — Nome do elemento raiz
Marca a própria classe para mudar o nome do elemento raiz no XML.
[XmlRoot("User")]
public class Person
{
public string Name { get; set; }
}
XML:
<User>
<Name>Anna</Name>
</User>
Atributo [XmlText] — Serializar como conteúdo de texto do elemento
Às vezes a especificação pede que o valor da propriedade seja simplesmente o texto dentro do elemento, não um subelemento nem um atributo.
public class Note
{
[XmlText]
public string Content { get; set; }
}
XML:
<Note>Ligue para a vovó!</Note>
Atributos [XmlNamespaceDeclarations], [XmlElement(Type = ...)]
Para cenários mais avançados (ex.: serialização com namespaces, suporte a herança etc.), existem atributos mais específicos. Confira a documentação oficial sobre XML serialization para a lista completa.
3. Prática: melhorando a serialização num exemplo real
Vamos, passo a passo, aprimorar nosso app de estudo para uma "serialização XML premium", para agradar até o inspetor XML mais exigente.
Classe básica sem atributos
Suponha que temos a classe de usuário assim:
public class User
{
public int Id { get; set; }
public string Name { get; set; }
public string[] Emails { get; set; }
public DateTime RegisteredAt { get; set; }
public string Password { get; set; }
}
A serialização padrão vai gerar algo como (e ainda grava a data no seu próprio formato):
<User>
<Id>42</Id>
<Name>Ivan Ivanov</Name>
<Emails>
<string>user@mail.com</string>
<string>admin@site.org</string>
</Emails>
<RegisteredAt>2024-07-01T00:00:00</RegisteredAt>
<Password>qwerty</Password>
</User>
O que está errado:
- É melhor não serializar a senha de jeito nenhum.
- Queremos a data como atributo e num formato legível.
- Queremos os Emails em formato mais bonito.
- Queremos o elemento raiz <Person>.
Adicionando configurações via atributos
[XmlRoot("Person")]
public class User
{
[XmlAttribute("id")]
public int Id { get; set; }
[XmlElement("FullName")]
public string Name { get; set; }
[XmlArray("EMails")]
[XmlArrayItem("Email")]
public string[] Emails { get; set; }
[XmlAttribute("registered")]
public string RegisteredAtString
{
get => RegisteredAt.ToString("yyyy-MM-dd");
set => RegisteredAt = DateTime.Parse(value);
}
[XmlIgnore]
public string Password { get; set; }
[XmlIgnore]
public DateTime RegisteredAt { get; set; }
}
Explicando os detalhes:
- Usamos [XmlAttribute("registered")] para serializar a data como atributo.
- Para serializar não o próprio DateTime, mas sua representação em string, adicionamos a propriedade separada RegisteredAtString, e escondemos o campo real com [XmlIgnore].
- Escondemos a senha com [XmlIgnore].
- O array de emails está configurado para que o wrapper externo seja <EMails> e cada email seja <Email>.
Resultado:
<Person id="42" registered="2024-07-01">
<FullName>Ivan Ivanov</FullName>
<EMails>
<Email>user@mail.com</Email>
<Email>admin@site.org</Email>
</EMails>
</Person>
4. Trabalhando com objetos aninhados
XML brilha quando existem objetos aninhados (por exemplo, usuário e seus endereços).
public class Address
{
[XmlAttribute]
public string City { get; set; }
[XmlText]
public string Details { get; set; }
}
public class User
{
// ...outras propriedades, ver acima...
public Address[] Addresses { get; set; }
}
E adicionamos a configuração para o array de endereços:
[XmlArray("UserAddresses")]
[XmlArrayItem("Address")]
public Address[] Addresses { get; set; }
Então o XML vai ficar assim:
<Person id="42" registered="2024-07-01">
<FullName>Ivan Ivanov</FullName>
<EMails>
<Email>user@mail.com</Email>
</EMails>
<UserAddresses>
<Address City="Neon city">ul. Zamkovaya, d.1</Address>
<Address City="North Cave">ul. Kraynyaya d.12</Address>
</UserAddresses>
</Person>
dá pra ver que cada <Address> tem city como atributo, e o próprio endereço está como texto interno.
5. Erros comuns e nuances
Se você serializa um objeto complexo e não vê as mudanças no XML que esperava — provavelmente esqueceu de aplicar o atributo correto. Às vezes propriedades/campos ficam sem marcação, aí o .NET usa o comportamento padrão.
Outra armadilha é o nome da coleção. Se a coleção (por ex., array de strings) não tiver [XmlArray] nem [XmlArrayItem], os elementos vão aparecer com a tag string (como no exemplo inicial). Para evitar isso, sempre defina explicitamente os nomes dos tags via atributos.
Cuidado com propriedades somente-get (getter-only) — essas não são desserializadas por padrão. Procure fornecer um set público.
Alguns tipos (por exemplo, dicionários ou interfaces) não são serializáveis pelo padrão do XmlSerializer, ou exigem tratamento especial.
GO TO FULL VERSION