CodeGym /Cursos /C# SELF /Configuração da serialização XML

Configuração da serialização XML

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

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
[XmlRoot("Persons")]
Classe UserList
<Persons>...</Persons>
List<User> Users
[XmlElement("Person")]
<Person>...</Person>
int Id
[XmlAttribute("id")]
id="..." (atributo)
string Name
[XmlElement("FullName")]
<FullName>...</FullName>
string[] Emails
[XmlArray("EMails")][XmlArrayItem("Email")]
<EMails><Email>...</Email></EMails>
DateTime RegisteredAt
[XmlIgnore] (ver RegisteredAtString) -
string RegisteredAtString
[XmlAttribute("registered")]
registered="..."
Address[] Addresses
[XmlArray("UserAddresses")][XmlArrayItem("Address")]
<UserAddresses>...</UserAddresses>

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.

2
Tarefa
C# SELF, nível 48, lição 1
Bloqueado
Serialização de coleção usando XmlArray e XmlArrayItem
Serialização de coleção usando XmlArray e XmlArrayItem
Comentários
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION