Partager via

Classe System.Xml.XmlTextWriter

Cet article fournit des remarques supplémentaires à la documentation de référence de cette API.

La XmlTextWriter classe implémente la XmlWriter classe.

Remarque

Nous vous recommandons de créer XmlWriter instances en utilisant la méthode XmlWriter.Create et la classe XmlWriterSettings pour tirer parti de nouvelles fonctionnalités.

XmlTextWriter gère une pile d’espaces de noms correspondant à tous les espaces de noms définis dans la pile d’éléments actuelle. Vous pouvez déclarer manuellement des espaces de noms avec XmlTextWriter.

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 vers l’élément racine afin d’éviter sa duplication sur les deux éléments enfants. Les éléments enfants récupèrent 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 <x:node xmlns:x="abc"/>XML .

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 <x:root xmlns:x="urn:1"><y:item xmlns:y="urn:1"/></x:root>XML.

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 à la même URI d’espace de noms, XmlTextWriter guide la pile des déclarations d’espace de noms vers l’arrière 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();

Comme l’appel WriteAttributeString ne spécifie pas de préfixe dans l’exemple C# ci-dessus, l'écrivain utilise le dernier préfixe poussé 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 des préfixes alternatifs. Par exemple, si un attribut et un élément ont le même préfixe, mais que différents espaces de noms, 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 par 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 fermante, 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 XmlConvert classe pour convertir les types de données en chaîne. Par exemple, le code C# suivant convertit les données en DoubleString 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 ne transforme pas les caractères Unicode en entités de caractères.
  • Attributs dupliqués.
  • Caractères dans l’identificateur public DOCTYPE ou l’identificateur système.

Considérations relatives à la sécurité

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

  • Les exceptions levées par XmlTextWriter peuvent divulguer des informations sur le chemin que vous ne souhaitez pas faire remonter à l'application. Vos applications doivent intercepter les exceptions et les traiter de manière appropriée.

  • Lorsque vous passez l’application 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.

  • XmlTextWriter ne valide pas les données transmises aux méthodes WriteDocType ou WriteRaw. Vous ne devez pas transmettre de données arbitraires à ces méthodes.

  • Si les paramètres par défaut sont modifiés, il n’existe aucune garantie que la sortie générée est des données XML bien formées.

  • N’acceptez pas les composants de support, tels qu’un objet Encoding, d’une source non approuvée.