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 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 Comment : spécifier un nom d'élément différent pour un flux XML.

Remarque :
Si le code XML généré doit se conformer à la section 5 du document World Wide Web Consortium (www.w3.org) intitulé « Simple Object Access Protocol (SOAP) 1.1 », utilisez les attributs répertoriés dans Attributs qui contrôlent 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 affiche la manière dont un attribut active cette option 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 Extending Metadata Using Attributes. 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 type de données de nom d'élément, d'espace de noms et de schéma XML (XSD) (comme défini dans le document 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.

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>

En revanche, 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 retournant 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 car le type de classe dérivée ne sera pas reconnu. Pour résoudre ce problème, appliquez l'attribut deux fois, en définissant à chaque fois la propriété Type pour chaque type acceptable (type de 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 retournant 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 Schema Definition 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 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

Il est possible d'appliquer deux attributs à une seule et même classe : XmlRootAttribute et XmlTypeAttribute. Ces attributs sont très semblables. 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 ne peut y avoir qu'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 compilée et que l'outil XML Schema Definition 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

Dans certains cas, 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

Tâches

Comment : spécifier un nom d'élément différent 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 encodée selon le protocole SOAP
Introduction à la sérialisation XML
Exemples de sérialisation XML