Compartilhar via

Controlar a serialização XML usando atributos

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

Observação

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

Por padrão, um nome de elemento XML é determinado pelo nome da classe ou membro. Em uma classe chamada Book, um campo chamado ISBN produzirá uma marca <ISBN>de elemento XML, 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>.

O comportamento padrão pode ser alterado se você quiser dar um novo nome ao elemento. O código a seguir mostra como um atributo habilita essa funcionalidade definindo a ElementName propriedade 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 atributos, consulte 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 XmlArrayAttribute atributos e os XmlArrayItemAttribute atributos controlam a serialização de matrizes. Usando esses atributos, você pode controlar o nome do elemento, o namespace e o tipo de dados XSD (Esquema XML), conforme definido no documento W3C intitulado XML Schema Part 2: Datatypes. Você também pode especificar os tipos que podem ser incluídos em uma matriz.

Ele XmlArrayAttribute determinará as propriedades do elemento XML delimitador que resulta quando uma matriz é serializada. Por exemplo, por padrão, serializar a matriz abaixo resultará em um elemento XML chamado Employees. O elemento Employees conterá uma série de elementos com o nome do 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 ser semelhante ao seguinte código:

<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 ser semelhante ao seguinte código:

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

Por outro lado, o XmlArrayItemAttribute controla como os itens contidos no array são serializados.

Observação

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 ser semelhante ao seguinte código:

<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 chamada Manager que deriva Employee pode ser adicionada ao exemplo anterior. Se você não aplicar XmlArrayItemAttribute, o código falhará em tempo de execução porque o tipo de classe derivada não será reconhecido. Para corrigir esse resultado, aplique o atributo duas vezes, cada vez definindo a Type propriedade para cada tipo aceitável (base e derivado).

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 ser semelhante ao seguinte código:

<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 simples de 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 ser semelhante ao seguinte código:

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

Outra maneira de diferenciar os dois fluxos XML é usar a ferramenta de Definição de Esquema XML para gerar os arquivos de documento XSD (Esquema XML) do código compilado. Para obter mais informações 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 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 ArrayList classe pode conter uma coleção de objetos diversos. Portanto, você pode usar um ArrayList da mesma forma que usa uma matriz. Em vez de criar um campo que retorna uma matriz de objetos tipados, você pode criar um campo que retorna um único ArrayList. No entanto, assim como acontece com as matrizes, você deve informar XmlSerializer os tipos de objetos que ArrayList contém. Para fazer isso, atribua várias instâncias do XmlElementAttribute 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

Você pode aplicar dois atributos somente a uma classe: XmlRootAttribute e XmlTypeAttribute. Esses atributos são semelhantes. Pode XmlRootAttribute ser aplicado a apenas 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 Group classe é a classe raiz e todos os seus campos públicos e propriedades se tornam os elementos XML encontrados no documento XML. Portanto, você pode ter apenas uma classe raiz. Ao aplicar o XmlRootAttribute, você pode controlar o fluxo XML gerado pelo XmlSerializer. Por exemplo, você pode alterar o nome do elemento e o namespace.

O XmlTypeAttribute permite controlar o esquema do XML gerado. Essa funcionalidade é útil quando você precisa publicar o esquema por meio de um serviço Web XML. O exemplo a seguir aplica tanto o XmlTypeAttribute quanto 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 compilada e a ferramenta de Definição de Esquema XML for usada para gerar seu esquema, você encontrará o seguinte XML descrevendo Group:

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

Por outro lado, se você fosse serializar uma instância da classe, só NewGroupName seria encontrado no documento XML:

<NewGroupName>
    . . .
</NewGroupName>

Impedindo a serialização com o XmlIgnoreAttribute

Você pode se deparar com uma situação em que uma propriedade ou campo público não necessite ser serializado. Por exemplo, um campo ou propriedade pode ser usado para conter metadados. Nesses casos, aplique o XmlIgnoreAttribute ao campo ou à propriedade, e o XmlSerializer o ignorará.

Consulte também

  • Last updated on