Controlar la serialización XML mediante atributos

Artículo
04/11/2008

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 Reemplazar la serialización 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 forma 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>.
[C#]
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
[C#]
public class TaxRates{
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Para obtener más información acerca de los atributos, vea Extender metadatos mediante atributos. Para obtener una lista de los atributos que controlan la serialización XML, vea Atributos que controlan la serialización.

Para controlar la serialización con atributos

Aplique uno de los atributos especiales a la clase o al miembro de la clase. Para obtener una lista de los atributos que controlan específicamente la serialización, vea Atributos que controlan la serialización.
Modifique el miembro de la clase, si es necesario. Por ejemplo, cambie el nombre de un miembro, pero establezca un valor apropiado en la propiedad ElementName. Un valor apropiado es aquél que se ajusta al esquema XML (XSD) del objeto serializado.
Serialice o deserialice la instancia de clase.

La secuencia XML resultante se ajustará al esquema, pero la clase tendrá un nombre de método legible.

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 forma 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
[C#]
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
[C#]
public class Group{
    [XmlArray("TeamMembers")]
    public Employee[] Employees;
}

El resultado XML tendría la apariencia siguiente.

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

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

Public Class Group
    <XmlArray("MemberName")> _
    Public Employee() As Employees
End Class
[C#]
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 fallará 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 XmlArrayItemAttribute.Type para cada tipo aceptable (base o 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
[C#]
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
[C#]
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 la herramienta Definición de esquemas XML y 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 lo tanto, puede utilizarla igual que una matriz. En lugar de crear un campo que devuelve 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
[C#]
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 se pueden aplicar a una clase (y sólo a una): XmlRootAttribute y XmlTypeAttribute. Estos atributos son muy similares. XmlRootAttribute puede aplicarse sólo a una clase: aquélla 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
[C#]
[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

Atributos que controlan la serialización XML | Atributos que controlan la serialización SOAP codificada | Presentar la serialización XML | Ejemplos de serialización XML | Reemplazar la serialización XML

Compartir a través de

Controlar la serialización XML mediante atributos

Controlar la serialización de matrices

Serializar clases derivadas

Serializar una matriz como secuencia de elementos

Serializar una ArrayList

Controlar la serialización de clases mediante XmlRootAttribute y XmlTypeAttribute

Impedir la serialización con XmlIgnoreAttribute

Vea también

Recursos adicionales