Classe System.Xml.XmlWriter

2025-06-22

La XmlWriter classe écrit des données XML dans un flux, un fichier, un lecteur de texte ou une chaîne. Il prend en charge les recommandations W3C Extensible Markup Language (XML) 1.0 (quatrième édition) et espaces de noms dans les recommandations XML 1.0 (troisième édition).

Les membres de la XmlWriter classe vous permettent de :

Vérifiez que les caractères sont des caractères XML légaux et que les noms d’éléments et d’attributs sont des noms XML valides.
Vérifiez que le document XML est bien formé.
Encoder des octets binaires en base64 ou BinHex et écrire le texte résultant.
Transmettez des valeurs à l’aide de types Common Language Runtime au lieu de chaînes pour éviter d’avoir à effectuer manuellement des conversions de valeurs.
Écrivez plusieurs documents dans un flux de sortie.
Écrivez des noms valides, des noms qualifiés et des jetons de nom.

Créer un enregistreur XML

Pour créer une XmlWriter instance, utilisez la XmlWriter.Create méthode. Pour spécifier l’ensemble de fonctionnalités que vous souhaitez activer sur l’enregistreur XML, passez une XmlWriterSettings à la Create méthode. Sinon, les paramètres par défaut sont utilisés. Pour plus d’informations, consultez les Create pages de référence.

Spécifier le format de sortie

La XmlWriterSettings classe comprend plusieurs propriétés qui contrôlent la mise XmlWriter en forme de la sortie :

Propriété	Descriptif
Encoding	Spécifie l’encodage de texte à utiliser. La valeur par défaut est `Encoding.UTF8`.
Indent	Indique s’il faut mettre en retrait les éléments. La valeur par défaut est `false` (aucune mise en retrait).
IndentChars	Spécifie la chaîne de caractères à utiliser lors de la mise en retrait. La valeur par défaut est 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, flux de ligne) pour les plateformes non Unix et `\n` (flux de ligne) pour les plateformes Unix.
NewLineHandling	Spécifie comment gérer les caractères de nouvelle ligne.
NewLineOnAttributes	Indique s’il faut écrire des attributs sur une nouvelle ligne. Indent doit être défini sur lors de `true` l’utilisation de cette propriété. La valeur par défaut est `false`.
OmitXmlDeclaration	Indique s’il faut écrire une déclaration XML. La valeur par défaut est `false`.

IndentChars Les Indent propriétés contrôlent la mise en forme de l’espace blanc non significatif. 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 la NewLineOnAttributes commande pour écrire chaque attribut sur une nouvelle ligne avec un niveau supplémentaire de 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 XmlWriterSettings classe pour vérifier la conformité des données :

La CheckCharacters propriété indique au writer XML de vérifier les caractères et de lever une XmlException exception si des caractères se trouvent en dehors de la plage légale, comme défini par le W3C.

La ConformanceLevel propriété configure l’enregistreur XML pour vérifier que le flux en cours d’écriture est conforme aux règles d’un document XML 1.0 ou fragment de document bien formé, tel que défini par le W3C. Les trois niveaux de conformité sont décrits dans le tableau suivant. La valeur par défaut est Document. Pour plus d’informations, consultez la XmlWriterSettings.ConformanceLevel propriété et l’énumération System.Xml.ConformanceLevel .

Niveau	Descriptif
Document	La sortie XML est conforme aux règles d’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 d’un fragment de document XML 1.0 bien formé.
Auto	L’enregistreur XML détermine le niveau de vérification de conformité à appliquer (document ou 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 répertoriées.

Utiliser	À
WriteElementString	Écrivez un nœud d’élément entier, y compris une valeur de chaîne.
WriteStartElement	Pour écrire une valeur d’élément à l’aide de plusieurs appels de méthode. Par exemple, vous pouvez appeler WriteValue pour écrire une valeur typée, WriteCharEntity écrire une entité de caractère, WriteAttributeString écrire un attribut ou écrire un élément enfant. Il s’agit d’une version plus sophistiquée de la WriteElementString méthode. Pour fermer l’élément, vous appelez l’élément ou WriteFullEndElement la WriteEndElement méthode.
WriteNode	Pour copier un nœud d’élément trouvé à la position actuelle d’un ou XPathNavigator d’un XmlReader objet. Lorsqu’elle est appelée, elle copie tous les éléments de l’objet source vers l’instance XmlWriter .

Écrire les attributs

Vous pouvez utiliser les méthodes suivantes XmlWriter 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.

Utiliser	À
WriteAttributeString	Pour écrire un nœud d’attribut entier, y compris une valeur de chaîne.
WriteStartAttribute	Pour écrire la valeur d’attribut à l’aide de plusieurs appels de méthode. Par exemple, vous pouvez appeler WriteValue pour écrire une valeur typée. Il s’agit d’une version plus sophistiquée de la WriteElementString méthode. Pour fermer l’élément, vous appelez la WriteEndAttribute méthode.
WriteAttributes	Pour copier tous les attributs trouvés à la position actuelle d’un XmlReader objet. Les attributs é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 contenus par 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œuds, la méthode lève une exception.

Gérer les espaces de noms

Les espaces de noms sont utilisés pour qualifier les noms d’éléments et d’attributs 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 aux références d’URI. Les espaces de noms créent l’unicité d’élément et de nom d’attribut dans un document XML.

Conserve XmlWriter une pile d’espaces de noms qui correspond à tous les espaces de noms définis dans l’étendue de l’espace de noms actuel. Lors de l’écriture d’éléments et d’attributs, vous pouvez utiliser des espaces de noms de la manière suivante :

Déclarez manuellement des espaces de noms à l’aide de la WriteAttributeString méthode. Cela peut être utile lorsque vous savez comment optimiser le nombre de déclarations d’espace de noms. Pour obtenir un exemple, consultez la WriteAttributeString(String, String, String, String) méthode.

Remplacez la déclaration d’espace de noms actuelle par un nouvel espace de noms. Dans le code suivant, la WriteAttributeString méthode modifie l’URI de l’espace "x" de noms du préfixe de "123" la valeur "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écifiez un préfixe d’espace de noms lors de l’écriture d’attributs ou d’éléments. La plupart des méthodes utilisées pour écrire des éléments et des attributs vous permettent de le faire. Par exemple, la WriteStartElement(String, String, String) méthode é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 WriteValue méthode 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 à l’aide de la WriteString méthode. Cela est plus facile que d’utiliser les méthodes de la XmlConvert classe pour convertir les données typées en valeur de chaîne avant de l’écrire.

Lors de l’écriture en texte, la valeur typée est sérialisée en texte à l’aide des XmlConvert règles de ce type de schéma.

Pour connaître les types de données XSD par défaut qui correspondent aux types CLR, consultez la WriteValue méthode.

Vous XmlWriter pouvez également l’utiliser pour écrire dans un magasin de données XML. Par exemple, la XPathNavigator classe peut créer un XmlWriter objet pour créer des nœuds pour un XmlDocument objet. Si le magasin de données contient des informations de schéma disponibles, la WriteValue méthode lève une exception si vous essayez de convertir en un type qui n’est pas autorisé. Si le magasin de données ne dispose pas d’informations de schéma disponibles, la WriteValue méthode traite toutes les valeurs comme un xsd:anySimpleType type.

Fermer l’enregistreur XML

Lorsque vous utilisez XmlWriter des méthodes pour générer du code XML, les éléments et les attributs ne sont pas écrits tant que vous n’appelez pas la Close méthode. Par exemple, si vous utilisez XmlWriter pour remplir un XmlDocument objet, vous ne pourrez pas voir les éléments et attributs écrits dans le document cible jusqu’à ce que vous fermez l’instance XmlWriter .

Programmation asynchrone

La plupart des XmlWriter méthodes ont des équivalents asynchrones qui ont « Async » à la fin de leurs noms de méthode. Par exemple, l’équivalent asynchrone est WriteAttributeString WriteAttributeStringAsync.

Pour la WriteValue méthode, qui n’a pas d’équivalent asynchrone, convertissez la valeur de retour en chaîne et utilisez la méthode à la WriteStringAsync place.

Considérations relatives à la sécurité

Tenez compte des éléments suivants lors de l’utilisation de la XmlWriter classe :

Les exceptions levées par le XmlWriter chemin d’accès peuvent divulguer les informations de chemin d’accès que vous ne souhaitez pas ajouter à l’application. Votre application doit intercepter les exceptions et les traiter de manière appropriée.
XmlWriterne valide aucune donnée transmise à la méthode ou WriteRaw à la WriteDocType méthode. Vous ne devez pas transmettre de données arbitraires à ces méthodes.