Classe System.Xml.XmlTextWriter

Cet article vous offre des remarques complémentaires à la documentation de référence pour cette API.

La classe XmlTextWriter implémente la classe XmlWriter.

Remarque

Nous vous recommandons de créer des instances de XmlWriter à l’aide de la méthode XmlWriter.Create et de la classe XmlWriterSettings pour tirer parti de nouvelles fonctionnalités.

XmlTextWriter conserve une pile d'espaces de noms correspondant à tous les espaces de noms définis dans la pile d’éléments actuelle. À l’aide de XmlTextWriter, vous pouvez déclarer des espaces de noms manuellement.

w.WriteStartElement("root");
w.WriteAttributeString("xmlns", "x", null, "urn:1");
w.WriteStartElement("item","urn:1");
w.WriteEndElement();
w.WriteStartElement("item","urn:1");
w.WriteEndElement();
w.WriteEndElement();

Le code C# ci-dessus génère la sortie suivante. XmlTextWriter promeut la déclaration d’espace de noms à l’élément racine pour éviter qu’elle soit dupliquée sur les deux éléments enfants. Les éléments enfants reprennent le préfixe de la déclaration d’espace de noms.

<root xmlns:x="urn:1">
<x:item/>
<x:item/>
</x:root>

XmlTextWriter vous permet également de remplacer la déclaration d’espace de noms actuelle. Dans l’exemple suivant, l’URI d’espace de noms « 123 » est remplacé par « abc » pour produire l’élément XML <x:node xmlns:x="abc"/>.

w.WriteStartElement("x","node","123");
w.WriteAttributeString("xmlns","x",null,"abc");

En utilisant les méthodes d’écriture qui prennent un préfixe comme argument, vous pouvez également spécifier le préfixe à utiliser. Dans l’exemple suivant, deux préfixes différents sont mappés au même URI d’espace de noms pour produire le texte XML <x:root xmlns:x="urn:1"><y:item xmlns:y="urn:1"/></x:root>.

XmlTextWriter w = new XmlTextWriter(Console.Out);
w.WriteStartElement("x","root","urn:1");
w.WriteStartElement("y","item","urn:1");
w.WriteEndElement();
w.WriteEndElement();
w.Close();

S’il existe plusieurs déclarations d’espace de noms mappant différents préfixes vers la même URI d’espace de noms, XmlTextWriter remonte la pile des déclarations d’espace de noms et choisit la plus proche.

XmlTextWriter w = new XmlTextWriter(Console.Out);
w.Formatting = Formatting.Indented;
w.WriteStartElement("x","root","urn:1");
w.WriteStartElement("y","item","urn:1");
w.WriteAttributeString("attr","urn:1","123");
w.WriteEndElement();
w.WriteEndElement();
w.Close();

Dans l’exemple C# ci-dessus, parce que l'appel WriteAttributeString ne spécifie pas de préfixe, l’enregistreur utilise le dernier préfixe envoyé sur la pile d’espaces de noms et produit le code XML suivant :

<x:root xmlns:x="urn:1">
<y:item y:attr="123" xmlns:y="urn:1" />
</x:root>

Si des conflits d’espaces de noms se produisent, XmlTextWriter les résout en générant d’autres préfixes. Par exemple, si un attribut et un élément ont le même préfixe mais des espaces de noms différents, XmlWriter génère un autre préfixe pour l’attribut. Les préfixes générés sont nommés n{i} où i est un nombre commençant à 1. Le nombre est réinitialisé à 1 pour chaque élément.

Les attributs associés à un URI d’espace de noms doivent avoir un préfixe (les espaces de noms par défaut ne s’appliquent pas aux attributs). Cela est conforme à la section 5.2 des espaces de noms W3C dans la recommandation XML. Si un attribut fait référence à un URI d’espace de noms, mais ne spécifie pas de préfixe, l’enregistreur génère un préfixe pour l’attribut.

Lors de l’écriture d’un élément vide, un espace supplémentaire est ajouté entre le nom de la balise et la balise de fermeture, par exemple <item />. Cela assure la compatibilité avec les navigateurs plus anciens.

Lorsqu’un String est utilisé comme paramètre de méthode, null et String.Empty sont équivalents. String.Empty suit les règles W3C.

Pour écrire des données fortement typées, utilisez la classe XmlConvert pour convertir les types de données en chaîne. Par exemple, le code C# suivant convertit les données de Double à String et écrit l’élément <price>19.95</price>.

Double price = 19.95;
writer.WriteElementString("price", XmlConvert.ToString(price));

XmlTextWriter ne vérifie pas les éléments suivants :

• Caractères non valides dans les noms d’attributs et d’éléments.
• Caractères Unicode qui ne correspondent pas à l’encodage spécifié. Si les caractères Unicode ne correspondent pas à l’encodage spécifié, le XmlTextWriter n’échappe pas aux caractères Unicode dans les entités de caractères.
• Attributs dupliqués.
• Caractères dans l’identificateur public DOCTYPE ou l’identificateur système.

Considérations de sécurité

Les éléments suivants sont à prendre en compte lors de l’utilisation de la classe XmlTextWriter.

• Les exceptions levées par leXmlTextWriter 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 correctement.

• Lorsque vous transmettez l'objet XmlTextWriter à une autre application, le flux sous-jacent est exposé à cette application. Si vous devez transmettre XmlTextWriter à une application partiellement fiable, vous devez plutôt utiliser un objet XmlWriter créé par la méthode Create.

• Le XmlTextWriter 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.

• Si les paramètres par défaut sont modifiés, il n'y a aucune garantie que la sortie générée soit une donnée XML bien formée.

• N’acceptez pas les composants de prise en charge, tels qu’un objet Encoding, à partir d’une source non approuvée.