System.Xml.XmlWriter-Klasse

  • Artikel

Die XmlWriter-Klasse schreibt XML-Daten in einen Datenstrom, eine Datei, einen Textleser oder eine Zeichenfolge. Sie unterstützt die W3C-Empfehlungen Extensible Markup Language (XML) 1.0 (fourth edition) und Namespaces in XML 1.0 (third edition).

Die Member der XmlWriter-Klasse ermöglichen Folgendes:

  • Überprüfen, ob die Zeichen zulässige XML-Zeichen sind, und ob Element- und Attributnamen gültige XML-Namen sind.
  • Überprüfen, ob das XML-Dokument wohlgeformt ist.
  • Das Codieren binärer Bytes als Base64 oder BinHex und das Ausschreiben des resultierenden Texts
  • Übergeben von Werten mithilfe von Common Language Runtime-Typen anstelle von Zeichenfolgen, um das manuelle Ausführen von Wertkonvertierungen zu vermeiden
  • Mehrere Dokumente in einen Ausgabestream schreiben.
  • Gültige Namen, qualifizierte Namen und Namenstoken schreiben.

Erstellen eines XML-Writers

Verwenden Sie die XmlWriter.Create-Methode, um eine XmlWriter-Instanz zu erstellen. Um die Features anzugeben, die Sie für den XML-Writer aktivieren möchten, übergeben Sie eine XmlWriterSettings-Klasse an die Create-Methode. Andernfalls werden die Standardeinstellungen verwendet. Weitere Informationen finden Sie auf den Create-Referenzseiten.

Festlegen des Ausgabeformats

Die XmlWriterSettings-Klasse enthält mehrere Eigenschaften, die steuern, wie die XmlWriter-Ausgabe formatiert wird:

Eigenschaft Beschreibung
Encoding Gibt die zu verwendende Textcodierung an. Der Standardwert ist Encoding.UTF8.
Indent Gibt an, ob Elemente eingerückt werden. Der Standardwert ist false (kein Einzug).
IndentChars Gibt die für das Einrücken zu verwendende Zeichenfolge an. Der Standard beträgt zwei Leerzeichen.
NewLineChars Gibt die für Zeilenumbrüche zu verwendende Zeichenfolge an. Der Standardwert ist für Nicht-Unix-Plattformen \r\n (Wagenrücklauf, Zeilenvorschub) und für Unix-Plattformen \n (Zeilenvorschub).
NewLineHandling Gibt an, wie Zeilenvorschubzeichen behandelt werden
NewLineOnAttributes Gibt an, ob Attribute in einer neuen Zeile geschrieben werden sollen. Indent sollte bei Verwendung dieser Eigenschaft auf true festgelegt werden. Der Standardwert ist false.
OmitXmlDeclaration Gibt an, ob eine XML-Deklaration geschrieben werden soll. Der Standardwert ist false.

Die Indent-Eigenschaft und die IndentChars-Eigenschaft steuern die Formatierung von nicht signifikantem Leerraum. Beispielsweise zum Einziehen von Elementknoten:

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)

Verwenden Sie die NewLineOnAttributes-Eigenschaft, um jedes Attribut mit einer zusätzlichen Einzugsstufe in eine neue Zeile zu schreiben:

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)

Datenkonformität

Ein XML-Writer verwendet zwei Eigenschaften aus der XmlWriterSettings-Klasse, um die Datenkonformität zu überprüfen:

  • Die CheckCharacters-Eigenschaft weist den XML-Writer an, Zeichen zu überprüfen und eine XmlException-Ausnahme auszulösen, wenn einige Zeichen außerhalb des durch W3C definierten gesetzlichen Bereichs liegen.

  • Die ConformanceLevel-Eigenschaft konfiguriert den XML-Writer so, dass er überprüfen, ob der geschriebene Datenstrom den durch W3C definierten Regeln für ein wohlgeformtes XML 1.0-Dokument oder -Dokumentfragment entspricht. Die drei Konformitätsstufen werden in der folgenden Tabelle beschrieben. Der Standardwert ist Document. Ausführliche Informationen finden Sie in der XmlWriterSettings.ConformanceLevel-Eigenschaft und der System.Xml.ConformanceLevel-Enumeration.

    Ebene Beschreibung
    Document Die XML-Ausgabe entspricht den Regeln für ein wohlgeformtes XML 1.0-Dokument und kann von jedem konformen Prozessor verarbeitet werden.
    Fragment Die XML-Ausgabe entspricht den Regeln für ein wohlgeformtes XML 1.0-Dokumentfragment.
    Auto Der XML-Writer bestimmt basierend auf den eingehenden Daten, welche Stufe der Konformitätsüberprüfung (Dokument oder Fragment) angewendet werden soll.

Schreiben von Elementen

Sie können die folgenden XmlWriter-Methoden verwenden, um Elementknoten zu schreiben. Beispiele finden Sie in den aufgelisteten Methoden.

Verwenden Beschreibung
WriteElementString Schreiben eines gesamten Elementknotens, einschließlich eines Zeichenfolgenwerts
WriteStartElement Zum Schreiben eines Elementwerts mithilfe mehrerer Methodenaufrufe. Beispielsweise können Sie WriteValue aufrufen, um einen typisierten Wert zu schreiben, WriteCharEntity, um eine Zeichenentität zu schreiben, WriteAttributeString, um ein Attribut zu schreiben, oder Sie können ein untergeordnetes Element schreiben. Das ist eine komplexere Version der WriteElementString-Methode.

Zum Schließen des Elements können Sie die Methoden WriteEndElement oder WriteFullEndElement aufrufen.
WriteNode Zum Kopieren eines Elementknotens an der aktuellen Position eines XmlReader- oder XPathNavigator-Objekts. Beim einem Aufruf werden alle Daten aus dem Quellobjekt in die XmlWriter-Instanz kopiert.

Attribute schreiben

Sie können die folgenden XmlWriter-Methoden verwenden, um Attribute in Elementknoten zu schreiben. Diese Methoden können ebenfalls verwendet werden, um Namespacedeklarationen für ein Element zu erstellen. Das wird im nächsten Abschnitt erläutert.

Verwenden Beschreibung
WriteAttributeString Zum Schreiben eines gesamten Attributknotens, einschließlich eines Zeichenfolgenwerts
WriteStartAttribute Zum Schreiben des Attributwerts mithilfe mehrerer Methodenaufrufe. Sie können beispielsweise WriteValue aufrufen, um einen eingegebenen Wert zu schreiben. Das ist eine komplexere Version der WriteElementString-Methode.

Zum Schließen des Elements können Sie die WriteEndAttribute-Methode aufrufen.
WriteAttributes Zum Kopieren aller Attribute an der aktuellen Position eines XmlReader-Objekts. Die geschriebenen Attribute hängen vom Typ des Knotens ab, auf dem der Leser derzeit positioniert ist:

– Bei einem Attributknoten wird das aktuelle Attribut und anschließend die restlichen Attribute bis zum Tag geschrieben, der das Element schließt.
– Bei einem Elementknoten werden alle Attribute geschrieben, die im Element enthalten sind.
– Bei einem XML-Deklarationsknoten werden alle Attribute in der Deklaration geschrieben.
– Bei allen anderen Knotentypen löst die Methode eine Ausnahme aus.

Behandeln von Namespaces

Mit Namespaces werden Element- und Attributnamen in XML-Dokumenten qualifiziert. Namespacepräfixe ordnen Elemente und Attribute Namespaces zu, die wiederum URI-Verweisen zugeordnet sind. Namespaces gewährleisten eindeutige Element- und Attributnamen in einem XML-Dokument.

Die XmlWriter-Klasse verwaltet einen Namespacestapel, der allen im aktuellen Namespacebereich definierten Namespace entspricht. Beim Schreiben von Elementen und Attributen können Sie Namespaces für folgende Aufgaben verwenden:

  • Deklarieren Sie Namespaces manuell mithilfe der WriteAttributeString-Methode. Dies kann hilfreich sein, wenn Sie wissen, wie die Anzahl der Namespacedeklarationen optimiert werden kann. Ein Beispiel finden Sie in der WriteAttributeString(String, String, String, String)-Methode.

  • Überschreiben der aktuellen Namespacedeklaration mit einem neuen Namespace. Im folgenden Code wird durch die WriteAttributeString-Methode der Namespace-URI für das Präfix "x" von "123" in "abc" geändert.

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

    Der Code generiert die folgende XML-Zeichenfolge:

    <x:root xmlns:x="123">
  <item xmlns:x="abc" />
</x:root>

  • Angeben eines Namespacepräfixes beim Schreiben von Attributen oder Elementen. Das ist mit vielen Methoden möglich, die zum Schreiben von Elementen und Attributen verwendet werden. Beispielsweise schreibt die WriteStartElement(String, String, String)-Methode ein Starttag und ordnet dieses einem angegebenen Namespace und Präfix zu.

Schreiben typisierter Daten

Die WriteValue-Methode akzeptiert ein CLR-Objekt (Common Language Runtime), konvertiert den Eingabewert entsprechend den XSD-Konvertierungsregeln (XML Schema Definition Language, Sprache der XML-Schemadefinition) in die Zeichenfolgendarstellung und schreibt diesen mithilfe der WriteString-Methode aus. Das ist einfacher als die Verwendung der Methoden in der XmlConvert-Klasse, um die eingegebenen Daten in einen Zeichenfolgenwert zu konvertieren, bevor diese ausgeschrieben werden.

Beim Schreiben in Text wird der eingegebene Wert mithilfe der XmlConvert-Regeln für diesen Schematyp in Text serialisiert.

XSD-Standarddatentypen, die CLR-Typen entsprechen, finden Sie in der WriteValue-Methode.

Die XmlWriter-Klasse kann zudem verwendet werden, um in einen XML-Datenspeicher zu schreiben. Die XPathNavigator-Klasse kann z. B. ein XmlWriter-Objekt erstellen, das Knoten für ein XmlDocument-Objekt erstellt. Wenn der Datenspeicher Schemainformationen enthält, löst die WriteValue-Methode eine Ausnahme beim Versuch aus, in einen nicht zulässigen Typ zu konvertieren. Wenn der Datenspeicher keine Schemainformationen enthält, behandelt die WriteValue-Methode alle Werte als xsd:anySimpleType-Typ.

Schließen des XML-Writers

Wenn Sie XmlWriter-Methoden zum Ausgeben von XML-Code verwenden, werden die Elemente und Attribute erst beim Aufrufen der Close-Methode geschrieben. Wenn Sie beispielsweise XmlWriter zum Auffüllen eines XmlDocument-Objekts verwenden, werden die geschriebenen Elemente und Attribute erst dann im Zieldokument angezeigt, wenn Sie die XmlWriter-Instanz schließen.

Asynchrone Programmierung

Die meisten XmlWriter-Methoden haben asynchrone Entsprechungen, die am Ende ihrer Methodennamen „Async“ aufweisen. Beispielsweise ist WriteAttributeStringAsync das asynchrone Äquivalent von WriteAttributeString.

Konvertieren Sie für die WriteValue-Methode ohne asynchrone Entsprechung den Rückgabewert in eine Zeichenfolge, und verwenden Sie stattdessen die WriteStringAsync-Methode.

Sicherheitshinweise

Beachten Sie beim Arbeiten mit der XmlWriter-Klasse Folgendes:

  • Die von der XmlWriter-Klasse ausgelösten Ausnahmen können Pfadinformationen offenlegen, die nicht in Ihrer App enthalten sein sollten. Ihre App muss Ausnahmen erfassen und entsprechend verarbeiten.

  • XmlWriter überprüft keine Daten, die an die Methoden WriteDocType oder WriteRaw übergeben werden. Sie sollten keine beliebigen Daten an diese Methoden übergeben.