System.Xml.XmlWriter – třída

Třída XmlWriter zapisuje data XML do datového proudu, souboru, textové čtečky nebo řetězce. Podporuje W3C Extensible Markup Language (XML) 1.0 (čtvrtá edice) a obory názvů v doporučeníCH XML 1.0 (třetí edice).

Č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ů modulu runtime jazyka místo řetězců, abyste se vyhnuli ruční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 tokeny názvů.

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 určují IndentChars , jak nevýznamné prázdné znaky jsou formátovány. 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 k zápisu NewLineOnAttributes každého atributu na nový řádek s jednou další úrovní odsazení:

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. Podrobnosti naleznete v XmlWriterSettings.ConformanceLevel vlastnosti a výčtu System.Xml.ConformanceLevel .

  Level	Popis
  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 elementů

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í oborů názvů

Obory názvů slouží k opravňujícím názvům elementů a atributů v dokumentu XML. Předpony oboru názvů přidružují prvky a atributy k oborům názvů, které jsou zase přidružené k odkazům URI. Obory názvů vytvářejí jedinečnost názvu elementu a atributu v dokumentu XML.

Udržuje XmlWriter zásobník oboru názvů, který odpovídá všem oborům názvů definovaným v aktuálním 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. To může 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ě.

• Přepište aktuální deklaraci oboru názvů novým oborem názvů. V následujícím kódu WriteAttributeString změní metoda 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. Metoda například 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. Třída může například XPathNavigator vytvořit XmlWriter objekt pro vytvoření uzlů pro XmlDocument objekt. 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 bubliny zobrazovaly v 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.