Controlando a serialização XML usando atributos

Artigo
02/25/2015

Os atributos podem ser usados para controlar a serialização XML de um objeto ou criar um fluxo XML alternativo do mesmo conjunto de classes. Para obter mais detalhes sobre a criação de um fluxo XML alternativo, consulte Como especificar um nome de elemento alternativo para um fluxo XML.

Dica

Se o XML gerado tiver que estar em conformidade com a seção 5 do documento "Simple Object Access Protocol (SOAP) 1.1" do World Wide Web Consortium (www.w3.org), use os atributos listados em Atributos que controlam a serialização SOAP codificada.

Por padrão, um nome de elemento XML é determinado pela classe ou nome do membro. Em uma classe simple chamada Book, um campo chamado ISBN produzirá uma marca de elemento XML < ISBN >, conforme mostrado no exemplo a seguir.

Public Class Book
    Public ISBN As String
End Class
' When an instance of the Book class is serialized, it might 
' produce this XML:
' <ISBN>1234567890</ISBN>.

public class Book
{
    public string ISBN;
}
// When an instance of the Book class is serialized, it might 
// produce this XML:
// <ISBN>1234567890</ISBN>.

Esse comportamento padrão pode ser modificado se você quiser dar ao elemento um novo nome. O código a seguir mostra como um atributo permite isso definindo a propriedade ElementName de um XmlElementAttribute.

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class

public class TaxRates{
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Para obter mais informações sobre os atributos, consulte Estendendo metadados por meio de atributos. Para obter uma lista de atributos que controlam a serialização XML, consulte Atributos que controlam a serialização XML.

Controlando a serialização de matriz

Os atributos XmlArrayAttribute e XmlArrayItemAttribute são criados para controlar a serialização de matrizes. Usando esses atributos, você pode controlar o nome do elemento, namespace e o tipo de dados do esquema XSD (como definido no documento "Parte 2 do esquema XML: tipos de dados" do World Wide Web Consortium [www.w3.org]). Você também pode especificar os tipos que podem ser incluídos em uma matriz.

O XmlArrayAttribute determinará as propriedades do elemento XML incluído que resulta quando uma matriz é serializada. Por exemplo, por padrão, serializar a matriz abaixo resultará em um elemento XML denominado Employees. O elemento Employees conterá uma série de elementos nomeados de acordo com o tipo de matriz Employee.

Public Class Group
    Public Employees() As Employee
End Class
Public Class Employee
    Public Name As String
End Class

public class Group{
    public Employee[] Employees;
}
public class Employee{
    public string Name;
}

Uma instância serializada pode parecer com o seguinte.

<Group>
<Employees>
    <Employee>
        <Name>Haley</Name>
    </Employee>
</Employees >
</Group>

Aplicando um XmlArrayAttribute, você pode alterar o nome do elemento XML, da seguinte maneira.

Public Class Group
    <XmlArray("TeamMembers")> _
    Public Employees() As Employee
End Class

public class Group{
    [XmlArray("TeamMembers")]
    public Employee[] Employees;
}

O XML resultante pode parecer com o seguinte.

<Group>
<TeamMembers>
    <Employee>
        <Name>Haley</Name>
    </Employee>
</TeamMembers>

O XmlArrayItemAttribute, por outro lado, controla como os itens contidos na matriz são serializados. Observe que o atributo é aplicado ao campo que retorna a matriz.

Public Class Group
    <XmlArrayItem("MemberName")> _
    Public Employee() As Employees
End Class

public class Group{
    [XmlArrayItem("MemberName")]
    public Employee[] Employees;
}

O XML resultante pode parecer com o seguinte.

<Group>
<Employees>
    <MemberName>Haley</MemberName>
</Employees>
</Group>

Serializando classes derivadas

Outro uso do XmlArrayItemAttribute é permitir a serialização de classes derivadas. Por exemplo, outra classe denominada Manager que é derivada de Employee pode ser adicionada ao exemplo anterior. Se você não aplicar o XmlArrayItemAttribute, o código falhará em tempo de execução porque o tipo da classe derivada não será reconhecido. Para corrigir isso, aplique o atributo duas vezes, cada vez que definir a propriedade Type para cada tipo aceitável (base e derivada).

Public Class Group
    <XmlArrayItem(Type:=GetType(Employee)), _
    XmlArrayItem(Type:=GetType(Manager))> _
    Public Employees() As Employee
End Class
Public Class Employee
    Public Name As String
End Class
Public Class Manager
Inherits Employee
    Public Level As Integer
End Class

public class Group{
    [XmlArrayItem(Type = typeof(Employee)),
    XmlArrayItem(Type = typeof(Manager))]
    public Employee[] Employees;
}
public class Employee{
    public string Name;
}
public class Manager:Employee{
    public int Level;
}

Uma instância serializada pode parecer com o seguinte.

<Group>
<Employees>
    <Employee>
        <Name>Haley</Name>
    </Employee>
    <Employee xsi:type = "Manager">
        <Name>Ann</Name>
        <Level>3</Level>
    <Employee>
</Employees >
</Group>

Serializando uma matriz como uma sequência de elementos

Você também pode serializar uma matriz como uma sequência plana dos elementos XML aplicando um XmlElementAttribute ao campo que retorna a matriz da seguinte maneira.

Public Class Group
    <XmlElement> _
    Public Employees() As Employee
End Class

public class Group{
    [XmlElement]
    public Employee[] Employees;
}

Uma instância serializada pode parecer com o seguinte.

<Group>
<Employees>
    <Name>Haley</Name>
</Employees>
<Employees>
    <Name>Noriko</Name>
</Employees>
<Employees>
    <Name>Marco</Name>
</Employees>
</Group>

Outra maneira para diferenciar os dois fluxos XML é usar a Ferramenta de Definição de Esquema XML para gerar os arquivos de documento de esquema XSD de código compilado. (Para obter mais detalhes sobre como usar a ferramenta, consulte A ferramenta de definição de esquema XML e a serialização XML.) Quando nenhum atributo é aplicado ao campo, o esquema descreve o elemento da seguinte maneira.

<xs:element minOccurs="0" maxOccurs ="1" name="Employees" type="ArrayOfEmployee" />

Quando o XmlElementAttribute é aplicado ao campo, o esquema resultante descreve o elemento da seguinte maneira.

<xs:element minOccurs="0" maxOccurs="unbounded" name="Employees" type="Employee" />

Serializando um ArrayList

A classe ArrayList pode conter uma coleção de vários objetos. Você pode, portanto, usar um ArrayList da mesma maneira que usa uma matriz. Em vez de criar um campo que retorna uma matriz de objetos tipados, no entanto, você pode criar um campo que retorna um único ArrayList. No entanto, da mesma forma que ocorre com matrizes, você deverá informar o XmlSerializer dos tipos de objetos que o ArrayList contém. Para fazer isso, atribua várias instâncias do XmlElementAttribute ao campo, conforme mostrado no exemplo a seguir.

Public Class Group
    <XmlElement(Type:=GetType(Employee)), _
    XmlElement(Type:=GetType(Manager))> _
    Public Info As ArrayList
End Class

public class Group{
    [XmlElement(Type = typeof(Employee)), 
    XmlElement(Type = typeof(Manager))]
    public ArrayList Info;
}

Controlando a serialização de classes usando XmlRootAttribute e XmlTypeAttribute

Há dois atributos que podem ser aplicados a uma classe (e somente a uma classe): XmlRootAttribute e XmlTypeAttribute. Esses atributos são muito semelhantes. O XmlRootAttribute pode ser aplicado somente a uma classe: a classe que, quando serializada, representa o elemento de abertura e fechamento do documento XML. Em outras palavras, o elemento raiz. O XmlTypeAttribute, por outro lado, pode ser aplicado a qualquer classe, incluindo a classe raiz.

Por exemplo, nos exemplos anteriores, a classe Group é a classe raiz, e todos os seus campos públicos e propriedades tornam-se elementos XML encontrados no documento XML. Portanto, pode haver apenas uma classe de raiz. Aplicando o XmlRootAttribute, você pode controlar o fluxo XML produzido pelo XmlSerializer. Por exemplo, você pode alterar o nome e o namespace do elemento.

O XmlTypeAttribute permite que você controle o esquema do XML gerado. Esse recurso é útil quando você precisa publicar o esquema por um serviço Web XML. O exemplo a seguir aplica o XmlTypeAttribute e o XmlRootAttribute à mesma classe.

<XmlRoot("NewGroupName"), _
XmlType("NewTypeName")> _
Public Class Group
    Public Employees() As Employee
End Class

[XmlRoot("NewGroupName")]
[XmlType("NewTypeName")]
public class Group{
    public Employee[] Employees;
}

Se essa classe for criada, e a ferramenta de Definição de Esquema XML for usada para gerar seu esquema, você descobriria o seguinte XML descrevendo o Group.

<xs:element name="NewGroupName" type="NewTypeName">

Por outro lado, se você quisesse serializar uma instância da classe, somente NewGroupName seria encontrado no documento XML.

<NewGroupName>
    . . .
</NewGroupName>

Evitando a serialização com o XmlIgnoreAttribute

Pode haver situações quando uma propriedade pública ou um campo não precisam ser serializados. Por exemplo, um campo ou propriedade podem ser usados para conter metadados. Nesses casos, aplicar o XmlIgnoreAttribute ao campo ou propriedade e o XmlSerializer o ignorarão.