Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die XmlWriter Klasse schreibt XML-Daten in einen Datenstrom, eine Datei, einen Textleser oder eine Zeichenfolge. Es unterstützt die Empfehlungen für W3C Extensible Markup Language (XML) 1.0 (vierte Edition) und Namespaces in XML 1.0 (dritte Edition).
Die Mitglieder der XmlWriter Klasse ermöglichen Folgendes:
- Stellen Sie sicher, dass die Zeichen gültige XML-Zeichen sind und dass Element- und Attributnamen gültige XML-Namen sind.
- Stellen Sie sicher, dass das XML-Dokument wohlgeformt ist.
- Codieren Sie binäre Bytes als Base64 oder BinHex, und schreiben Sie den resultierenden Text aus.
- Übergeben Sie Werte mithilfe gängiger Sprachlaufzeittypen anstelle von Zeichenfolgen, um zu vermeiden, dass Sie Wertkonvertierungen manuell ausführen müssen.
- Schreiben Sie mehrere Dokumente in einen Ausgabedatenstrom.
- Schreiben Sie gültige Namen, qualifizierte Namen und Namenstoken.
Erstellen eines XML-Writers
Verwenden Sie die XmlWriter Methode, um eine XmlWriter.Create Instanz zu erstellen. Um den Satz von Features anzugeben, die Sie für den XML-Writer aktivieren möchten, übergeben Sie eine XmlWriterSettings an die Create Methode. Andernfalls werden Standardeinstellungen verwendet. Ausführliche Informationen finden Sie auf den Create Referenzseiten.
Angeben des Ausgabeformats
Die XmlWriterSettings Klasse enthält mehrere Eigenschaften, die steuern, wie XmlWriter die Ausgabe formatiert wird:
| Eigentum | BESCHREIBUNG |
|---|---|
| Encoding | Gibt die zu verwendende Textcodierung an. Der Standardwert lautet 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 Standardwert ist zwei Leerzeichen. |
| NewLineChars | Gibt die Zeichenfolge an, die für Zeilenumbrüche verwendet werden soll. 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 lautet false. |
| OmitXmlDeclaration | Gibt an, ob eine XML-Deklaration geschrieben werden soll. Der Standardwert lautet false. |
Die Eigenschaften Indent und IndentChars steuern, wie unerheblicher Leerraum formatiert wird. 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 das NewLineOnAttributes Attribut, um jedes Attribut in eine neue Zeile mit einer zusätzlichen Einzugsebene 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 auszuwerfen, wenn alle Zeichen außerhalb des gesetzlichen Bereichs liegen, wie von W3C definiert.
Die ConformanceLevel Eigenschaft konfiguriert den XML-Writer, um zu überprüfen, ob der geschriebene Datenstrom den Regeln für ein wohlgeformtes XML 1.0-Dokument oder -Dokumentfragment entspricht, wie vom W3C definiert. Die drei Konformitätsstufen werden in der folgenden Tabelle beschrieben. Der Standardwert lautet Document. Ausführliche Informationen finden Sie in der XmlWriterSettings.ConformanceLevel Eigenschaft und in der System.Xml.ConformanceLevel Enumeration.
Niveau 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, welche Konformitätsüberprüfungsebene (Dokument oder Fragment) basierend auf den eingehenden Daten angewendet werden soll.
Elemente schreiben
Sie können die folgenden XmlWriter Methoden verwenden, um Elementknoten zu schreiben. Beispiele finden Sie in den aufgelisteten Methoden.
| Verwendung | Bis |
|---|---|
| WriteElementString | Schreiben eines gesamten Elementknotens, einschließlich eines Zeichenfolgenwerts |
| WriteStartElement | So schreiben Sie einen Elementwert mithilfe mehrerer Methodenaufrufe. Sie können beispielsweise aufrufen WriteValue , um einen typierten Wert zu schreiben, WriteCharEntity eine Zeichenentität zu schreiben, WriteAttributeString ein Attribut zu schreiben oder ein untergeordnetes Element zu schreiben. Dies ist eine komplexere Version der WriteElementString Methode. Um das Element zu schließen, rufen Sie die WriteEndElement Oder-Methode WriteFullEndElement auf. |
| WriteNode | Zum Kopieren eines Elementknotens an der aktuellen Position eines XmlReader- oder XPathNavigator-Objekts. Wenn sie aufgerufen wird, kopiert sie alles vom Quellobjekt in die XmlWriter Instanz. |
Attribute schreiben
Mit den folgenden XmlWriter Methoden können Sie Attribute auf Elementknoten schreiben. Diese Methoden können auch verwendet werden, um Namespacedeklarationen für ein Element zu erstellen, wie im nächsten Abschnitt erläutert.
| Verwendung | Bis |
|---|---|
| WriteAttributeString | Zum Schreiben eines gesamten Attributknotens, einschließlich eines Zeichenfolgenwerts |
| WriteStartAttribute | So schreiben Sie den Attributwert mithilfe mehrerer Methodenaufrufe. Sie können z. B. aufrufen WriteValue , um einen typierten Wert zu schreiben. Dies ist eine komplexere Version der WriteElementString Methode. Zum Schließen des Elements rufen Sie die WriteEndAttribute Methode auf. |
| WriteAttributes | Alle Attribute kopieren, die sich an der aktuellen Position eines XmlReader Objekts befinden. 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. - Für einen Elementknoten schreibt er alle Attribute, die im Element enthalten sind. - Für einen XML-Deklarationsknoten schreibt er alle Attribute in der Deklaration. - Bei allen anderen Knotentypen löst die Methode eine Ausnahme aus. |
Behandeln von Namespaces
Namespaces werden verwendet, um Element- und Attributnamen in einem XML-Dokument zu qualifizieren. Namespacepräfixe ordnen Elemente und Attribute Namespaces zu, die wiederum URI-Verweisen zugeordnet sind. Namespaces sorgen für die Eindeutigkeit von 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 auf folgende Weise verwenden:
Deklarieren Sie Namespaces manuell mithilfe der WriteAttributeString Methode. Dies kann hilfreich sein, wenn Sie wissen, wie Sie die Anzahl der Namespacedeklarationen am besten optimieren können. Ein Beispiel finden Sie unter der WriteAttributeString(String, String, String, String) Methode.
Überschreiben Sie die aktuelle Namespacedeklaration mit einem neuen Namespace. Im folgenden Code ändert die WriteAttributeString Methode den Namespace-URI für das
"x"Präfix von"123"zu"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()Der Code generiert die folgende XML-Zeichenfolge:
<x:root xmlns:x="123"> <item xmlns:x="abc" /> </x:root>Geben Sie beim Schreiben von Attributen oder Elementen ein Namespacepräfix an. Viele der Methoden zum Schreiben von Elementen und Attributen ermöglichen ihnen dies. Die Methode WriteStartElement(String, String, String) schreibt beispielsweise ein Starttag und verknüpft es mit einem angegebenen Namespace und Präfix.
Schreiben typisierter Daten
Die WriteValue Methode akzeptiert ein Common Language Runtime (CLR)-Objekt, konvertiert den Eingabewert in seine Zeichenfolgendarstellung entsprechend den XSD-Konvertierungsregeln (XML Schema Definition Language) und schreibt ihn mithilfe der WriteString Methode heraus. Dies ist einfacher als die Verwendung der Methoden in der XmlConvert Klasse, um die eingegebenen Daten in einen Zeichenfolgenwert zu konvertieren, bevor sie ausgeschrieben werden.
Beim Schreiben in Text wird der eingegebene Wert mithilfe der für diesen XmlConvert Schematyp geltenden Regeln in Text serialisiert.
Standard-XSD-Datentypen, die CLR-Typen entsprechen, finden Sie unter der WriteValue Methode.
Dies XmlWriter kann auch zum Schreiben in einen XML-Datenspeicher verwendet werden. Beispielsweise kann die XPathNavigator Klasse ein XmlWriter Objekt erstellen, um Knoten für ein XmlDocument Objekt zu erstellen. Wenn der Datenspeicher Schemainformationen enthält, löst die WriteValue Methode eine Ausnahme aus, wenn Sie versuchen, in einen nicht zulässigen Typ zu konvertieren. Wenn der Datenspeicher keine Schemainformationen zur Verfügung hat, behandelt die WriteValue Methode alle Werte als xsd:anySimpleType Typ.
Schließen des XML-Writers
Wenn Sie die XmlWriter-Methoden zum Ausgeben von XML verwenden, werden die Elemente und Attribute erst geschrieben, wenn Sie die Close-Methode aufrufen. Beispielsweise, wenn Sie ein XmlWriter verwenden, um ein XmlDocument Objekt zu befüllen, können Sie die geschriebenen Elemente und Attribute im Zieldokument erst sehen, wenn Sie die XmlWriter Instanz schließen.
Asynchrone Programmierung
XmlWriter Die meisten Methoden weisen asynchrone Entsprechungen auf, die am Ende der Methodennamen "Async" haben. Zum Beispiel ist die asynchrone Entsprechung von WriteAttributeStringWriteAttributeStringAsync.
Konvertieren Sie für die Methode, für die WriteValue kein asynchrones Gegenstück vorhanden ist, den Rückgabewert in eine Zeichenfolge, und verwenden Sie stattdessen die WriteStringAsync Methode.
Sicherheitsüberlegungen
Berücksichtigen Sie beim Arbeiten mit der XmlWriter Klasse Folgendes:
Ausnahmen, die von XmlWriter ausgelöst werden, können Pfadinformationen offenlegen, die Sie nicht an die App weitergeben möchten. Ihre App muss Ausnahmen erfassen und entsprechend verarbeiten.
XmlWriter überprüft keine Daten, die an die WriteDocType Methode WriteRaw übergeben werden. Sie sollten keine beliebigen Daten an diese Methoden übergeben.
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
