Controlando a serialização XML usando atributosControlling XML Serialization Using Attributes

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.Attributes can be used to control the XML serialization of an object or to create an alternate XML stream from the same set of classes. Para obter mais detalhes sobre como criar um fluxo XML alternativo, consulte como: Especifique um nome de elemento alternativo para um Stream do XML.For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

Observação

Se o XML gerado deve estar em conformidade com a seção 5 do documento do World Wide Web Consortium (W3C) simples objeto Access Protocol (SOAP) 1.1, use os atributos listados em atributos que controle codificado em SOAP Serialização.If the XML generated must conform to section 5 of the World Wide Web Consortium (W3C) document titled Simple Object Access Protocol (SOAP) 1.1, use the attributes listed in Attributes That Control Encoded SOAP Serialization.

Por padrão, um nome de elemento XML é determinado pela classe ou nome do membro.By default, an XML element name is determined by the class or member name. Em uma classe simples chamada Book, um campo chamado ISBN produzirá uma marcação de elemento XML <ISBN>, conforme mostrado no exemplo a seguir.In a simple class named Book, a field named ISBN will produce an XML element tag <ISBN>, as shown in the following example.

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.This default behavior can be changed if you want to give the element a new name. O código a seguir mostra como um atributo permite isso definindo a propriedade ElementName de um XmlElementAttribute.The following code shows how an attribute enables this by setting the ElementName property of a 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.For more information about attributes, see Attributes. Para obter uma lista de atributos que controlam a serialização XML, consulte Atributos que controlam a serialização XML.For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

Controlando a serialização de matrizControlling Array Serialization

Os atributos XmlArrayAttribute e XmlArrayItemAttribute são criados para controlar a serialização de matrizes.The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. Usando esses atributos, você pode controlar o nome do elemento, namespace e tipo de dados XSD (esquema XML) (conforme definido no documento do World Wide Web Consortium [www.w3.org] intitulado "XML Schema Part 2: Tipos de dados").Using these attributes, you can control the element name, namespace, and XML Schema (XSD) data type (as defined in the World Wide Web Consortium [www.w3.org] document titled "XML Schema Part 2: Datatypes"). Você também pode especificar os tipos que podem ser incluídos em uma matriz.You can also specify the types that can be included in an array.

O XmlArrayAttribute determinará as propriedades do elemento XML incluído que resulta quando uma matriz é serializada.The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. Por exemplo, por padrão, serializar a matriz abaixo resultará em um elemento XML denominado Employees.For example, by default, serializing the array below will result in an XML element named Employees. O elemento Employees conterá uma série de elementos nomeados de acordo com o tipo de matriz Employee.The Employees element will contain a series of elements named after the array type 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.A serialized instance might resemble the following.

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

Aplicando um XmlArrayAttribute, você pode alterar o nome do elemento XML, da seguinte maneira.By applying a XmlArrayAttribute, you can change the name of the XML element, as follows.

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.The resulting XML might resemble the following.

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

O XmlArrayItemAttribute, por outro lado, controla como os itens contidos na matriz são serializados.The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. Observe que o atributo é aplicado ao campo que retorna a matriz.Note that the attribute is applied to the field returning the array.

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.The resulting XML might resemble the following.

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

Serializando classes derivadasSerializing Derived Classes

Outro uso do XmlArrayItemAttribute é permitir a serialização de classes derivadas.Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. Por exemplo, outra classe denominada Manager que é derivada de Employee pode ser adicionada ao exemplo anterior.For example, another class named Manager that derives from Employee can be added to the previous example. 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.If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. Para corrigir isso, aplique o atributo duas vezes, cada vez que definir a propriedade Type para cada tipo aceitável (base e derivada).To remedy this, apply the attribute twice, each time setting the Type property for each acceptable type (base and derived).

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.A serialized instance might resemble the following.

<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 elementosSerializing an Array as a Sequence of Elements

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.You can also serialize an array as a flat sequence of XML elements by applying a XmlElementAttribute to the field returning the array as follows.

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.A serialized instance might resemble the following.

<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.Another way to differentiate the two XML streams is to use the XML Schema Definition tool to generate the XML Schema (XSD) document files from the compiled code. (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.(For more details on using the tool, see The XML Schema Definition Tool and XML Serialization.) When no attribute is applied to the field, the schema describes the element in the following manner.

<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.When the XmlElementAttribute is applied to the field, the resulting schema describes the element as follows.

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

Serializando um ArrayListSerializing an ArrayList

A classe ArrayList pode conter uma coleção de vários objetos.The ArrayList class can contain a collection of diverse objects. Você pode, portanto, usar um ArrayList da mesma maneira que usa uma matriz.You can therefore use a ArrayList much as you use an array. 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.Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. No entanto, da mesma forma que ocorre com matrizes, você deverá informar o XmlSerializer dos tipos de objetos que o ArrayList contém.However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. Para fazer isso, atribua várias instâncias do XmlElementAttribute ao campo, conforme mostrado no exemplo a seguir.To accomplish this, assign multiple instances of the XmlElementAttribute to the field, as shown in the following example.

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 XmlTypeAttributeControlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

Há dois atributos que podem ser aplicados a uma classe (e somente a uma classe): XmlRootAttribute e XmlTypeAttribute.There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. Esses atributos são muito semelhantes.These attributes are very similar. 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.The XmlRootAttribute can be applied to only one class: the class that, when serialized, represents the XML document's opening and closing element—in other words, the root element. O XmlTypeAttribute, por outro lado, pode ser aplicado a qualquer classe, incluindo a classe raiz.The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

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.For example, in the previous examples, the Group class is the root class, and all its public fields and properties become the XML elements found in the XML document. Portanto, pode haver apenas uma classe de raiz.Therefore, there can be only one root class. Aplicando o XmlRootAttribute, você pode controlar o fluxo XML produzido pelo XmlSerializer.By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. Por exemplo, você pode alterar o nome e o namespace do elemento.For example, you can change the element name and namespace.

O XmlTypeAttribute permite que você controle o esquema do XML gerado.The XmlTypeAttribute allows you to control the schema of the generated XML. Esse recurso é útil quando você precisa publicar o esquema por um serviço Web XML.This capability is useful when you need to publish the schema through an XML Web service. O exemplo a seguir aplica o XmlTypeAttribute e o XmlRootAttribute à mesma classe.The following example applies both the XmlTypeAttribute and the XmlRootAttribute to the same class.

<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.If this class is compiled, and the XML Schema Definition tool is used to generate its schema, you would find the following XML describing 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.In contrast, if you were to serialize an instance of the class, only NewGroupName would be found in the XML document.

<NewGroupName>
    . . .
</NewGroupName>

Evitando a serialização com o XmlIgnoreAttributePreventing Serialization with the XmlIgnoreAttribute

Pode haver situações quando uma propriedade pública ou um campo não precisam ser serializados.There might be situations when a public property or field does not need to be serialized. Por exemplo, um campo ou propriedade podem ser usados para conter metadados.For example, a field or property could be used to contain metadata. Nesses casos, aplicar o XmlIgnoreAttribute ao campo ou propriedade e o XmlSerializer o ignorarão.In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

Consulte tambémSee also