Contrôler la sérialisation XML avec des attributs

  • Article

Les attributs peuvent être utilisés pour contrôler la sérialisation XML d'un objet ou pour créer un flux de données XML différent à partir du même ensemble de classes. Pour plus d’informations sur la création d’un flux de données XML différent, consultez Guide pratique : spécifier un nom d’élément différent pour un flux XML.

Notes

Si le code XML généré doit se conformer à la section 5 du document World Wide Web Consortium (W3C) intitulé Simple Object Access Protocol (SOAP) 1.1, utilisez les attributs répertoriés dans Attributs contrôlant la sérialisation encodée selon le protocole SOAP.

Par défaut, un nom d'élément XML est déterminé par le nom de la classe ou du membre. Dans une classe simple nommée Book, un champ nommé ISBN génère une balise d’élément XML<ISBN>, comme illustré dans l’exemple suivant :

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

Ce comportement par défaut peut être modifié si vous souhaitez donner un nouveau nom à l'élément. Le code suivant indique de quelle manière un attribut active cette fonction en définissant la propriété ElementName d'un XmlElementAttribute :

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class

public class TaxRates {
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Pour plus d’informations sur les attributs, consultez Attributs. Pour obtenir une liste complète des attributs qui contrôlent la sérialisation XML, consultez Attributs qui contrôlent la sérialisation XML.

Contrôle de la sérialisation de tableau

Les attributs XmlArrayAttribute et XmlArrayItemAttribute sont conçus pour contrôler la sérialisation de tableaux. À l'aide de ces attributs, vous pouvez contrôler le nom d'élément, l'espace de noms et le schéma XML (XSD), comme défini dans le document du W3C intitulé Schéma XML Partie 2 : types de données. Vous pouvez également spécifier les types qui peuvent être inclus dans un tableau.

XmlArrayAttribute détermine les propriétés de l'élément XML englobant obtenu lorsqu'un tableau est sérialisé. Par exemple, la sérialisation du tableau suivant génère par défaut un élément XML nommé Employees. L'élément Employees contient une série d'éléments nommée d'après le type de tableau 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;
}

Une instance sérialisée peut se présenter comme suit :

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

En appliquant un XmlArrayAttribute, vous pouvez modifier le nom de l'élément XML, comme suit :

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

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

Le code XML obtenu peut se présenter comme suit :

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

En revanche, XmlArrayItemAttribute contrôle la manière dont les éléments contenus dans le tableau sont sérialisés.

Notes

L’attribut est appliqué au champ renvoyant le tableau.

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

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

Le code XML obtenu peut se présenter comme suit :

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

Sérialisation de classes dérivées

XmlArrayItemAttribute permet également de sérialiser des classes dérivées. Par exemple, une autre classe nommée Manager, dérivée de Employee, peut être ajoutée à l'exemple précédent. Si vous n'appliquez pas XmlArrayItemAttribute, le code ne pourra pas s'exécuter puisque le type de classe dérivée ne sera pas reconnu. Pour résoudre ce résultat, appliquez l'attribut deux fois, en définissant à chaque fois la propriété Type pour chaque type acceptable (base et dérivé).

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

Une instance sérialisée peut se présenter comme suit :

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

Sérialisation d'un tableau sous forme de séquence d'éléments

Vous pouvez également sérialiser un tableau sous forme de séquence en deux dimensions d'éléments XML en appliquant XmlElementAttribute au champ renvoyant le tableau suivant :

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

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

Une instance sérialisée peut se présenter comme suit :

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

Pour différencier les deux flux de données XML, vous pouvez également utiliser l'outil XML Schema Definition pour générer des fichiers de document de schéma XML (XSD) à partir du code compilé. Pour plus d’informations sur l’utilisation de l’outil, consultez Outil XML Définition du schéma et sérialisation XML. Lorsqu'aucun attribut n'est appliqué au champ, le schéma décrit l'élément de la manière suivante :

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

Lorsque le XmlElementAttribute est appliqué au champ, le schéma obtenu décrit l'élément comme suit :

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

Sérialisation d'un ArrayList

La classe ArrayList peut contenir une collection d'objets divers. Par conséquent, vous pouvez utiliser un ArrayList plus souvent qu'un tableau. Au lieu de créer un champ qui retourne un tableau d'objets typés, vous pouvez cependant créer un champ qui retourne un ArrayList unique. Toutefois, comme avec les tableaux, vous devez indiquer à XmlSerializer les types d'objets que contient l'ArrayList. Pour ce faire, assignez plusieurs instances de XmlElementAttribute à ce champ, comme illustré dans l'exemple suivant.

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

Contrôle de la sérialisation de classes à l'aide de XmlRootAttribute et XmlTypeAttribute

Vous pouvez appliquer deux attributs uniquement à une classe : XmlRootAttribute et XmlTypeAttribute. Ces attributs sont similaires. XmlRootAttribute peut être appliqué à une seule classe : celle qui, une fois sérialisée, représente l'élément ouvrant et fermant du document XML, c'est-à-dire l'élément racine. En revanche, XmlTypeAttribute peut être appliqué à n'importe quelle classe, y compris la classe racine.

Par exemple, la classe Group correspond à la classe racine dans les exemples précédents, et tous ses champs et propriétés publics deviennent les éléments XML recherchés dans le document XML. Par conséquent, il peut y avoir uniquement une seule classe racine. En appliquant XmlRootAttribute, vous pouvez contrôler le flux de données XML généré par XmlSerializer. Par exemple, vous pouvez modifier le nom de l'élément et l'espace de noms.

XmlTypeAttribute vous permet de contrôler le schéma du code XML généré. Cette fonction est utile lorsque vous devez publier le schéma via un service Web XML. L'exemple suivant applique XmlTypeAttribute et XmlRootAttribute à la même classe :

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

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

Si cette classe est générée et que l'outil XML Définition du schéma est utilisé pour générer son schéma, vous obtenez le code XML suivant qui décrit Group :

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

En revanche, si vous deviez sérialiser une instance de la classe, vous obtiendriez uniquement NewGroupName dans le document XML :

<NewGroupName>
    . . .
</NewGroupName>

Empêcher la sérialisation avec XmlIgnoreAttribute

Vous pouvez rencontrer une situation dans laquelle une propriété ou un champ public ne doit pas être sérialisé. Par exemple, un champ ou une propriété peut servir à contenir des métadonnées. Dans de tels cas, appliquez XmlIgnoreAttribute au champ ou à la propriété pour que XmlSerializer puisse l'ignorer.

Voir aussi