Sérialise et désérialise des objets dans des documents XML ou à partir de documents XML.
La sérialisation XML est le processus qui consiste à convertir des propriétés et champs publics d'un objet dans un format série (dans ce cas, XML) à des fins de stockage et de transport. La désérialisation recrée l'objet dans son état d'origine à partir du résultat XML. La sérialisation peut donc être considérée comme un moyen d'enregistrer l'état d'un objet sous forme de flux ou de mémoire tampon. Par exemple, ASP.NET utilise la classe XmlSerializer pour coder les messages de services Web XML.
Les données de vos objets sont décrites à l'aide des constructions d'un langage de programmation, telles que les classes, les champs, les propriétés, les types primitifs, les tableaux et même du code XML incorporé sous forme d'objets XmlElement ou XmlAttribute. Vous avez le choix entre la création de vos propres classes, annotées d'attributs, et l'utilisation de Outil XML Schema Definition (Xsd.exe) pour générer des classes sur la base d'un document XSD (XML Schema Definition). Si vous disposez d'un schéma XML, vous pouvez exécuter l'outil Xsd.exe pour générer un ensemble de classes fortement typées sur le schéma et annotées d'attributs leur permettant d'adhérer au schéma une fois sérialisées.
Le transfert de données entre les objets et le langage XML requiert une correspondance entre les constructions du langage de programmation et le schéma XML et vice versa. XmlSerializer et des outils connexes, tels que Xsd.exe, proposent une passerelle entre ces deux technologies au moment du design et de l'exécution. Au moment du design, utilisez Xsd.exe pour produire un document de schéma XML (.xsd) à partir de vos classes personnalisées ou pour générer des classes à partir d'un schéma donné. Dans un cas comme dans l'autre, les classes sont annotées à l'aide d'attributs personnalisés qui indiquent à XmlSerializer comment établir une correspondance entre le système de schémas XML et le Common Language Runtime. Au moment de l'exécution, il est possible de sérialiser des instances des classes en documents XML respectant le schéma donné. De la même façon, ces documents XML peuvent être désérialisés en objets d'exécution. (Notez que le schéma XML est facultatif, car il n'est nécessaire ni au moment du design ni au moment de l'exécution.)
Contrôle du XML généré
Pour contrôler le langage XML généré, vous pouvez appliquer des attributs spéciaux aux classes et aux membres. Par exemple, pour spécifier un autre nom d'élément XML, appliquez XmlElementAttribute à un champ public ou à une propriété publique et définissez la propriété ElementName. Pour obtenir la liste complète des attributs similaires, consultez Attributs qui contrôlent la sérialisation XML. Vous pouvez également implémenter l'interface IXmlSerializable pour contrôler la sortie XML.
Si le langage XML généré doit être conforme à la section 5 du document du World Wide Consortium (www.w3.org) intitulé « Simple Object Access Protocol (SOAP) 1.1 », vous devez alors construire XmlSerializer avec XmlTypeMapping. Pour mieux contrôler le langage XML SOAP codé, utilisez les attributs répertoriés dans Attributs qui contrôlent la sérialisation codée en SOAP.
Avec XmlSerializer, vous bénéficiez de l'avantage à utiliser des classes fortement typées tout en conservant la souplesse du langage XML. L'utilisation de champs ou de propriétés de type XmlElement, XmlAttribute ou XmlNode dans vos classes fortement typées vous permet de lire certaines parties du document XML directement dans des objets XML.
Si vous recourrez à des schémas XML extensibles, vous pouvez également utiliser les propriétés XmlAnyElementAttribute et XmlAnyAttributeAttribute pour sérialiser et désérialiser des éléments ou des attributs absents du schéma d'origine. Pour utiliser les objets, appliquez XmlAnyElementAttribute à un champ retournant un tableau d'objets XmlElement ou appliquez XmlAnyAttributeAttribute à un champ retournant un tableau d'objets XmlAttribute.
Si une propriété ou un champ retourne un objet complexe (tel qu'un tableau ou une instance de classe), XmlSerializer le convertit en élément imbriqué dans le document XML principal. Par exemple, la première classe du code ci-dessous retourne une instance de la seconde classe.
Public Class MyClass
Public MyObjectProperty As MyObject
End Class
Public Class MyObject
Public ObjectName As String
End Class
public class MyClass
{
public MyObject MyObjectProperty;
}
public class MyObject
{
public string ObjectName;
}
Voici le résultat XML sérialisé obtenu :
<MyClass>
<MyObjectProperty>
<ObjectName>My String</ObjectName>
</MyObjectProperty>
</MyClass>
Si un schéma comporte un élément facultatif (minOccurs = '0') ou une valeur par défaut, vous disposez de deux options. La première option consiste à utiliser System.ComponentModel.DefaultValueAttribute pour spécifier la valeur par défaut, comme illustré dans l'exemple ci-après.
Public Class PurchaseOrder
<System.ComponentModel.DefaultValueAttribute ("2002")> _
Public Year As String
End Class
public class PurchaseOrder
{
[System.ComponentModel.DefaultValueAttribute ("2002")]
public string Year;
}
La seconde option consiste à utiliser un modèle spécifique pour créer un champ de type Boolean reconnu par XmlSerializer, puis à appliquer XmlIgnoreAttribute à ce champ. Le modèle est créé sous la forme propertyNameSpecified. Par exemple, s'il existe un champ nommé « MyFirstName », vous allez également créer un champ « MyFirstNameSpecified » qui indique à XmlSerializer s'il doit générer un élément XML nommé « MyFirstName ». L'exemple suivant le démontre.
Public Class OptionalOrder
' This field's value should not be serialized
' if it is uninitialized.
Public FirstOrder As String
' Use the XmlIgnoreAttribute to ignore the
' special field named "FirstOrderSpecified".
<System.Xml.Serialization.XmlIgnoreAttribute> _
Public FirstOrderSpecified As Boolean
End Class
public class OptionalOrder
{
// This field should not be serialized
// if it is uninitialized.
public string FirstOrder;
// Use the XmlIgnoreAttribute to ignore the
// special field named "FirstOrderSpecified".
[System.Xml.Serialization.XmlIgnoreAttribute]
public bool FirstOrderSpecified;
}
Substitution de la sérialisation par défaut
Vous pouvez également substituer la sérialisation d'un ensemble d'objets, ainsi que leurs champs et leurs propriétés, en créant un des attributs appropriés, puis en l'ajoutant à une instance de la classe XmlAttributes. Cette méthode de substitution de la sérialisation présente deux intérêts : en premier lieu, vous pouvez contrôler et augmenter la sérialisation d'objets contenus dans une DLL, même si vous n'avez pas accès à la source ; ensuite, vous pouvez créer un seul ensemble de classes sérialisables, mais sérialiser les objets de diverses manières. Pour plus d'informations, consultez la classe XmlAttributeOverrides et Comment : Contrôler la sérialisation de classes dérivées.
Pour sérialiser un objet, appelez la méthode Serialize. Pour désérialiser un objet, appelez la méthode Deserialize.
Pour ajouter des espaces de noms XML à un document XML, consultez XmlSerializerNamespaces.
Remarque |
|---|
| XmlSerializer accorde un traitement spécial aux classes qui implémentent IEnumerable ou ICollection. Une classe implémentant IEnumerable doit implémenter une méthode Add publique ne prenant qu'un paramètre. Le paramètre de la méthode Add doit être du même type que celui du paramètre retourné par la propriété Current sur la valeur retournée par GetEnumerator, ou être une des bases de ce type. Une classe qui implémente ICollection (tel que CollectionBase) en plus de IEnumerable doit avoir une propriété indexée Item publique (indexeur en C#) prenant un entier ainsi qu'une propriété Count publique de type entier (Integer). Le paramètre de la méthode Add doit être du même type que celui retourné par la propriété Item, ou être une des bases de ce type. Dans le cas de classes qui implémentent ICollection, les valeurs à sérialiser sont récupérées de la propriété Item indexée et non par appel à GetEnumerator. |
Vous devez avoir l'autorisation d'écriture sur le répertoire temporaire (comme défini par la variable d'environnement TEMP) pour désérialiser un objet.
Assemblys générés dynamiquement
Pour augmenter les performances, l'infrastructure de sérialisation XML génère dynamiquement des assemblys destinés à sérialiser et désérialiser des types spécifiés. L'infrastructure recherche et réutilise ces assemblys. Ce problème se produit uniquement lors de l'utilisation des constructeurs suivants :
System.Xml.Serialization.XmlSerializer(Type)
System.Xml.Serialization.XmlSerializer(Type,String)
Si vous utilisez un des autres constructeurs, plusieurs versions du même assembly sont générées et ne sont jamais chargées, ce qui résulte en une fuite de mémoire et des performances moindres. La solution la plus simple est d'utiliser l'un des deux constructeurs ci-dessus. Sinon, vous devez mettre en cache les assemblys dans un Hashtable, comme illustré dans l'exemple suivant.
Hashtable serializers = new Hashtable();
// Use the constructor that takes a type and XmlRootAttribute.
XmlSerializer s = new XmlSerializer(typeof(MyClass), myRoot);
// Implement a method named GenerateKey that creates unique keys
// for each instance of the XmlSerializer. The code should take
// into account all parameters passed to the XmlSerializer
// constructor.
object key = GenerateKey(typeof(MyClass), myRoot);
// Check the local cache for a matching serializer.
XmlSerializer ser = (XmlSerializer)serializers[key];
if (ser == null)
{
ser = new XmlSerializer(typeof(MyClass), myRoot);
// Cache the serializer.
serializers[key] = ser;
}
else
{
// Use the serializer to serialize, or deserialize.
}
Dim serializers As New Hashtable()
' Use the constructor that takes a type and XmlRootAttribute.
Dim s As New XmlSerializer(GetType([MyClass]), myRoot)
' Implement a method named GenerateKey that creates unique keys
' for each instance of the XmlSerializer. The code should take
' into account all parameters passed to the XmlSerializer
' constructor.
Dim key As Object = GenerateKey(GetType([MyClass]), myRoot)
' Check the local cache for a matching serializer.
Dim ser As XmlSerializer = CType(serializers(key), XmlSerializer)
If ser Is Nothing Then
ser = New XmlSerializer(GetType([MyClass]), myRoot)
' Cache the serializer.
serializers(key) = ser
Else
' Use the serializer to serialize, or deserialize.
End If
Sérialisation d'ArrayList et de liste générique
XmlSerializer ne peut pas sérialiser ou désérialiser les éléments suivants :
Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile pour Pocket PC, Windows Mobile pour Smartphone, Windows Server 2003, Windows XP Édition Media Center, Windows XP Professionnel Édition x64, Windows XP SP2, Windows XP Starter Edition
Le .NET Framework ne prend pas en charge toutes les versions de chaque plate-forme. Pour obtenir la liste des versions prises en charge, consultez Configuration requise.