Contrôle de la sérialisation XML à l'aide d'attributsControlling XML Serialization Using Attributes

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.Attributes can be used to control the XML serialization of an object or to create an alternate XML stream from the same set of classes. Pour plus d’informations sur la création d’un flux de données XML différent, consultez Guide pratique pour spécifier un nom d’élément différent pour un flux XML.For more details about creating an alternate XML stream, see How to: Specify an Alternate Element Name for an XML Stream.

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 listés dans attributs qui contrôlent la sérialisation encodéeselon le protocole SOAP.If the XML generated must conform to section 5 of the World Wide Web Consortium (W3C) document titled Simple Object Access Protocol (SOAP) 1.1, use the attributes listed in Attributes That Control Encoded SOAP Serialization.

Par défaut, un nom d'élément XML est déterminé par le nom de la classe ou du membre.By default, an XML element name is determined by the class or member name. 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.In a simple class named Book, a field named ISBN will produce an XML element tag <ISBN>, as shown in the following example.

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.This default behavior can be changed if you want to give the element a new name. Le code suivant affiche la manière dont un attribut active cette option en définissant la propriété ElementName d'un XmlElementAttribute.The following code shows how an attribute enables this by setting the ElementName property of a 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.For more information about attributes, see 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.For a list of attributes that control XML serialization, see Attributes That Control XML Serialization.

Contrôle de la sérialisation de tableauControlling Array Serialization

Les attributs XmlArrayAttribute et XmlArrayItemAttribute sont conçus pour contrôler la sérialisation de tableaux.The XmlArrayAttribute and the XmlArrayItemAttribute attributes are designed to control the serialization of arrays. À 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 »).Using these attributes, you can control the element name, namespace, and XML Schema (XSD) data type (as defined in the World Wide Web Consortium [www.w3.org] document titled "XML Schema Part 2: Datatypes"). Vous pouvez également spécifier les types qui peuvent être inclus dans un tableau.You can also specify the types that can be included in an array.

XmlArrayAttribute détermine les propriétés de l'élément XML englobant obtenu lorsqu'un tableau est sérialisé.The XmlArrayAttribute will determine the properties of the enclosing XML element that results when an array is serialized. Par exemple, la sérialisation du tableau suivant génère par défaut un élément XML nommé Employees.For example, by default, serializing the array below will result in an XML element named Employees. L'élément Employees contient une série d'éléments nommée d'après le type de tableau Employee.The Employees element will contain a series of elements named after the array type 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.A serialized instance might resemble the following.

<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.By applying a XmlArrayAttribute, you can change the name of the XML element, as follows.

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.The resulting XML might resemble the following.

<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.The XmlArrayItemAttribute, on the other hand, controls how the items contained in the array are serialized. Notez que l'attribut est appliqué au champ retournant le tableau.Note that the attribute is applied to the field returning the array.

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.The resulting XML might resemble the following.

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

Sérialisation de classes dérivéesSerializing Derived Classes

XmlArrayItemAttribute permet également de sérialiser des classes dérivées.Another use of the XmlArrayItemAttribute is to allow the serialization of derived classes. Par exemple, une autre classe nommée Manager, dérivée de Employee, peut être ajoutée à l'exemple précédent.For example, another class named Manager that derives from Employee can be added to the previous example. 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.If you do not apply the XmlArrayItemAttribute, the code will fail at run time because the derived class type will not be recognized. 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é).To remedy this, apply the attribute twice, each time setting the Type property for each acceptable type (base and derived).

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.A serialized instance might resemble the following.

<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émentsSerializing an Array as a Sequence of Elements

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.You can also serialize an array as a flat sequence of XML elements by applying a XmlElementAttribute to the field returning the array as follows.

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.A serialized instance might resemble the following.

<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é.Another way to differentiate the two XML streams is to use the XML Schema Definition tool to generate the XML Schema (XSD) document files from the compiled code. (Pour plus d’informations sur l’utilisation de l’outil, consultez l’outil XML Schema Definition et SÉRIALISATION XML.) Quand aucun attribut n’est appliqué au champ, le schéma décrit l’élément de la manière suivante.(For more details on using the tool, see The XML Schema Definition Tool and XML Serialization.) When no attribute is applied to the field, the schema describes the element in the following manner.

<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.When the XmlElementAttribute is applied to the field, the resulting schema describes the element as follows.

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

Sérialisation d'un ArrayListSerializing an ArrayList

La classe ArrayList peut contenir une collection d'objets divers.The ArrayList class can contain a collection of diverse objects. Par conséquent, vous pouvez utiliser un ArrayList plus souvent qu'un tableau.You can therefore use a ArrayList much as you use an array. 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.Instead of creating a field that returns an array of typed objects, however, you can create a field that returns a single ArrayList. Toutefois, comme avec les tableaux, vous devez indiquer à XmlSerializer les types d'objets que contient l'ArrayList.However, as with arrays, you must inform the XmlSerializer of the types of objects the ArrayList contains. Pour ce faire, assignez plusieurs instances de XmlElementAttribute à ce champ, comme illustré dans l'exemple suivant.To accomplish this, assign multiple instances of the XmlElementAttribute to the field, as shown in the following example.

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 XmlTypeAttributeControlling Serialization of Classes Using XmlRootAttribute and XmlTypeAttribute

Il est possible d'appliquer deux attributs à une seule et même classe : XmlRootAttribute et XmlTypeAttribute.There are two attributes that can be applied to a class (and only a class): XmlRootAttribute and XmlTypeAttribute. Ces attributs sont très semblables.These attributes are very similar. 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.The XmlRootAttribute can be applied to only one class: the class that, when serialized, represents the XML document's opening and closing element—in other words, the root element. En revanche, XmlTypeAttribute peut être appliqué à n'importe quelle classe, y compris la classe racine.The XmlTypeAttribute, on the other hand, can be applied to any class, including the root class.

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.For example, in the previous examples, the Group class is the root class, and all its public fields and properties become the XML elements found in the XML document. Par conséquent, il ne peut y avoir qu'une seule classe racine.Therefore, there can be only one root class. En appliquant XmlRootAttribute, vous pouvez contrôler le flux de données XML généré par XmlSerializer.By applying the XmlRootAttribute, you can control the XML stream generated by the XmlSerializer. Par exemple, vous pouvez modifier le nom de l'élément et l'espace de noms.For example, you can change the element name and namespace.

XmlTypeAttribute vous permet de contrôler le schéma du code XML généré.The XmlTypeAttribute allows you to control the schema of the generated XML. Cette fonction est utile lorsque vous devez publier le schéma via un service Web XML.This capability is useful when you need to publish the schema through an XML Web service. L'exemple suivant applique XmlTypeAttribute et XmlRootAttribute à la même classe.The following example applies both the XmlTypeAttribute and the XmlRootAttribute to the same class.

<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.If this class is compiled, and the XML Schema Definition tool is used to generate its schema, you would find the following XML describing 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.In contrast, if you were to serialize an instance of the class, only NewGroupName would be found in the XML document.

<NewGroupName>
    . . .
</NewGroupName>

Empêcher la sérialisation avec XmlIgnoreAttributePreventing Serialization with the XmlIgnoreAttribute

Dans certains cas, une propriété ou un champ public ne doit pas être sérialisé.There might be situations when a public property or field does not need to be serialized. Par exemple, un champ ou une propriété peut servir à contenir des métadonnées.For example, a field or property could be used to contain metadata. Dans de tels cas, appliquez XmlIgnoreAttribute au champ ou à la propriété pour que XmlSerializer puisse l'ignorer.In such cases, apply the XmlIgnoreAttribute to the field or property and the XmlSerializer will skip over it.

Voir aussiSee also