Controlar la serialización XML mediante atributosControlling XML Serialization Using Attributes

Los atributos se pueden utilizar para controlar la serialización XML de un objeto o crear una secuencia XML alternativa a partir del mismo conjunto de clases.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 obtener más información acerca de cómo crear una secuencia XML alternativa, vea Cómo: Especifique un nombre de elemento alternativo para un Stream XML.For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

Nota

Si el XML generado debe ajustarse a la sección 5 del documento de World Wide Web Consortium (W3C) titulado protocolo de acceso de objeto Simple (SOAP) 1.1, utilice los atributos listados en atributos que Control con codificación SOAP Serialización.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.

La clase o nombre de miembro determina, de forma predeterminada, un nombre del elemento XML.By default, an XML element name is determined by the class or member name. En una clase simple denominada Book, un campo denominado ISBN generará una etiqueta del elemento XML <ISBN> como se muestra en el ejemplo siguiente.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>.

Se puede cambiar este comportamiento predeterminado si desea dar un nuevo nombre al elemento.This default behavior can be changed if you want to give the element a new name. El código siguiente muestra cómo un atributo habilita esto estableciendo la propiedad ElementName de 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 obtener más información sobre atributos, vea Atributos.For more information about attributes, see Attributes. Para obtener una lista de atributos que controlan la serialización XML, vea Atributos que controlan la serialización XML.For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

Controlar la serialización de la matrizControlling Array Serialization

Los atributos XmlArrayAttribute y XmlArrayItemAttribute están diseñados para controlar la serialización de las matrices.The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. Uso de estos atributos, puede controlar el nombre del elemento, el espacio de nombres y el tipo de datos de esquemas XML (XSD) (tal como se define en el documento de World Wide Web Consortium [www.w3.org] titulado "esquema XML parte 2: Tipos de datos").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"). También puede especificar los tipos que pueden estar incluidos en una matriz.You can also specify the types that can be included in an array.

XmlArrayAttribute determinará las propiedades del elemento envolvente XML que resulta cuando se serializa una matriz.The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. Por ejemplo, de forma predeterminada, serializar la matriz siguiente producirá un elemento XML denominado Employees.For example, by default, serializing the array below will result in an XML element named Employees. El elemento Employees contendrá una serie de elementos denominados según el 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;
}

Una instancia serializada se podría parecer a lo siguiente.A serialized instance might resemble the following.

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

Aplicando XmlArrayAttribute, puede cambiar el nombre del elemento XML, como sigue.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;
}

El XML resultante puede parecerse a lo siguiente.The resulting XML might resemble the following.

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

XmlArrayItemAttribute, por otro lado, controla cómo se serializan los elementos contenidos en la matriz.The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. Observe que el atributo se aplica al campo que devuelve la 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;
}

El XML resultante puede parecerse a lo siguiente.The resulting XML might resemble the following.

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

Serializar las clases derivadasSerializing Derived Classes

Otro uso de XmlArrayItemAttribute es permitir la serialización de clases derivadas.Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. Por ejemplo, otra clase denominada Manager que deriva de Employee se puede agregar al ejemplo anterior.For example, another class named Manager that derives from Employee can be added to the previous example. Si no aplica XmlArrayItemAttribute, se producirá un error en el código en tiempo de ejecución porque no se reconocerá el tipo de clase derivada.If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. Para solucionar esto, aplique dos veces el atributo, estableciendo la propiedad Type cada vez, para cada tipo aceptable (base y derivado).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;
}

Una instancia serializada se podría parecer a lo siguiente.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>

Serializar una matriz como una secuencia de elementosSerializing an Array as a Sequence of Elements

También puede serializar una matriz como una secuencia plana de elementos XML aplicando XmlElementAttribute al campo que devuelve la matriz como sigue.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;
}

Una instancia serializada se podría parecer a lo siguiente.A serialized instance might resemble the following.

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

Otra manera de diferenciar las dos secuencias XML es utilizar la herramienta de definición de esquemas XML para generar los archivos de documento de esquema XML (XSD) a partir del 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 obtener más información sobre el uso de la herramienta, vea La herramienta de definición de esquema XML y serialización XML). Cuando ningún atributo se aplica al campo, el esquema describe el elemento de la manera siguiente.(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" />

Cuando XmlElementAttribute se aplica al campo, el esquema resultante describe el elemento como sigue.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" /> 

Serializar un ArrayListSerializing an ArrayList

La clase ArrayList puede contener una colección de objetos diversos.The ArrayList class can contain a collection of diverse objects. Además puede utilizar ArrayList tantas veces como utiliza la matriz.You can therefore use a ArrayList much as you use an array. En lugar de crear un campo que devuelve una matriz de objetos escritos, sin embargo, puede crear un campo que devuelve un ArrayListúnico.Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. Sin embargo, al igual que con las matrices, debe informar aXmlSerializer de los tipos de objetos ArrayList que contiene.However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. Para lograr esto, asigne varias instancias de XmlElementAttribute al campo, como se muestra en el ejemplo siguiente.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;
}

Controle la serialización de clases utilizando XmlRootAttribute y XmlTypeAttributeControlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

Existen dos atributos que pueden aplicarse a la clase (y solamente una clase): XmlRootAttribute y XmlTypeAttribute.There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. Estos atributos son muy similares.These attributes are very similar. XmlRootAttribute se puede aplicar a solo una clase: la clase que, cuando se serializa, representa el elemento de apertura y cierre del documento XML, en otras palabras, el elemento raíz.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. XmlTypeAttribute, por otro lado, se puede aplicar a cualquier clase, incluso a la clase raíz.The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

Por ejemplo, en los ejemplos anteriores, la clase Group es la clase raíz y todos sus campos públicos y propiedades se vuelven elementos XML situados en el 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. Además, solo puede haber una clase de raíz.Therefore, there can be only one root class. Aplicando XmlRootAttribute, puede controlar la secuencia XML generada por XmlSerializer.By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. Por ejemplo, puede cambiar el nombre de elemento y espacio de nombres.For example, you can change the element name and namespace.

XmlTypeAttribute le permite controlar el esquema del XML generado.The XmlTypeAttribute allows you to control the schema of the generated XML. Esta función es útil si se necesita publicar el esquema a través de un servicio Web XML.This capability is useful when you need to publish the schema through an XML Web service. En el siguiente ejemplo, se aplica XmlTypeAttribute y XmlRootAttribute a la misma clase.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;
}

Si esta clase está compilada, y la herramienta de definición de esquemas XML se utiliza para generar su esquema, encontraría el XML siguiente que describe 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">

En contraste, si fuera serializar una instancia de la clase, solo NewGroupName se buscarían en el 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>

Evitar la serialización con XmlIgnoreAttributePreventing Serialization with the XmlIgnoreAttribute

Podrían darse situaciones en las que una propiedad pública o el campo no necesite ser serializado.There might be situations when a public property or field does not need to be serialized. Por ejemplo, un campo o propiedad se puede utilizar para contener los metadatos.For example, a field or property could be used to contain metadata. En casos como éste, aplique XmlIgnoreAttribute al campo o la propiedad y XmlSerializer omitirán sobre él.In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

Vea tambiénSee also