System.Xml.XmlWriter osztály

Az XmlWriter osztály XML-adatokat ír streambe, fájlba, szövegolvasóba vagy sztringbe. Támogatja a W3C Bővíthető Jelölőnyelv (XML) 1.0 (negyedik kiadás) és XML Nevek Térben 1.0 (harmadik kiadás) ajánlásokat.

Az XmlWriter osztály tagjai lehetővé teszik, hogy Ön:

  • Ellenőrizze, hogy a karakterek jogi XML-karakterek-e, és hogy az elem- és attribútumnevek érvényes XML-nevek-e.
  • Ellenőrizze, hogy az XML-dokumentum megfelelően van-e formázva.
  • Bináris bájtok kódolása Base64 vagy BinHex formátumban, és írja ki az eredményül kapott szöveget.
  • Adjon át értékeket sztringek helyett gyakori nyelvi futtatókörnyezet-típusok használatával, hogy ne kelljen manuálisan értékkonvertálást végeznie.
  • Több dokumentum írása egy kimeneti streambe.
  • Írjon érvényes neveket, minősített neveket és név jogkivonatokat.

XML-író létrehozása

Ahhoz, hogy létrehozzon egy példányt, használja a XmlWriter metódust XmlWriter.Create. Ha meg szeretné adni az XML-írón engedélyezni kívánt funkciók készletét, adja meg XmlWriterSettings a Create metódusnak. Ellenkező esetben a rendszer az alapértelmezett beállításokat használja. Részletekért tekintse meg a Create referenciaoldalakat.

Adja meg a kimeneti formátumot

Az XmlWriterSettings osztály számos tulajdonságot tartalmaz, amelyek a kimenet formázását szabályozzák XmlWriter :

Ingatlan Leírás
Encoding Megadja a használni kívánt szövegkódolást. Az alapértelmezett érték a Encoding.UTF8.
Indent Azt jelzi, hogy be kell-e húzni az elemeket. Az alapértelmezett érték false (nincs behúzás).
IndentChars Megadja a behúzáskor használni kívánt karaktersztringet. Az alapértelmezett érték két szóköz.
NewLineChars Megadja a sortörésekhez használandó karaktersztringet. Az alapértelmezett érték ( \r\n kocsivissza, vonalcsatorna) a nem Unix-platformok esetében, a \n Unix-platformok esetében pedig (vonalcsatorna).
NewLineHandling Megadja, hogyan kell kezelni az új vonal karaktereit.
NewLineOnAttributes Azt jelzi, hogy attribútumokat kell-e írni egy új sorban. A tulajdonság használatakor Indent beállítását true -re kell végezni. Az alapértelmezett érték a false.
OmitXmlDeclaration Azt jelzi, hogy XML-deklarációt kell-e írni. Az alapértelmezett érték a false.

Az Indent és IndentChars a tulajdonságok szabályozzák, hogy milyen jelentéktelen üres terület legyen formázva. Elemcsomópontok behúzása például:

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)

NewLineOnAttributes Az attribútumokat egy új sorba írhatja egy további behúzási szinttel:

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)

Adatmegformálás

Az XML-írók az osztály két tulajdonságát használják az XmlWriterSettings adatmegformálás ellenőrzéséhez:

  • A CheckCharacters tulajdonság arra utasítja az XML-írót, hogy ellenőrizze a karaktereket, és kivételt XmlException okoz, ha bármely karakter a W3C által meghatározott jogi tartományon kívül esik.

  • A ConformanceLevel tulajdonság úgy konfigurálja az XML-írót, hogy ellenőrizze, hogy a megírt stream megfelel-e a W3C által meghatározott, jól formázott XML 1.0-dokumentum vagy dokumentumtöredék szabályainak. A három megfelelési szintet az alábbi táblázat ismerteti. Az alapértelmezett érték a Document. Részletekért tekintse meg a XmlWriterSettings.ConformanceLevel tulajdonságot és az enumerálást System.Xml.ConformanceLevel .

    szint Leírás
    Document Az XML-kimenet megfelel egy jól formázott XML 1.0-dokumentum szabályainak, és bármely megfelelő feldolgozó feldolgozhatja.
    Fragment Az XML-kimenet megfelel egy jól formázott XML 1.0-dokumentumtöredék szabályainak.
    Auto Az XML-író határozza meg, hogy a bejövő adatok alapján milyen szintű megfelelőség-ellenőrzést (dokumentumot vagy töredéket) kell alkalmazni.

Elemek írása

Az elemcsomópontok írásához az alábbi XmlWriter módszereket használhatja. Példákért tekintse meg a felsorolt módszereket.

Használd Há
WriteElementString Írjon egy teljes elemcsomópontot, beleértve egy sztringértéket is.
WriteStartElement Elemérték írása több metódushívással. Meghívhat WriteValue például beírt érték írására, WriteCharEntity karakterentitás írására, WriteAttributeString attribútum írására, vagy gyermekelem írására. Ez a módszer kifinomultabb verziója WriteElementString .

Az elem bezárásához hívja meg a WriteEndElement vagy a WriteFullEndElement metódusokat.
WriteNode Egy elemcsomópont másolása, amely az XmlReader vagy XPathNavigator objektumok aktuális helyén található. Amikor meghívják, mindent átmásol a forrásobjektumból az XmlWriter példányba.

Attribútumok írása

Az alábbi XmlWriter módszerekkel attribútumokat írhat az elemcsomópontokra. Ezekkel a módszerekkel névtérdeklarációkat is létrehozhat egy elemen, ahogyan azt a következő szakaszban is ismertetjük.

Használd Há
WriteAttributeString Egy teljes attribútumcsomópont írása, beleértve egy sztringértéket is.
WriteStartAttribute Az attribútumérték írása több metódushívással. Például meghívhatja a WriteValue függvényt egy típusos érték írására. Ez a módszer kifinomultabb verziója WriteElementString .

Az elem bezárásához hívja meg a metódust WriteEndAttribute .
WriteAttributes Az objektum aktuális helyén található összes attribútum másolása XmlReader . Az írott attribútumok attól függenek, hogy az olvasó milyen típusú csomóponton van jelenleg elhelyezve:

– Egy attribútumcsomópont esetében az aktuális attribútumot írja, majd a többi attribútumot az elem záró címkéjéig.
- Elemcsomópont esetén az elem által tartalmazott összes attribútumot megírja.
– XML-deklarációs csomópont esetén a deklarációban szereplő összes attribútumot megírja.
– Az összes többi csomóponttípus esetében a metódus kivételt jelez.

Névterek kezelése

A névterek az XML-dokumentumok elem- és attribútumneveinek minősítésére szolgálnak. A névtér-előtagok elemeket és attribútumokat társítanak a névterekhez, amelyek viszont URI-hivatkozásokhoz vannak társítva. A névterek elem- és attribútumnév-egyediséget hoznak létre egy XML-dokumentumban.

A XmlWriter névtérverem az aktuális névtér-hatókörben definiált összes névtérnek felel meg. Elemek és attribútumok írásakor a következő módokon használhatja a névtereket:

  • A metódus használatával manuálisan deklarálhatja a WriteAttributeString névtereket. Ez akkor lehet hasznos, ha tudja, hogyan optimalizálhatja legjobban a névtér-deklarációk számát. Például tekintse meg a metódust WriteAttributeString(String, String, String, String) .

  • Felülbírálja az aktuális névtér-deklarációt egy új névtérrel. A következő kódban a WriteAttributeString metódus az "x" előtag névterének URI-ját "123"-ről "abc"-ra módosítja.

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

    A kód a következő XML-sztringet hozza létre:

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

  • Adjon meg egy névtérelőtagot attribútumok vagy elemek írásakor. Az elemek és attribútumok írásához használt módszerek közül sok lehetővé teszi ezt. A metódus például egy kezdőcímkét ír, WriteStartElement(String, String, String) és hozzárendeli egy megadott névtérhez és előtaghoz.

Beírt adatok írása

A WriteValue metódus elfogad egy közös nyelvi futtatókörnyezeti (CLR) objektumot, átalakítja a bemeneti értéket az XML-sémadefiníciós nyelv (XSD) adattípus-konverziós szabályainak megfelelő sztringre, és a WriteString metódussal kiírja. Ez egyszerűbb, mint az XmlConvert osztály metódusainak használata a beírt adatok sztringértékké alakításához, mielőtt kiírta volna.

Szövegbe írásakor a rendszer a beírt értéket szöveggé szerializálja az XmlConvert adott sématípus szabályainak használatával.

A CLR-típusoknak megfelelő alapértelmezett XSD-adattípusok esetében tekintse meg a metódust WriteValue .

Az XmlWriter XML-adattárba való íráshoz is használható. Az osztály például XPathNavigator létrehozhat egy XmlWriter objektumot, amely csomópontokat hoz létre egy XmlDocument objektumhoz. Ha az adattárban rendelkezésre állnak sémainformációk, a WriteValue metódus kivételt jelent, ha nem engedélyezett típusra próbál konvertálni. Ha az adattár nem rendelkezik rendelkezésre álló sémainformációkkal, a metódus az WriteValue összes értéket típusként xsd:anySimpleType kezeli.

Az XML-író bezárása

Ha metódusokat használ XmlWriter az XML-kimenethez, az elemek és attribútumok csak akkor lesznek megírva, ha meghívja a metódust Close . Ha például a XmlWriter használatával tölt fel egy XmlDocument objektumot, a cél dokumentum írott elemeit és attribútumait csak akkor fogja látni, ha bezárja a XmlWriter példányt.

Aszinkron programozás

A metódusok többsége aszinkron XmlWriter megfelelőkkel rendelkezik, amelyek a metódusnevek végén "Async"-et használnak. Az WriteAttributeString aszinkron megfelelője például a WriteAttributeStringAsync.

Az aszinkron WriteValue megfelelővel nem rendelkező metódus esetében konvertálja a visszatérési értéket sztringgé, és használja helyette a metódust WriteStringAsync .

Biztonsági szempontok

Az osztály használatakor vegye figyelembe a XmlWriter következőket:

  • A XmlWriter által dobott kivételek felfedhetik az elérési út információit, amelyeket nem szeretne, hogy eljussanak az alkalmazásba. Az alkalmazásnak ki kell fognia a kivételeket, és megfelelően kell feldolgoznia őket.

  • XmlWriter nem ellenőrzi a WriteDocType vagy WriteRaw metódusnak átadott adatokat. Ezekhez a módszerekhez nem szabad tetszőleges adatokat átadni.

  • Last updated on