System.Xml.XmlWriter – třída

Článek
01/04/2024

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:

Vlastnost	Popis
Encoding	Určuje kódování textu, které se má použít. Výchozí hodnota je `Encoding.UTF8`.
Indent	Určuje, zda se mají odsadit prvky. Výchozí hodnota je `false` (bez odsazení).
IndentChars	Určuje řetězec znaků, který se má použít při odsazení. Výchozí hodnota je dvě mezery.
NewLineChars	Určuje znakový řetězec, který se má použít pro konce řádků. Výchozí hodnota je `\r\n` (návrat na začátek řádku, odřádkování) pro jiné platformy než Unix a `\n` (podávání řádků) pro platformy Unix.
NewLineHandling	Určuje, jak zpracovat znaky nového řádku.
NewLineOnAttributes	Určuje, zda se mají atributy zapisovat na nový řádek. Indent při použití této vlastnosti by měla být nastavena na `true` hodnotu. Výchozí hodnota je `false`.
OmitXmlDeclaration	Určuje, zda se má zapsat deklarace XML. Výchozí hodnota je `false`.

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.

Používání	To
WriteElementString	Zapište celý uzel prvku, včetně řetězcové hodnoty.
WriteStartElement	K zápisu hodnoty prvku pomocí více volání metod. Můžete například volat WriteValue k zápisu zadané hodnoty, WriteCharEntity k zápisu entity znaku, WriteAttributeString k zápisu atributu nebo k zápisu podřízeného prvku. Jedná se o sofistikovanější verzi WriteElementString metody. Pokud chcete prvek zavřít, zavoláte metodu nebo WriteFullEndElement metoduWriteEndElement.
WriteNode	Chcete-li zkopírovat uzel prvku nalezený na aktuální pozici objektu nebo XPathNavigator objektuXmlReader. Při zavolání zkopíruje vše ze zdrojového objektu XmlWriter do instance.

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.

Používání	To
WriteAttributeString	Pokud chcete napsat celý uzel atributu, včetně řetězcové hodnoty.
WriteStartAttribute	Chcete-li napsat hodnotu atributu pomocí více volání metody. Můžete například volat WriteValue zápis zadané hodnoty. Jedná se o sofistikovanější verzi WriteElementString metody. Pokud chcete prvek zavřít, zavoláte metodu WriteEndAttribute .
WriteAttributes	Chcete-li zkopírovat všechny atributy nalezené na aktuální pozici objektu XmlReader . Atributy, které jsou zapsány, závisí na typu uzlu, na kterém je čtenář aktuálně umístěn: – U uzlu atributu zapíše aktuální atribut a zbytek atributů, dokud se nezavírá značka elementu. – Pro uzel elementu zapíše všechny atributy obsažené elementem. - Pro uzel deklarace XML zapíše všechny atributy v deklaraci. – Pro všechny ostatní typy uzlů vyvolá metoda výjimku.

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.