Compartir a través de

Controlar la serialización XML mediante atributos

  • Artículo

Los atributos se pueden utilizar para controlar la serialización XML de un objeto o para crear una secuencia XML alternativa a partir del mismo conjunto de clases. Para obtener más detalles sobre cómo crear una secuencia XML alternativa, vea Cómo especificar el nombre de un elemento alternativo para una secuencia XML.

Nota

Si el XML generado debe ajustarse a la sección 5 del documento del W3C (www.w3.org) titulado "Simple Object Access Protocol (SOAP) 1.1", use los atributos que aparecen en Atributos que controlan la serialización SOAP codificada.

De manera predeterminada, el nombre de un elemento XML se determina mediante el nombre del miembro o de la clase. En una clase simple denominada Book, un campo denominado ISBN producirá una etiqueta de elemento XML <ISBN>, como se muestra en el ejemplo siguiente.

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>.

El comportamiento predeterminado se puede cambiar si se asigna un nombre nuevo al elemento. En el código siguiente se muestra la forma en que un atributo establece la propiedad ElementName de un XmlElementAttribute para conseguir esto.

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 acerca de los atributos, vea Extending Metadata Using Attributes. Para obtener una lista de los atributos que controlan la serialización XML, vea Atributos que controlan la serialización XML.

Controlar la serialización de matrices

Los atributos XmlArrayAttribute y XmlArrayItemAttribute están diseñados para controlar la serialización de matrices. Con estos atributos, puede controlar el nombre del elemento, el espacio de nombres y el tipo de datos de los esquemas XML (XSD), como se define en el documento del W3C, en www.w3.org, titulado "XML Schema Part 2: Datatypes". También puede especificar los tipos que pueden incluirse en una matriz.

XmlArrayAttribute determinará las propiedades del elemento XML envolvente que resulta cuando se serializa una matriz. Por ejemplo, de manera predeterminada, al serializar la matriz inferior se creará un elemento XML denominado Employees. El elemento Employees contendrá una serie de elementos con el nombre del 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;
}

Una instancia serializada tendría la apariencia siguiente.

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

Al aplicar un XmlArrayAttribute, puede cambiar el nombre del elemento XML de este modo.

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

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

El resultado XML tendría la apariencia siguiente.

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

Por otra parte, XmlArrayItemAttribute controla el modo en que se serializan los elementos que contiene la matriz. Observe que el atributo se aplica al campo que devuelve la matriz.

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

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

El resultado XML tendría la apariencia siguiente.

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

Serializar clases derivadas

Otro uso de XmlArrayItemAttribute es el de permitir la serialización de clases derivadas. Por ejemplo, otra clase denominada Manager que se deriva de Employee puede agregarse al ejemplo anterior. Si no aplica XmlArrayItemAttribute, el código generará errores en tiempo de ejecución porque el tipo de clase derivada no se reconocerá. Para solucionar esto, aplique el atributo dos veces y en cada una establezca la propiedad Type para cada tipo aceptable (base o 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;
}

Una instancia serializada tendría la apariencia siguiente.

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

Serializar una matriz como secuencia de elementos

También puede serializar una matriz como secuencia "sin formato" de elementos XML si aplica XmlElementAttribute al campo que devuelve la matriz, del modo siguiente.

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

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

Una instancia serializada tendría la apariencia siguiente.

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

Otro modo de diferenciar ambas secuencias XML es utilizar la herramienta Definición de esquemas XML para generar los archivos del documento de esquema XML (XSD) a partir del código compilado. Para obtener más detalles sobre cómo usar la herramienta, vea Herramienta Definición de esquemas XML y la serialización XML. Cuando no se aplica ningún atributo al campo, el esquema describe el elemento del modo siguiente.

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

Cuando el atributo XmlElementAttribute se aplica al campo, el esquema resultante describe el elemento como sigue.

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

Serializar una ArrayList

La clase ArrayList puede contener una colección de varios objetos. Por tanto, puede utilizar ArrayList igual que una matriz. En lugar de crear un campo que devuelva una matriz de objetos con tipo, puede crear un campo que devuelva una sola ArrayList. No obstante, al igual que sucede con las matrices, debe informar a XmlSerializer de los tipos de objetos que contiene ArrayList. Para ello, asigne varias instancias de XmlElementAttribute al campo, como se muestra en el ejemplo siguiente.

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;
}

Controlar la serialización de clases mediante XmlRootAttribute y XmlTypeAttribute

Hay dos atributos que pueden aplicarse a una clase (y sólo una clase): XmlRootAttribute y XmlTypeAttribute. Estos atributos son muy similares. XmlRootAttribute puede aplicarse únicamente a una clase: aquella que, cuando se serializa, representa el elemento de apertura y cierre del documento XML; en otras palabras, el elemento raíz. Por otra parte, XmlTypeAttribute puede aplicarse a cualquier clase, incluso a la clase raíz.

Por ejemplo, en los ejemplos anteriores, la clase Group es la clase raíz y todas sus propiedades y campos públicos se convierten en los elementos XML encontrados en el documento XML. Por lo tanto, sólo puede haber una clase raíz. Al aplicar el atributo XmlRootAttribute, puede controlar la secuencia XML que genera el XmlSerializer. Por ejemplo, puede cambiar el espacio de nombres y el nombre del elemento.

XmlTypeAttribute permite controlar el esquema del XML generado. Esta capacidad resulta útil cuando necesita publicar el esquema a través de un servicio Web XML. En el ejemplo siguiente se aplica XmlTypeAttribute y XmlRootAttribute a la misma clase.

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

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

Si se compila esta clase y se utiliza la herramienta Definición de esquemas XML para generar su esquema, encontraría el siguiente XML que describe a Group.

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

Por el contrario, si serializara una instancia de la clase, sólo se encontraría NewGroupName en el documento XML.

<NewGroupName>
    . . .
</NewGroupName>

Impedir la serialización con XmlIgnoreAttribute

Puede haber situaciones en las que no sea necesario serializar un campo o propiedad públicos. Por ejemplo, se puede usar un campo o una propiedad para contener metadatos. En estos casos, si aplica XmlIgnoreAttribute al campo o a la propiedad, XmlSerializer lo omitirá.

Vea también

Tareas

Cómo especificar el nombre de un elemento alternativo para una secuencia XML
Cómo serializar un objeto
Cómo deserializar un objeto

Conceptos

Atributos que controlan la serialización XML
Atributos que controlan la serialización SOAP codificada
Presentación de la serialización XML
Ejemplos de serialización XML