Contrôler la sérialisation XML avec des 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 du même ensemble de classes. Pour plus d’informations sur la création d’un autre flux XML, consultez Guide pratique pour spécifier un autre nom d’élément pour un flux XML.

Par défaut, un nom d’élément XML est déterminé par le nom de la classe ou du membre. Dans une classe nommée Book, un champ nommé ISBN produit une balise <ISBN>d’élément XML, 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>.

Le comportement par défaut peut être modifié si vous souhaitez donner à l’élément un nouveau nom. Le code suivant montre comment un attribut active cette fonctionnalité en définissant la ElementName propriété 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 la liste 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 tableaux

Les XmlArrayAttribute attributs et les XmlArrayItemAttribute attributs contrôlent la sérialisation des tableaux. À l’aide de ces attributs, vous pouvez contrôler le type de données XSD (nom d’élément, espace de noms et schéma XML) tel que défini dans le document W3C intitulé Xml Schema Part 2 : Datatypes. Vous pouvez également spécifier les types qui peuvent être inclus dans un tableau.

XmlArrayAttribute déterminera les propriétés de l’élément XML englobant qui résulte lorsque un tableau est sérialisé. Par exemple, par défaut, la sérialisation du tableau ci-dessous entraîne un élément XML nommé Employees. L’élément Employees contient une série d’éléments nommés après le type Employeede tableau.

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 au code suivant :

<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 ressembler au code suivant :

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

D'autre XmlArrayItemAttribute part, il contrôle la façon dont les éléments contenus dans le tableau sont sérialisés.

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

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

Le code XML obtenu peut ressembler au code suivant :

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

Sérialisation des classes dérivées

Une autre utilisation du XmlArrayItemAttribute est d’autoriser la sérialisation des classes dérivées. Par exemple, une autre classe nommée Manager qui dérive de Employee peut être ajoutée à l’exemple précédent. Si vous n’appliquez pas le XmlArrayItemAttributecode, le code échoue au moment de l’exécution, car le type de classe dérivé n’est pas reconnu. Pour remédier à ce résultat, appliquez l’attribut deux fois, chaque fois que vous définissez la Type propriété 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

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 au code suivant :

<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 en tant que séquence d’éléments

Vous pouvez également sérialiser un tableau en tant que séquence plate d’éléments XML en appliquant un XmlElementAttribute au champ retournant le tableau 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 au code suivant :

<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 De définition de schéma XML pour générer les fichiers de documents XML Schema (XSD) à partir du code compilé. Pour plus d’informations sur l’utilisation de l’outil, consultez l’outil De définition de schéma XML 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 le XmlElementAttribute est appliqué au champ, le schéma résultant décrit l’élément comme suit :

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

Sérialisation d'une ArrayList

La ArrayList classe peut contenir une collection d’objets variés. Vous pouvez donc utiliser un ArrayList comme vous utilisez un tableau. Au lieu de créer un champ qui retourne un tableau d’objets typés, toutefois, vous pouvez créer un champ qui retourne un seul ArrayList. Toutefois, comme avec les tableaux, vous devez indiquer à XmlSerializer les types d'objets que ArrayList contient. Pour ce faire, affectez plusieurs instances du XmlElementAttribute 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 des classes à l’aide de XmlRootAttribute et XmlTypeAttribute

Vous pouvez appliquer deux attributs à une classe uniquement : XmlRootAttribute et XmlTypeAttribute. Ces attributs sont similaires. Il XmlRootAttribute ne peut être appliqué 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 Group classe est la classe racine, et tous ses champs et propriétés publics deviennent les éléments XML trouvés dans le document XML. Par conséquent, vous ne pouvez avoir qu’une seule classe racine. En appliquant le XmlRootAttribute, vous pouvez contrôler le flux XML généré par le XmlSerializer. Par exemple, vous pouvez modifier le nom et l’espace de noms de l’élément.

Le XmlTypeAttribute vous permet de contrôler le schéma du XML généré. Cette fonctionnalité est utile lorsque vous devez publier le schéma via un service web XML. L'exemple suivant applique les 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" />

En revanche, si vous deviez sérialiser une instance de la classe, seul NewGroupName se trouverait dans le document XML.

<NewGroupName>
    . . .
</NewGroupName>

Prévention de la sérialisation avec XmlIgnoreAttribute

Vous pouvez rencontrer une situation où une propriété publique ou un champ n’a pas besoin d’être sérialisé. Par exemple, un champ ou une propriété peut être utilisé pour contenir des métadonnées. Dans ces cas, appliquez la XmlIgnoreAttribute au champ ou à la propriété et le XmlSerializer l’ignorera.

Voir aussi

• Attributs qui contrôlent la sérialisation XML
• Attributs qui contrôlent la sérialisation SOAP encodée
• Présentation de la sérialisation XML
• Exemples de sérialisation XML
• Guide pratique pour spécifier un autre nom d’élément pour un flux XML
• Guide pratique pour sérialiser un objet
• Guide pratique pour désérialiser un objet