Classe System.Xml.XmlWriter
La classe XmlWriter écrit des données XML dans un flux, un lecteur de texte ou une chaîne. Elle est conforme aux recommandations W3C Extensible Markup Language (XML) 1.0 (quatrième édition) et Espaces de noms dans XML 1.0 (troisième édition).
Les membres de la classe XmlWriter vous permettent de :
- vérifier que les caractères sont des caractères XML reconnus et que les noms d'éléments et d'attributs sont des noms XML valides ;
- vérifier que le document XML est correctement construit ;
- Encoder les octets binaires en Base64 ou BinHex, et écrire le texte résultant.
- Passer des valeurs en utilisant des types du Common Language Runtime au lieu de chaînes, pour éviter de devoir effectuer manuellement des conversions de valeurs.
- écrire plusieurs documents dans un même flux de sortie ;
- écrire des noms, des noms qualifiés et des jetons de nom valides.
Créer un enregistreur XML
Pour créer une instance de XmlWriter, utilisez la méthode XmlWriter.Create. Pour spécifier l’ensemble de fonctionnalités que vous souhaitez activer sur l’enregistreur XML, passez un objet XmlWriterSettings à la méthode Create. Sinon, les paramètres par défaut sont utilisés. Pour plus d’informations, consultez les pages des informations de référence sur Create.
Spécifier le format de sortie
La classe XmlWriterSettings comprend plusieurs propriétés qui contrôlent la mise en forme de la sortie de XmlWriter :
| Propriété | Description |
|---|---|
| Encoding | Spécifie l'encodage de texte à utiliser. Par défaut, il s’agit de Encoding.UTF8. |
| Indent | Indique si des éléments doivent être mis en retrait. La valeur par défaut est false (pas de mise en retrait). |
| IndentChars | Spécifie la chaîne de caractères à utiliser pour la mise en retrait. Par défaut, il s'agit de deux espaces. |
| NewLineChars | Spécifie la chaîne de caractères à utiliser pour les sauts de ligne. La valeur par défaut est \r\n (retour chariot, saut de ligne) pour les plateformes non-Unix et \n (saut de ligne) pour les plateformes Unix. |
| NewLineHandling | Spécifie la manière de traiter les caractères de nouvelle ligne. |
| NewLineOnAttributes | Indique si des attributs doivent être écrits sur une nouvelle ligne. Indent doit être défini sur true quand vous utilisez cette propriété. Par défaut, il s’agit de false. |
| OmitXmlDeclaration | Indique si une déclaration XML doit être écrite. Par défaut, il s’agit de false. |
Les propriétés Indent et IndentChars contrôlent la taille minime de l'espace blanc formaté. Par exemple, pour mettre en retrait les nœuds d’élément :
XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);
Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.IndentChars = vbTab
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)
Utilisez NewLineOnAttributes pour écrire chaque attribut sur une nouvelle ligne avec un niveau supplémentaire de mise en retrait :
XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);
Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.NewLineOnAttributes = True
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)
Conformité des données
Un enregistreur XML utilise deux propriétés de la classe XmlWriterSettings pour vérifier la conformité des données :
La propriété CheckCharacters indique à l’enregistreur XML de vérifier les caractères et de lever une exception XmlException si des caractères se trouvent en dehors de la plage autorisée, telle qu’elle est définie par le W3C.
La propriété ConformanceLevel configure l’enregistreur XML pour vérifier que le flux à écrire est conforme aux règles pour un document ou un fragment de document XML 1.0 bien formé, tel que défini par le W3C. Les trois niveaux de conformité sont décrits dans le tableau suivant. Par défaut, il s’agit de Document. Pour plus d’informations, consultez la propriété XmlWriterSettings.ConformanceLevel et l’énumération System.Xml.ConformanceLevel.
Level Description Document La sortie XML est conforme aux règles pour un document XML 1.0 bien formé et peut être traitée par n’importe quel processeur conforme. Fragment La sortie XML est conforme aux règles pour un fragment de document XML 1.0 bien formé. Auto L’enregistreur XML détermine le niveau de vérification de la conformité à appliquer (à un document ou un fragment) en fonction des données entrantes.
Écrire des éléments
Vous pouvez utiliser les méthodes suivantes XmlWriter pour écrire des nœuds d’élément. Pour obtenir des exemples, consultez les méthodes listées.
| Utilisation | À |
|---|---|
| WriteElementString | Écrivez un nœud d’élément entier, incluant une valeur de chaîne. |
| WriteStartElement | Pour écrire une valeur d’élément en utilisant plusieurs appels de méthode. Par exemple, vous pouvez appeler WriteValue pour écrire une valeur typée, WriteCharEntity pour écrire une entité de caractères, WriteAttributeString pour écrire un attribut ou vous pouvez écrire un élément enfant. C’est une version plus sophistiquée de la méthode WriteElementString. Pour fermer l’élément, vous appelez la méthode WriteEndElement ou WriteFullEndElement. |
| WriteNode | Pour copier un nœud d’élément trouvé à la position actuelle d’un objet XmlReader ou XPathNavigator. Lorsqu'elle est appelée, elle copie tout l'objet source vers l'instance de l'objet XmlWriter. |
Écrire les attributs
Vous pouvez utiliser les méthodes XmlWriter suivantes pour écrire des attributs sur des nœuds d’élément. Ces méthodes peuvent également être utilisées pour créer des déclarations d’espace de noms sur un élément, comme indiqué dans la section suivante.
| Utilisation | À |
|---|---|
| WriteAttributeString | Pour écrire un nœud d’attribut entier, incluant une valeur de chaîne. |
| WriteStartAttribute | Pour écrire la valeur d’une attribut en utilisant plusieurs appels de méthode. Par exemple, vous pouvez appeler WriteValue pour écrire une valeur typée. C’est une version plus sophistiquée de la méthode WriteElementString. Pour fermer l’élément, vous appelez la méthode WriteEndAttribute. |
| WriteAttributes | Pour copier tous les attributs trouvés à la position actuelle d’un objet XmlReader. Les attributs qui sont écrits dépendent du type de nœud sur lequel le lecteur est actuellement positionné : – Pour un nœud d’attribut, il écrit l’attribut actuel, puis le reste des attributs jusqu’à la balise de fermeture de l’élément. – Pour un nœud d’élément, il écrit tous les attributs que contient l’élément. – Pour un nœud de déclaration XML, il écrit tous les attributs de la déclaration. – Pour tous les autres types de nœud, la méthode lève une exception. |
Gérer les espaces de noms
Les espaces de noms sont utilisés pour qualifier des noms d'attributs et d'éléments dans un document XML. Les préfixes d’espace de noms associent des éléments et des attributs à des espaces de noms, qui sont à leur tour associés à des références d’URI. Les espaces de noms garantissent l'unicité des noms d'attributs et d'éléments dans un document XML.
XmlWriter gère une pile d’espaces de noms correspondant à tous les espaces de noms définis dans l’étendue actuelle. Lors de l'écriture des éléments et attributs, vous pouvez utiliser les espaces de noms comme suit :
Déclarez manuellement des espaces de noms en utilisant la méthode WriteAttributeString. Cela peut s'avérer utile si vous savez comment optimiser le nombre de déclarations d'espaces de noms. Pour un exemple, consultez la méthode WriteAttributeString(String, String, String, String).
substituer la déclaration d'un nouvel espace de noms à celle de l'espace de noms en cours ; Dans le code suivant, la méthode WriteAttributeString change l’URI d’espace de noms pour le préfixe
"x"de"123"en"abc".writer.WriteStartElement("x", "root", "123"); writer.WriteStartElement("item"); writer.WriteAttributeString("xmlns", "x", null, "abc"); writer.WriteEndElement(); writer.WriteEndElement();writer.WriteStartElement("x", "root", "123") writer.WriteStartElement("item") writer.WriteAttributeString("xmlns", "x", Nothing, "abc") writer.WriteEndElement() writer.WriteEndElement()Le code génère la chaîne XML suivante :
<x:root xmlns:x="123"> <item xmlns:x="abc" /> </x:root>spécifier un préfixe d'espace de noms lors de l'écriture des attributs ou éléments. La plupart des méthodes utilisées pour écrire un élément et des attributs vous permettent de faire cela. Par exemple, la méthode WriteStartElement(String, String, String) écrit une balise de début et l’associe à un espace de noms et un préfixe spécifiés.
Écrire des données typées
La méthode WriteValue accepte un objet CLR (Common Language Runtime), convertit la valeur d’entrée en sa représentation sous forme de chaîne en fonction des règles de conversion de type de données XSD (XML Schema Definition Language) et les écrit en utilisant la méthode WriteString. Ceci est plus facile que d’utiliser les méthodes de la classe XmlConvert pour convertir les données typées en une valeur de chaîne avant de l’écrire.
Lors de l’écriture en texte, la valeur typée est sérialisée en texte en utilisant les règles de XmlConvert pour ce type de schéma.
Pour connaître les types de données XSD par défaut qui correspondent aux types CLR, consultez la méthode WriteValue.
XmlWriter peut aussi écrire dans un magasin de données XML. Par exemple, la classe XPathNavigator peut créer un objet XmlWriter pour créer des nœuds pour un objet XmlDocument. Si des informations de schéma sont disponibles pour un magasin de données, la méthode WriteValue lève une exception si vous tentez de convertir en un type qui n’est pas autorisé. Si aucune information de schéma n’est disponible pour un magasin de données, la méthode WriteValue traite toutes les valeurs comme un type xsd:anySimpleType.
Fermer l’enregistreur XML
Quand vous utilisez des méthodes XmlWriter pour générer du code XML, les éléments et les attributs ne sont pas écrits tant que vous n’appelez pas la méthode Close. Par exemple, si vous utilisez XmlWriter pour remplir un objet XmlDocument, vous ne pourrez pas voir les éléments et les attributs écrits dans le document cible tant que vous n’avez pas fermé l’instance de XmlWriter.
Programmation asynchrone
La plupart des méthodes XmlWriter ont des équivalents asynchrones qui ont « Async » à la fin du nom de leurs méthodes. Par exemple, l’équivalent asynchrone de WriteAttributeString est WriteAttributeStringAsync.
Pour la méthode WriteValue, qui n’a pas d’équivalent asynchrone, convertissez la valeur de retour en chaîne et utilisez à la place la méthode WriteStringAsync.
Considérations de sécurité
Tenez compte des éléments suivants lors de l’utilisation de la classe XmlWriter :
Les exceptions levées par XmlWriter peuvent divulguer des informations de chemin d’accès que vous ne voulez pas voir apparaître dans l’application. Vos applications doivent intercepter les exceptions et les traiter de façon appropriée.
XmlWriter ne valide aucune des donnée passées à la méthode WriteDocType ou WriteRaw. Vous ne devez pas passer de données arbitraires à ces méthodes.
