Création de XML correctement construit avec XmlTextWriter
XmlTextWriter, dérivé de XmlWriter, écrit le XML dans un fichier, une console, un flux et d'autres types de sortie.Lors de l'écriture du XML, ces méthodes effectuent des tâches supplémentaires pour générer du XML correctement construit.Le tableau suivant fournit une liste de méthodes qui vérifient à votre place que les données sont correctement construites.
Méthode |
Description de la tâche effectuée |
|---|---|
WriteAttributeString |
XmlTextWriter remplace le contenu du texte de l'attribut sous forme de séquence d'échappement en fonction de ce qu'il trouve. |
WriteString |
XmlTextWriter remplace les caractères spéciaux sous la forme de séquences d'échappement & < > et d'entités de caractères numériques si nécessaire. |
WriteBase64 |
XmlTextWriter encode les octets en Base64, qui peuvent ensuite être lus à l'aide de ReadBinary sur XmlReader. |
XmlTextWriter effectue les tâches supplémentaires suivantes pour vérifier que le XML est correctement construit :
Vérifie que les éléments XML sont écrits dans le bon ordre.Par exemple, il ne vous permettra pas d'écrire un attribut en dehors d'un élément, d'écrire un bloc CDATA dans un attribut ou d'écrire plusieurs éléments racine.En outre, il vérifie que la déclaration <?xml figure en premier et que le nœud <!DOCTYPE vient avant l'élément racine.
Vérifie que la valeur et le format de l'attribut xml:space sont corrects et s'assure que sa valeur est conforme à la recommandation du World Wide Web Consortium (W3C) sur le langage XML (Extensible Markup Language) 1.0 (quatrième édition) (en anglais). L'exemple suivant montre comment utiliser une valeur valide pour xml:space dans la méthode WriteAttributeString :
w.WriteAttributeString("xml:space", "", "preserve");Les valeurs valides pour l'attribut xml:space sont default et preserve.Si l'argument ne correspond pas à l'une de ces deux valeurs, une exception ArgumentException est levée.
Vérifie si une chaîne est utilisée en tant que paramètre (par exemple, Null==String.Empty et String.Empty), et si elle est conforme aux règles du W3C.
Le tableau suivant indique les méthodes et les propriétés supplémentaires définies par XmlTextWriter qui ne sont ni héritées ni définies dans XmlWriter ou héritées de Object.
Méthode ou propriété |
Description |
|---|---|
XmlTextWriter |
Crée une instance de XmlTextWriter qui prend un nom de fichier, un flux ou un TextWriter.Il existe une méthode surchargée pour intégrer un paramètre supplémentaire qui définit le type d'encodage. |
Spécifie si les espaces de noms sont pris en charge.Lorsque la valeur affectée est false, les déclarations xmlns ne sont pas écrites et vous pouvez spécifier des noms d'élément contenant un nombre indéfini de signes deux-points (:). |
|
Définit si la mise en retrait est utilisée pour mettre en forme la sortie. |
|
Définit le caractère à utiliser pour la mise en retrait lors d'une mise en forme (Formatting) avec retrait. |
|
Définit le nombre de caractères IndentChar à écrire pour chaque niveau dans la hiérarchie lors d'une mise en forme (Formatting) avec retrait. |
|
Définit le caractère à utiliser comme guillemet pour les valeurs des attributs.Il doit s'agir du guillemet simple ' ou double ". |
|
Retourne le flux dans lequel XmlTextWriter écrit.Retourne la valeur NULL si XmlTextWriter est construit avec un TextWriter non dérivé de StreamWriter. |
L'exemple suivant crée une sortie XML à l'aide de XmlTextWriter.
Shared Sub WriteQuote(writer As XmlWriter, symbol As String, price As Double, change As Double, volume As Long)
writer.WriteStartElement("Stock")
writer.WriteAttributeString("Symbol", symbol)
writer.WriteElementString("Price", XmlConvert.ToString(price))
writer.WriteElementString("Change", XmlConvert.ToString(change))
writer.WriteElementString("Volume", XmlConvert.ToString(volume))
writer.WriteEndElement()
End Sub 'WriteQuote
Public Shared Sub Main()
Dim writer As New XmlTextWriter(Console.Out)
writer.Formatting = Formatting.Indented
WriteQuote(writer, "MSFT", 74.125, 5.89, 69020000)
writer.Close()
End Sub 'Main
static void WriteQuote(XmlWriter writer, string symbol,
double price, double change, long volume)
{
writer.WriteStartElement("Stock");
writer.WriteAttributeString("Symbol", symbol);
writer.WriteElementString("Price", XmlConvert.ToString(price));
writer.WriteElementString("Change", XmlConvert.ToString(change));
writer.WriteElementString("Volume", XmlConvert.ToString(volume));
writer.WriteEndElement();
}
public static void Main(){
XmlTextWriter writer = new XmlTextWriter(Console.Out);
writer.Formatting = Formatting.Indented;
WriteQuote(writer, "MSFT", 74.125, 5.89, 69020000);
writer.Close();
}
Sortie
<Stock Symbol="MSFT">
<Price>74.125</Price>
<Change>5.89</Change>
<Volume>69020000</Volume>
</Stock>
L'entrée de la méthode WriteQuote est le symbole de cotation qui se présente sous la forme d'une chaîne string.Le prix et la modification sont déclarés comme double, et le volume est long.Pour convertir ces variables en chaînes, la classe XmlConvert est utilisée.Elle comprend des méthodes qui convertissent toutes les données fortement typées en chaînes.En outre, la classe XmlConvert contient des méthodes qui effectuent la conversion opposée, à savoir la conversion de chaînes en types de données Microsoft .NET Framework.Pour plus d'informations, voir Encodage de caractères des noms XML et conversion des types de données XML.
Pour un exemple de code illustrant l'écriture de données XML dans un fichier, voir XmlTextWriter.WriteProcessingInstruction.Pour un exemple de code illustrant l'écriture de données XML dans la console, voir XmlTextWriter.WriteString.
Le code suivant montre comment écrire un élément qui produit <price>19.95</price> :
'Write the price.writer.WriteElementString("price", "19.95")
//Write the price.writer.WriteElementString("price", "19.95");
Le code suivant montre comment écrire un attribut qui produit <element name="purchaseOrder"/> :
writer.WriteStartElement("element")
writer.WriteAttributeString("name", "purchaseOrder")
writer.WriteEndElement()
writer.WriteStartElement("element");
writer.WriteAttributeString("name", "purchaseOrder");
writer.WriteEndElement();
Écriture de déclarations d'espaces de noms et d'attributs à l'aide de la méthode WriteAttributeString
La méthode WriteAttributeString effectue deux tâches différentes.La première tâche consiste à écrire les attributs et à leur associer un préfixe d'espace de noms défini par l'utilisateur.La seconde tâche consiste à générer des déclarations d'espaces de noms.Si l'on écrit des attributs et que le paramètre de nom local est xmlns, cette méthode est considérée comme créatrice d'une déclaration d'espaces de noms.
Dans l'exemple de code suivant, la méthode WriteAttributeString est utilisée pour écrire des attributs dans un élément.
'Write the genre attribute.writer.WriteAttributeString("genre", "novel")
'Write the ISBN attribute.writer.WriteAttributeString("ISBN", "1-8630-014")
//Write the genre attribute.writer.WriteAttributeString("genre", "novel");
//Write the ISBN attribute.writer.WriteAttributeString("ISBN", "1-8630-014");
La méthode WriteAttributeString remplace aussi le contenu du texte de l'attribut sous forme de séquence d'échappement en fonction de ce qu'elle trouve.Si des guillemets doubles sont utilisés, XmlTextWriter les remplace dans le contenu du texte de la valeur de l'attribut par ".Si des guillemets simples sont utilisés, la méthode remplace le contenu du texte de la valeur de l'attribut par '.
Pour générer des déclarations d'espaces de noms, il existe une méthode surchargée, WriteAttributeString, qui permet à l'application de définir une déclaration d'espaces de noms.L'exemple de code suivant crée deux espaces de noms par défaut.La première déclaration lie tous les éléments sans préfixe à la première déclaration d'espaces de noms, tandis qu'un élément déclaré avec un préfixe « po » est lié à la seconde déclaration d'espaces de noms.
' Write the default namespace, identified as xmlns with no prefix
writer.WriteAttributeString("xmlns", Nothing, "http://www.w3.org/2000/10/XMLSchema")
' Write a namespace for the purchase order with a prefix of "po"
writer.WriteAttributeString("xmlns", "po", Nothing, "https://contoso.com/po")
// Write the default namespace, identified as xmlns with no prefix
writer.WriteAttributeString("xmlns", null, "http://www.w3.org/2000/10/XMLSchema");
// Write a namespace for the purchase order with a prefix of "po"
writer.WriteAttributeString("xmlns", "po", null, "https://contoso.com/po");
Méthode Close
La méthode Close vérifie que le document XML est valide lorsque le flux est fermé.Cela empêche la création de documents XML non valides et garantit que les données XML sont correctement construites.Outre la fermeture du flux, la méthode Close appelle également toutes les méthodes WriteEnd<xxx> nécessaires pour fermer le document.
Paires de méthodes
Les méthodes de XmlWriter se présentent par paires ; les paires WriteStartDocument et WriteEndDocument, WriteStartElement et WriteEndElement, WriteStartAttribute et WriteEndAttribute.À l'aide de ces méthodes, vous pouvez par exemple créer des éléments ou des attributs imbriqués.C'est grâce à ces paires de méthodes qu'un document XML est généré et permet de créer des attributs ou des éléments complexes.
Méthodes WriteStartDocument et WriteEndDocument
La méthode WriteStartDocument commence un nouveau document et écrit une déclaration XML avec la version « 1.0 » tandis que la méthode WriteEndDocument ferme ce document.Avant d'appeler à nouveau la méthode WriteStartDocument pour débuter l'écriture du document suivant, la mise en forme, la mise en retrait et d'autres propriétés peuvent être modifiées.La méthode WriteStartDocument reconnaît par programme qu'un document XML est en cours d'écriture et lui applique des règles de niveau racine.Si cette méthode n'est pas utilisée, un fragment XML est créé et vérifie que le document XML est correctement construit.Les règles de niveau racine ne sont pas appliquées.L'exemple de code suivant montre le début et la fin dans un document.
' Write the XML declaration.writer.WriteStartDocument()
...
'Close the document.writer.WriteEndDocument()
// Write the XML declaration.writer.WriteStartDocument();
...// Close the document.writer.WriteEndDocument();
Méthodes WriteStartElement et WriteEndElement
La paire de méthodes WriteStartElement et WriteEndElement délimite un ou plusieurs éléments.Dans toutes les méthodes WriteStartElement substituées, il est obligatoire d'affecter un paramètre de nom local à la balise de départ.Le code suivant utilise la paire de méthodes WriteStartElement et WriteEndElement.
' Write the title.writer.WriteStartElement("title")
writer.WriteString("The Handmaid's Tale")
writer.WriteEndElement()
// Write the title.writer.WriteStartElement("title");
writer.WriteString("The Handmaid's Tale");
writer.WriteEndElement();
Sortie
<title>The Handmaid's Tale</title>
WriteStartElement fournit une signature de méthode substituée qui permet au code de spécifier des préfixes d'espaces de noms pour ses éléments.Pour plus d'informations, voir Préfixes d'espaces de noms d'éléments dans XmlTextWriter.
Méthodes WriteStartAttribute et WriteEndAttribute
WriteStartAttribute et WriteEndAttribute sont identiques aux autres méthodes de début et de fin, à l'exception du fait qu'elles commencent et terminent des attributs.WriteStartAttribute écrit le début de l'attribut, une méthode WriteString est utilisée pour écrire sa valeur et WriteEndAttribute termine la balise d'attribut.L'exemple de code suivant illustre l'utilisation de la paire de méthodes WriteStartAttribute et WriteEndAttribute.
writer.WriteStartAttribute(prefix, "ISBN", "urn:samples")
writer.WriteString("1-861003-78")
writer.WriteEndAttribute()
writer.WriteStartAttribute(prefix, "ISBN", "urn:samples");
writer.WriteString("1-861003-78");
writer.WriteEndAttribute();
Sortie
<book bk:ISBN="1-861003-78">
La méthode WriteStartAttribute a une méthode surchargée qui permet à une application de spécifier un préfixe d'espace de noms pour pouvoir l'associer à l'attribut qu'elle écrit.Pour plus d'informations, voir Préfixes d'espaces de noms d'attributs dans XmlTextWriter.
Voir aussi
Référence
Concepts
Mise en forme d'une sortie XML avec XmlTextWriter
Fonctionnalités d'espace de noms de XmlTextWriter