XmlWriter Třída

Definice

public ref class XmlWriter abstract : IDisposable

public ref class XmlWriter abstract : IAsyncDisposable, IDisposable

public ref class XmlWriter abstract

public abstract class XmlWriter : IDisposable

public abstract class XmlWriter : IAsyncDisposable, IDisposable

public abstract class XmlWriter

type XmlWriter = class
    interface IDisposable

type XmlWriter = class
    interface IAsyncDisposable
    interface IDisposable

type XmlWriter = class

Public MustInherit Class XmlWriter
Implements IDisposable

Public MustInherit Class XmlWriter
Implements IAsyncDisposable, IDisposable

Public MustInherit Class XmlWriter

Dědičnost

Object

XmlWriter

Odvozené

System.Xml.XmlDictionaryWriter

System.Xml.XmlTextWriter

System.Xml.Xsl.Runtime.XmlQueryOutput

Implementuje

IDisposable IAsyncDisposable

Příklady

Následující příklad kódu ukazuje, jak použít asynchronní rozhraní API ke generování XML.

async Task TestWriter(Stream stream)
{
    XmlWriterSettings settings = new XmlWriterSettings();
    settings.Async = true;

    using (XmlWriter writer = XmlWriter.Create(stream, settings)) {
        await writer.WriteStartElementAsync("pf", "root", "http://ns");
        await writer.WriteStartElementAsync(null, "sub", null);
        await writer.WriteAttributeStringAsync(null, "att", null, "val");
        await writer.WriteStringAsync("text");
        await writer.WriteEndElementAsync();
        await writer.WriteProcessingInstructionAsync("pName", "pValue");
        await writer.WriteCommentAsync("cValue");
        await writer.WriteCDataAsync("cdata value");
        await writer.WriteEndElementAsync();
        await writer.FlushAsync();
    }
}

Poznámky

Třída XmlWriter zapisuje data XML do datového proudu, souboru, textu nebo řetězce. Podporuje W3C Extensible Markup Language (XML) 1.0 (čtvrtá edice) a názvové prostory v XML 1.0 (třetí edice) doporučení.

Členové XmlWriter třídy umožňují:

• Ověřte, že znaky jsou právní znaky XML a že názvy elementů a atributů jsou platné názvy XML.
• Ověřte, že je dokument XML správně vytvořený.
• Zakódujte binární bajty jako Base64 nebo BinHex a zapište výsledný text.
• Předejte hodnoty pomocí běžných typů běhového prostředí místo řetězců, abyste se vyhnuli manuálnímu převodu hodnot.
• Napište více dokumentů do jednoho výstupního datového proudu.
• Zapisujte platné názvy, kvalifikované názvy a názvové tokeny.

Vytvoření zapisovače XML

K vytvoření XmlWriter instance použijte metodu XmlWriter.Create . Chcete-li zadat sadu funkcí, které chcete povolit pro zapisovač XML, předejte XmlWriterSettings metodě Create . V opačném případě se použijí výchozí nastavení. Podrobnosti najdete na Create referenčních stránkách.

Zadání výstupního formátu

Třída XmlWriterSettings obsahuje několik vlastností, které řídí formátování XmlWriter výstupu:

Vlastnosti Indent a IndentChars řízení, jak je nevýznamný bílý prostor formátován. Pokud například chcete odsadit uzly elementů:

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)

Použijte NewLineOnAttributes pro zápis každého atributu na nový řádek s jednou úrovní odsazení navíc.

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)

Shoda s daty

Zapisovač XML používá dvě vlastnosti třídy XmlWriterSettings ke kontrole shody dat:

• Vlastnost CheckCharacters dává zapisovači XML pokyn, aby zkontroloval znaky a vyvolá XmlException výjimku, pokud některé znaky jsou mimo právní rozsah, jak definuje W3C.

• Vlastnost ConformanceLevel nakonfiguruje zapisovač XML tak, aby zkontroloval, že datový proud, který je zapsán, vyhovuje pravidlům pro dobře formátovaný dokument XML 1.0 nebo fragment dokumentu, jak je definováno W3C. Tři úrovně shody jsou popsány v následující tabulce. Výchozí hodnota je Document. Další informace naleznete v vlastnosti XmlWriterSettings.ConformanceLevel a výčtu System.Xml.ConformanceLevel.

  Úrovni	Description
  Document	Výstup XML odpovídá pravidlům pro dokument XML 1.0 ve správném formátu a lze ho zpracovat libovolným odpovídajícím procesorem.
  Fragment	Výstup XML odpovídá pravidlům pro fragment dokumentu XML 1.0 ve správném formátu.
  Auto	Zapisovač XML určuje, jakou úroveň kontroly shody se má použít (dokument nebo fragment) na základě příchozích dat.

Zápis prvků

K zápisu uzlů elementů můžete použít následující XmlWriter metody. Příklady najdete v uvedených metodách.

Zápis atributů

K zápisu atributů na uzlech elementů můžete použít následující XmlWriter metody. Tyto metody lze také použít k vytvoření deklarací oboru názvů u elementu, jak je popsáno v další části.

Zpracování jmenných prostorů

Jmenné prostory se používají k určení názvů elementů a atributů v dokumentu XML. Předpony jmenného prostoru přidružují prvky a atributy k jmenným prostorům, které jsou zase přidružené k odkazům URI. Jmenné prostory zajišťují jedinečnost názvů elementů a atributů v dokumentu XML.

Udržuje XmlWriter zásobník oborů názvů, který odpovídá všem oborům názvů definovaným v aktuálním rozsahu oboru názvů. Při psaní elementů a atributů můžete obory názvů využívat následujícími způsoby:

• Deklarujte obory názvů ručně pomocí WriteAttributeString metody. Může to být užitečné, když víte, jak nejlépe optimalizovat počet deklarací oboru názvů. Příklad najdete v WriteAttributeString(String, String, String, String) metodě.

• Nahraďte aktuální deklaraci oboru názvů novou deklarací oboru názvů. V následujícím kódu metoda WriteAttributeString změní identifikátor URI oboru názvů pro předponu "x" z "123" na "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()
  

  Kód vygeneruje následující řetězec XML:

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

• Při zápisu atributů nebo prvků zadejte předponu oboru názvů. Mnoho metod používaných k zápisu elementů a atributů vám to umožňuje. Například metoda WriteStartElement(String, String, String) zapíše počáteční značku a přidruží ji k zadanému oboru názvů a předponě.

Zápis zadaných dat

Metoda WriteValue přijímá objekt CLR (Common Language Runtime), převede vstupní hodnotu na řetězcovou reprezentaci podle pravidel převodu datového typu XSD (XML Schema Definition Language) a zapíše ji pomocí WriteString metody. To je jednodušší než použití metod ve XmlConvert třídě k převodu zadaných dat na řetězcovou hodnotu před jejich zápisem.

Při zápisu do textu se zadaná hodnota serializuje na text pomocí XmlConvert pravidel pro tento typ schématu.

Výchozí datové typy XSD, které odpovídají typům CLR, najdete v WriteValue metodě.

Dá XmlWriter se také použít k zápisu do úložiště dat XML. Například může třída XPathNavigator vytvořit objekt XmlWriter, který pak vytvoří uzly pro objekt XmlDocument. Pokud má úložiště dat k dispozici informace o schématu, WriteValue metoda vyvolá výjimku, pokud se pokusíte převést na typ, který není povolen. Pokud úložiště dat nemá k dispozici informace o schématu, WriteValue metoda považuje všechny hodnoty za xsd:anySimpleType typ.

Zavření zapisovače XML

Když použijete XmlWriter metody pro výstup XML, elementy a atributy nebudou zapsány, dokud metodu Close nezavoláte. Pokud například používáte XmlWriter k naplnění objektu XmlDocument , nebudete moct v cílovém dokumentu zobrazit zapsané prvky a atributy, dokud instanci nezavřete XmlWriter .

Asynchronní programování

XmlWriter Většina metod má asynchronní protějšky, které mají na konci názvů metod "Async". Například asynchronní ekvivalent WriteAttributeString je WriteAttributeStringAsync.

Pro metodu WriteValue , která nemá asynchronní protějšek, převeďte návratovou hodnotu na řetězec a použijte metodu WriteStringAsync .

Bezpečnostní aspekty

Při práci s XmlWriter třídou zvažte následující skutečnosti:

• Výjimky vyvolané XmlWriter můžou odhalit informace o cestě, které nechcete, aby se dostaly až k aplikaci. Vaše aplikace musí zachytit výjimky a odpovídajícím způsobem je zpracovat.

• XmlWriterneověřuje žádná data, která jsou předána metoděWriteDocType.WriteRaw Těmto metodám byste neměli předávat libovolná data.

Viz také

• Dokumenty a data XML