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

Article
04/11/2008

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, consultez Substitution de la sérialisation XML.

**Remarque **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>.
[C#]
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 changé si vous voulez donner un nouveau nom à l'élément. Le code suivant montre comment un attribut offre cette possibilité en définissant la propriété ElementName d'un attribut XmlElementAttribute.

Public Class TaxRates
   < XmlElement(ElementName = "TaxRate")> _
    Public ReturnTaxRate As Decimal
End Class
[C#]
public class TaxRates{
    [XmlElement(ElementName = "TaxRate")]
    public decimal ReturnTaxRate;
}

Pour plus d'informations sur les attributs, consultez Extension des métadonnées à l'aide des attributs. Pour obtenir une liste d'attributs qui contrôlent la sérialisation XML, consultez Attributs qui contrôlent la sérialisation.

Pour contrôler la sérialisation à l'aide des attributs

Appliquez un des attributs spéciaux au membre de la classe ou à la classe. Pour obtenir une liste des attributs qui contrôlent spécifiquement la sérialisation, consultez Attributs qui contrôlent la sérialisation.
Modifiez le membre de la classe, si nécessaire. Par exemple, changez le nom d'un membre, mais attribuez une valeur appropriée à la propriété ElementName - c'est-à-dire une valeur conforme au schéma XML (XSD) de l'objet sérialisé.
Sérialisez ou désérialisez l'instance de classe.

Le flux XML résultant se conformera au schéma, mais la classe aura un nom de méthode explicite.

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 engendre 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
[C#]
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 un attribut XmlArrayAttribute, vous pouvez changer le nom de l'élément XML comme suit.

Public Class Group
    <XmlArray("TeamMembers")> _
    Public Employees() As Employee
End Class
[C#]
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, l'attribut XmlArrayItemAttribute contrôle la manière dont les éléments contenus dans le tableau sont sérialisés. Remarquez dans l'exemple suivant que l'attribut est appliqué au champ qui retourne le tableau.

Public Class Group
    <XmlArray("MemberName")> _
    Public Employee() As Employees
End Class
[C#]
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

Une autre utilisation de l'attribut XmlArrayItemAttribute est de permettre la sérialisation 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 l'attribut XmlArrayItemAttribute, le code échouera au moment de l'exécution car le type classe dérivé ne sera pas reconnu. Pour corriger ce problème, appliquez deux fois l'attribut, en définissant à chaque fois la propriété XmlArrayItemAttribute.Type pour chaque type acceptable (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
[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;
}

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 un attribut XmlElementAttribute au champ qui retourne le champ comme suit.

Public Class Group
    <XmlElement> _
    Public Employees() As Employee
End Class
[C#]
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érentier les deux flux XML consiste à utiliser l'outil XML Schema Definition Tool pour générer les fichiers document XSD à partir du code compilé. (Pour plus d'informations sur l'utilisation de l'outil, consultez L'outil XML Schema Definition Tool 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 l'attribut 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 une classe ArrayList de la même manière qu'un tableau. Plutôt que de créer un champ qui retourne un tableau d'objets typés, vous pouvez créer un champ qui retourne une seule classe ArrayList. Cependant, comme avec tous les tableaux, vous devez préciser à XmlSerializer les types d'objets contenus dans ArrayList. Pour réaliser cela, assignez de multiples 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
[C#]
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

Il existe deux attributs qui peuvent être appliqués à une classe (et seulement une classe) : XmlRootAttribute et XmlTypeAttribute. Ces attributs sont très similaires. L'attribut XmlRootAttribute peut être appliqué à une seule classe uniquement : la classe qui, lorsqu'elle est sérialisée, représente l'élément d'ouverture et de fermeture du document XML - en autres termes, l'élément « racine ». En revanche, l'attribut 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 l'attribut 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.

L'attribut 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
[C#]
[XmlRoot("NewGroupName")]
[XmlType("NewTypeName")]
public class Group{
    public Employee[] Employees;
}

Si cette classe est compilée, et l'outil XML Schema Definition Tool est utilisé pour générer son schéma, vous trouveriez 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ée pour contenir des métadonnées. Dans ces cas-là, appliquez l'attribut XmlIgnoreAttribute au champ ou à la propriété et XmlSerializer l'ignorera.

Voir aussi

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 | Substitution de la sérialisation XML

Partager via

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

Contrôle de la sérialisation des tableaux

Sérialisation des classes dérivées

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

Sérialisation d'une ArrayList

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

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

Voir aussi

Ressources supplémentaires