Erstellen von wohlgeformtem XML mit "XmlTextWriter"

Artikel
04/27/2011

Der XmlTextWriter, der aus dem XmlWriter abgeleitet ist, schreibt XML in eine Datei, eine Konsole, einen Datenstream oder in einen anderen Ausgabetyp.Beim Schreiben von XML-Code führen die Methoden zusätzliche Aktionen aus, um wohlgeformten XML-Code zu produzieren.In der folgenden Tabelle wird eine Reihe von Methoden zur Gewährleistung von wohlgeformten XML-Daten veranschaulicht.

Methode	Ausgeführte Aktionen
WriteAttributeString	Der XmlTextWriter schützt auch den Textinhalt des Attributs, je nach den vorhandenen Daten.
WriteString	Der XmlTextWriter schützt Sonderzeichen und ersetzt sie dabei, falls erforderlich, durch & < > und numerische Zeichenentitäten.
WriteBase64	Der XmlTextWriter codiert die Base64-Bytes, die dann mit ReadBinary im "XmlReader" gelesen werden können.

Die folgenden zusätzlichen Schritte werden vom XmlTextWriter ausgeführt, um zu gewährleisten, dass der XML-Code wohlgeformt ist:

Es wird sichergestellt, dass die XML-Elemente in der richtigen Reihenfolge geschrieben werden.Beispielsweise wird verhindert, dass ein Attribut außerhalb eines Elements, ein CDATA-Block innerhalb eines Attributs oder mehrere Stammelemente geschrieben werden.Darüber hinaus wird gewährleistet, dass die <?xml-Deklaration an erster Stelle und der <!DOCTYPE-Knoten vor dem Stammelement steht.
Stellt sicher, dass Wert und Format des xml:space-Attributs korrekt sind und dass der Wert der W3C-Empfehlung zu Extensible Markup Language (XML) 1.0 (Fourth Edition) entspricht. Anhand des folgenden Beispiels wird die Verwendung eines gültigen Werts für das xml:space-Attribut in der WriteAttributeString-Methode dargestellt:
```
w.WriteAttributeString("xml:space", "", "preserve");
```
Gültige Werte für das xml:space-Attribut sind default und preserve.Wenn das Argument einen anderen Wert aufweist, wird eine ArgumentException ausgelöst.
Es wird überprüft, ob eine Zeichenfolge als Parameter verwendet wird, z. B. Null==String.Empty und String.Empty), und ob diese den W3C-Regeln entspricht.

In der folgenden Tabelle werden zusätzliche Methoden und Eigenschaften veranschaulicht, die vom XmlTextWriter definiert werden und nicht in XmlWriter geerbt oder definiert oder von Object geerbt werden.

Methode oder Eigenschaft	Beschreibung
XmlTextWriter	Erstellt eine Instanz des XmlTextWriter, die einen Dateinamen, einen Datenstream oder einen TextWriter verwendet.Es gibt eine überladene Methode, die einen zusätzlichen Parameter verwendet, der den Codierungstyp definiert.
Namespaces-Eigenschaft	Gibt an, ob Namespaces unterstützt werden.Wenn diese Eigenschaft den Wert false aufweist, werden xmlns-Deklarationen nicht geschrieben, und Sie können Elementnamen mit beliebig vielen Doppelpunkten angeben.
Formatting-Eigenschaft	Definiert, ob für die Formatierung der Ausgabe Einzüge verwendet werden.
IndentChar-Eigenschaft	Definiert, welche Zeichen für Einzüge verwendet werden, wenn Formatting mit Einzügen ausgeführt wird.
Indentation-Eigenschaft	Definiert, wie viele IndentChars für jede Ebene der Hierarchie geschrieben werden sollen, wenn Formatting ausgeführt wird.
QuoteChar-Eigenschaft	Definiert, welches Zeichen als Anführungszeichen für Attributwerte verwendet wird.Dabei muss es sich um ein einfaches (') oder ein doppeltes Anführungszeichen (") handeln.
BaseStream	Gibt den Datenstream zurück, in den der XmlTextWriter schreibt.Gibt NULL zurück, wenn der XmlTextWriter mit einem TextWriter erstellt wurde, der nicht vom StreamWriter abgeleitet ist.

Im folgenden Beispiel wird mithilfe des XmlTextWriter eine XML-Ausgabe erstellt.

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();
}

Ausgabe

<Stock Symbol="MSFT">
      <Price>74.125</Price>
      <Change>5.89</Change>
      <Volume>69020000</Volume>
</Stock>

Die Eingabe für die WriteQuote-Methode ist das Börsensymbol (Stock Symbol), das als string eingelesen wird.Der Kurs und die Veränderung werden als double deklariert, das Volumen als long.Die XmlConvert-Klasse wird verwendet, um diese Variablen in Zeichenfolgen zu konvertieren.Die zugehörigen Methoden konvertieren alle stark typisierten Daten in Zeichenfolgen.Darüber hinaus verfügt die XmlConvert-Klasse über Methoden, die die umgekehrte Konvertierung durchführen, d. h. Zeichenfolgen in .NET Framework-Datentypen.Weitere Informationen finden Sie unter Zeichencodierung von XML-Namen und Konvertierung von XML-Datentypen.

Ein Codebeispiel für das Schreiben von XML in eine Datei finden Sie unter XmlTextWriter.WriteProcessingInstruction.Ein Codebeispiel für das Schreiben von XML in eine Konsole finden Sie unter XmlTextWriter.WriteString.

Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein Element schreiben, das <price>19.95</price> generiert:

'Write the price.writer.WriteElementString("price", "19.95")

//Write the price.writer.WriteElementString("price", "19.95");

Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein Attribut schreiben, das <element name="purchaseOrder"/> generiert:

writer.WriteStartElement("element")
writer.WriteAttributeString("name", "purchaseOrder")
writer.WriteEndElement()

writer.WriteStartElement("element"); 
writer.WriteAttributeString("name", "purchaseOrder"); 
writer.WriteEndElement();

Schreiben von Attributen und Namespacedeklarationen mit der WriteAttributeString-Methode

Die WriteAttributeString-Methode hat zwei verschiedene Aufgaben.Eine besteht darin, Attribute zu schreiben und sie mit einem benutzerdefinierten Namespacepräfix zu verknüpfen.Die andere besteht im Generieren von Namespacedeklarationen.Wenn Attribute geschrieben werden und der localname-Parameter xmlns ist, dann wird angenommen, dass diese Methode eine Namespacedeklaration erstellt.

Im folgenden Codebeispiel wird die WriteAttributeString-Methode zum Schreiben von Attributen innerhalb eines Elements verwendet.

'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");

WriteAttributeString schützt auch den Textinhalt des Attributs, je nach den vorhandenen Daten.Wenn doppelte Anführungszeichen verwendet werden, schützt der XmlTextWriter sie im Textinhalt des Attributwerts mit ".Wenn einfache Anführungszeichen verwendet werden, schützt er diese im Textinhalt des Attributwerts mit '.

Zum Generieren von Namespacedeklarationen gibt es die überladene Methode WriteAttributeString, anhand der die Anwendung eine Namespacedeklaration definieren kann.Im folgenden Codebeispiel werden zwei Standardnamespaces deklariert.Die erste Deklaration bindet alle Elemente ohne Präfix an die erste Namespacedeklaration, während alle Elemente, die mit einem "po"-Präfix deklariert sind, an die zweite Namespacedeklaration gebunden werden.

' 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");

Close-Methode

Mit der Close-Methode wird sichergestellt, dass das XML-Dokument gültig ist, wenn der Datenstream geschlossen wird.Dadurch wird verhindert, dass ungültige XML-Dokumente erstellt werden, und gleichzeitig gewährleistet, dass der XML-Code wohlgeformt ist.Die Close-Methode schließt nicht nur den Datenstream, sondern ruft auch alle erforderliche WriteEnd<xxx>-Methoden zum Schließen des Dokuments auf.

Methodenpaare

Die Methoden im XmlWriter gehören paarweise zusammen: die WriteStartDocument-Methode und die WriteEndDocument-Methode, die WriteStartElement-Methode und die WriteEndElement-Methode sowie die WriteStartAttribute-Methode und die WriteEndAttribute-Methode.Mithilfe dieser Methoden können Sie z. B. geschachtelte Elemente oder Attribute erstellen.Diese Methodenpaare dienen zur Erstellung eines XML-Dokuments und komplexer Elemente oder Attribute.

WriteStartDocument-Methode und WriteEndDocument-Methode

Die WriteStartDocument-Methode startet ein neues Dokument und schreibt die XML-Deklaration, wobei als Versionsattribut "1.0" festgelegt wird, und die WriteEndDocument-Methode schließt dieses Dokument.Bis zum Aufrufen der nächsten WriteStartDocument-Methode, um das nächste Dokument zu schreiben, können die Formatierung, die Einzüge und andere Eigenschaften geändert werden.Die WriteStartDocument-Methode erkennt programmgesteuert, dass ein XML-Dokument geschrieben wird, und wendet auf Stammebene gültige Regeln an.Wenn diese Methode nicht verwendet wird, wird ein XML-Fragment erstellt und überprüft, ob dieses wohlgeformt ist.Auf Stammebene gültige Regeln werden nicht angewendet.Das folgende Codebeispiel veranschaulicht den Start und das Ende in einem Dokument.

' Write the XML declaration.writer.WriteStartDocument()
...
'Close the document.writer.WriteEndDocument()

// Write the XML declaration.writer.WriteStartDocument();
...// Close the document.writer.WriteEndDocument();

WriteStartElement-Methode und WriteEndElement-Methode

Das WriteStartElement- und WriteEndElement-Methodenpaar begrenzt eines oder mehrere Elemente.Alle überschriebenen WriteStartElement-Methoden erfordern einen Parameter für den lokalen Namen für das Anfangstag.Im folgenden Codebeispiel wird das Methodenpaar WriteStartElement und WriteEndElement verwendet.

' 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();

Ausgabe

<title>The Handmaid's Tale</title>

WriteStartElement stellt eine überschriebene Methodensignatur bereit, durch die der Code Namespacepräfixe für seine Elemente angeben kann.Weitere Informationen finden Sie unter Präfixe des Elementnamespaces im "XmlTextWriter".

WriteStartAttribute-Methode und WriteEndAttribute-Methode

Die WriteStartAttribute-Methode und die WriteEndAttribute-Methode ähneln anderen Start- und Endmethoden, nur dienen sie zum Starten und Beenden von Attributen.WriteStartAttribute schreibt den Start eines Attributs, der Attributwert wird mit einer WriteString-Methode geschrieben, und WriteEndAttribute beendet das Attributtag.Im folgenden Codebeispiel wird das Methodenpaar WriteStartAttribute und WriteEndAttribute veranschaulicht.

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();

Ausgabe

<book bk:ISBN="1-861003-78">

WriteStartAttribute verfügt über eine überladene Methode, mit der eine Anwendung ein Namespacepräfix angeben kann, sodass das Namespacepräfix mit den von ihm geschriebenen Attributen verknüpft werden kann.Weitere Informationen finden Sie unter Präfixe des Attributnamespaces im "XmlTextWriter".

Siehe auch

Freigeben über

Erstellen von wohlgeformtem XML mit "XmlTextWriter"

Schreiben von Attributen und Namespacedeklarationen mit der WriteAttributeString-Methode

Close-Methode

Methodenpaare

WriteStartDocument-Methode und WriteEndDocument-Methode

WriteStartElement-Methode und WriteEndElement-Methode

WriteStartAttribute-Methode und WriteEndAttribute-Methode

Siehe auch

Referenz

Konzepte

Weitere Ressourcen

Zusätzliche Ressourcen