Contrôle de la sérialisation XML à l'aide d'attributs

Les attributs peuvent être utilisés pour contrôler la sérialisation XML d'un objet ou pour créer un autre flux XML à partir d'un même ensemble de classes. Pour plus d'informations sur la création d'un autre flux XML, voir Comment : Spécifier un autre nom d'élément pour un flux XML.

Notes

Si le code XML généré doit se conformer à la section 5 du document du World Wide Web Consortium (www.w3.org) intitulé "Simple Object Access Protocol (SOAP) 1.1" (en anglais), utilisez les attributs répertoriés dans Attributs qui contrôlent la sérialisation codée en 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 produit une balise d'élément XML <ISBN>, comme le montre 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 attribuer un nouveau nom à l'élément. Le code suivant montre comment un attribut offre cette possibilité en définissant la propriété ElementName de 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, voir Extending Metadata Using Attributes. Pour obtenir la liste des attributs qui contrôlent la sérialisation XML, voir Attributs qui contrôlent la sérialisation XML.

Contrôle de la sérialisation des tableaux

Les attributs XmlArrayAttribute et XmlArrayItemAttribute sont conçus pour contrôler la sérialisation des tableaux. À l'aide de ces attributs, vous pouvez contrôler le nom d'élément, l'espace de noms et le Schéma XML (type de données XSD) (selon la définition du document en anglais du World Wide Web Consortium [www.w3.org] intitulé "XML Schema Part 2: Datatypes"). Vous pouvez également spécifier les types qui peuvent être inclus dans un tableau.

L'attribut XmlArrayAttribute détermine les propriétés de l'élément XML englobant qui résulte de la sérialisation d'un tableau. Par exemple, par défaut, la sérialisation du tableau ci-dessous donne un élément XML nommé Employees. L'élément Employees contient une série d'éléments nommés à partir du type 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 ressembler à ce qui suit.

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

En appliquant XmlArrayAttribute, vous pouvez changer 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 résultant peut ressembler à ce qui suit.

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

Par contre, XmlArrayItemAttribute contrôle la manière dont les éléments contenus dans le tableau sont sérialisés. Notez que l'attribut est appliqué au champ qui retourne le tableau.

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

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

Le code XML résultant peut ressembler à ce qui suit.

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

Sérialisation des classes dérivées

XmlArrayItemAttribute permet aussi 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 échouera au moment de l'exécution car le type de classe dérivée ne sera pas reconnu. Pour corriger ce problème, appliquez deux fois l'attribut, en définissant à chaque fois la propriété Type pour chaque type acceptable (classe de base et dérivée).

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 ressembler à ce qui 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 la forme d'une séquence d'éléments

Vous pouvez également sérialiser un tableau sous la forme d'une séquence à deux dimensions (flat) d'éléments XML en appliquant XmlElementAttribute au champ qui retourne le champ comme suit.

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

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

Une instance sérialisée peut ressembler à ce qui suit.

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

Une autre façon de différencier les deux flux XML consiste à utiliser l'outil XML Schema Definition pour générer les fichiers document XSD à partir du code compilé. (Pour plus d'informations sur l'utilisation de l'outil, voir L'outil XML Schema Definition et la 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 XmlElementAttribute est appliqué au champ, le schéma résultant décrit l'élément de la manière suivante.

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

Sérialisation d'une ArrayList

La classe ArrayList peut contenir une collection d'objets divers. Vous pouvez donc utiliser ArrayList de la même manière qu'un tableau. Au lieu de créer un champ qui retourne un tableau d'objets typés, vous pouvez créer un champ qui retourne un seul ArrayList. Cependant, comme avec tous les tableaux, vous devez préciser à XmlSerializer les types d'objets contenus dans ArrayList. Pour ce faire, assignez plusieurs instances de XmlElementAttribute au champ, comme le montre 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 des classes à l'aide de XmlRootAttribute et XmlTypeAttribute

Deux attributs peuvent s'appliquer à une classe (et uniquement à une classe) : XmlRootAttribute et XmlTypeAttribute. Ces attributs sont très similaires. Le XmlRootAttribute ne peut s'appliquer qu'à une seule classe : la classe qui, lorsqu'elle est sérialisée, représente l'élément d'ouverture et de fermeture du document XML ; en d'autres termes, l'élément racine. En revanche,XmlTypeAttribute peut être appliqué à n'importe quelle classe, y compris la classe racine.

Par exemple, dans les exemples précédents, la classe Group est la classe racine, et tous ses champs et propriétés publics deviennent les éléments XML trouvés dans le document XML. Il ne peut y avoir par conséquent qu'une seule classe racine. En appliquant XmlRootAttribute, vous pouvez contrôler le flux XML généré par XmlSerializer. Par exemple, vous pouvez changer le nom d'élément et l'espace de noms.

XmlTypeAttribute vous permet de contrôler le schéma du code XML généré. Cette capacité est utile lorsque vous avez besoin de 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 compilée et que l'outil XML Schema Definition est utilisé pour générer son schéma, vous trouverez le code XML suivant décrivant Group.

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

Par contre, si vous étiez amené à sérialiser une instance de la classe, seul NewGroupName serait trouvé dans le document XML.

<NewGroupName>
    . . .
</NewGroupName>

Empêcher la sérialisation à l'aide de XmlIgnoreAttribute

Vous rencontrerez peut-être des situations où la sérialisation d'une propriété ou d'un champ public n'est pas nécessaire. Par exemple, un champ ou une propriété peut être utilisé pour contenir des métadonnées. Dans ces cas-là, appliquez XmlIgnoreAttribute au champ ou à la propriété et XmlSerializer l'ignorera.

Voir aussi

Tâches

Comment : Spécifier un autre nom d'élément pour un flux XML
Comment : Sérialiser un objet
Comment : Désérialiser un objet

Concepts

Attributs qui contrôlent la sérialisation XML
Attributs qui contrôlent la sérialisation codée en SOAP
Introduction à la sérialisation XML
Exemples de sérialisation XML