Klasse System.Xml.XmlWriter

De XmlWriter klasse schrijft XML-gegevens naar een stroom, bestand, tekstlezer of tekenreeks. Het ondersteunt de W3C Extensible Markup Language (XML) 1.0 (vierde editie) en naamruimten in aanbevelingen voor XML 1.0 (derde editie).

Met de leden van de XmlWriter klas kunt u het volgende doen:

  • Controleer of de tekens juridische XML-tekens zijn en dat element- en kenmerknamen geldige XML-namen zijn.
  • Controleer of het XML-document goed is opgemaakt.
  • Codeer binaire bytes als Base64 of BinHex en schrijf de resulterende tekst uit.
  • Geef waarden door met behulp van algemene typen taalruntime in plaats van tekenreeksen, om te voorkomen dat u handmatig waardeconversies moet uitvoeren.
  • Schrijf meerdere documenten naar één uitvoerstroom.
  • Schrijf geldige namen, gekwalificeerde namen en naamtokens.

Een XML-schrijver maken

Als u een XmlWriter exemplaar wilt maken, gebruikt u de XmlWriter.Create methode. Als u de set functies wilt opgeven die u wilt inschakelen voor de XML-schrijver, geeft u een XmlWriterSettings door aan de Create methode. Anders worden standaardinstellingen gebruikt. Zie de Create referentiepagina's voor meer informatie.

De uitvoerindeling opgeven

De XmlWriterSettings klasse bevat verschillende eigenschappen die bepalen hoe XmlWriter uitvoer wordt opgemaakt:

Vastgoed Beschrijving
Encoding Hiermee geeft u de te gebruiken tekstcodering op. De standaardwaarde is Encoding.UTF8.
Indent Hiermee wordt aangegeven of u elementen wilt laten inspringen. De standaardwaarde is false (geen inspringing).
IndentChars Hiermee geeft u de tekenreeks die moet worden gebruikt bij het inspringen. De standaardwaarde is twee spaties.
NewLineChars Hiermee specificeert u de tekenreeks die wordt gebruikt voor regeleinden. De standaardwaarde is \r\n (regelterugloop, regelfeed) voor niet-Unix-platforms en \n (regelfeed) voor Unix-platforms.
NewLineHandling Hiermee geeft u op hoe nieuwe regeltekens moeten worden verwerkt.
NewLineOnAttributes Hiermee wordt aangegeven of kenmerken op een nieuwe regel moeten worden geschreven. Indent moet worden ingesteld op true wanneer u deze eigenschap gebruikt. De standaardwaarde is false.
OmitXmlDeclaration Geeft aan of een XML-declaratie moet worden geschreven. De standaardwaarde is false.

De Indent en IndentChars eigenschappen bepalen hoe onbelangrijke witruimte wordt opgemaakt. Om bijvoorbeeld elementknooppunten in te laten springen:

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)

Gebruik het NewLineOnAttributes kenmerk om elk kenmerk op een nieuwe regel te schrijven met één extra inspringingsniveau:

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)

Gegevensconformance

Een XML-schrijver gebruikt twee eigenschappen van de XmlWriterSettings klasse om te controleren op gegevensconformantie:

  • Met CheckCharacters de eigenschap wordt de XML-schrijver geïnstrueerd om tekens te controleren en een XmlException uitzondering te genereren als tekens buiten het juridische bereik vallen, zoals gedefinieerd door de W3C.

  • De ConformanceLevel eigenschap configureert de XML-schrijver om te controleren of de stroom die wordt geschreven voldoet aan de regels voor een goed opgemaakt XML 1.0-document of -documentfragment, zoals gedefinieerd door de W3C. De drie nalevingsniveaus worden beschreven in de volgende tabel. De standaardwaarde is Document. Zie de XmlWriterSettings.ConformanceLevel eigenschap en de System.Xml.ConformanceLevel opsomming voor meer informatie.

    Niveau Beschrijving
    Document De XML-uitvoer voldoet aan de regels voor een goed opgemaakt XML 1.0-document en kan worden verwerkt door elke conforme processor.
    Fragment De XML-uitvoer voldoet aan de regels voor een goed opgemaakt XML 1.0-documentfragment.
    Auto De XML-schrijver bepaalt welk niveau van conformatiecontrole moet worden toegepast (document of fragment) op basis van de binnenkomende gegevens.

Elementen schrijven

U kunt de volgende XmlWriter methoden gebruiken om elementknooppunten te schrijven. Zie de vermelde methoden voor voorbeelden.

Gebruik Tot
WriteElementString Een volledig elementknooppunt schrijven, inclusief een tekenreekswaarde.
WriteStartElement Een elementwaarde schrijven met behulp van meerdere methodeaanroepen. U kunt bijvoorbeeld aanroepen WriteValue om een getypte waarde te schrijven, WriteCharEntity een tekenentiteit te schrijven, WriteAttributeString een kenmerk te schrijven of u kunt een onderliggend element schrijven. Dit is een geavanceerdere versie van de WriteElementString methode.

Als u het element wilt sluiten, roept u de WriteEndElement of WriteFullEndElement methode aan.
WriteNode Als u een elementknooppunt wilt kopiëren dat zich op de huidige positie van een XmlReader of XPathNavigator object bevindt. Wanneer deze wordt aangeroepen, wordt alles van het bronobject naar het XmlWriter exemplaar gekopieerd.

Kenmerken schrijven

U kunt de volgende XmlWriter methoden gebruiken om kenmerken op elementknooppunten te schrijven. Deze methoden kunnen ook worden gebruikt om naamruimtedeclaraties te maken voor een element, zoals beschreven in de volgende sectie.

Gebruik Tot
WriteAttributeString Een volledig kenmerkknooppunt schrijven, inclusief een tekenreekswaarde.
WriteStartAttribute Als u de kenmerkwaarde wilt schrijven met behulp van meerdere methode-aanroepen. U kunt bijvoorbeeld aanroepen WriteValue om een getypte waarde te schrijven. Dit is een geavanceerdere versie van de WriteElementString methode.

Als u het element wilt sluiten, roept u de WriteEndAttribute methode aan.
WriteAttributes Als u alle kenmerken op de huidige positie van een XmlReader object wilt kopiëren. De kenmerken die zijn geschreven, zijn afhankelijk van het type knooppunt waarop de lezer momenteel is ingesteld:

- Voor een attribuutknooppunt schrijft het het huidige attribuut en vervolgens de rest van de attributen tot aan de afsluitende tag van het element.
- Voor een elementknooppunt worden alle kenmerken geschreven die zijn opgenomen in het element.
- Voor een XML-declaratieknooppunt worden alle kenmerken in de declaratie geschreven.
- Voor alle andere knooppunttypen genereert de methode een uitzondering.

Naamruimten verwerken

Naamruimten worden gebruikt om element- en kenmerknamen in een XML-document te kwalificeren. Naamruimtevoorvoegsels koppelen elementen en kenmerken aan naamruimten, die op hun beurt zijn gekoppeld aan URI-verwijzingen. Naamruimten maken uniekheid van element- en kenmerknamen in een XML-document.

Het XmlWriter onderhoudt een naamruimtestack die overeenkomt met alle naamruimten die zijn gedefinieerd in het huidige naamruimtebereik. Wanneer u elementen en kenmerken schrijft, kunt u op de volgende manieren naamruimten gebruiken:

  • Declareer naamruimten handmatig met behulp van de WriteAttributeString methode. Dit kan handig zijn wanneer u weet hoe u het aantal naamruimtedeclaraties het beste kunt optimaliseren. Zie de WriteAttributeString(String, String, String, String) methode voor een voorbeeld.

  • Overschrijf de huidige naamruimtedeclaratie met een nieuwe naamruimte. In de volgende code wijzigt de WriteAttributeString methode de naamruimte-URI voor het "x" voorvoegsel van "123" in "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()

    De code genereert de volgende XML-tekenreeks:

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

  • Geef een naamruimtevoorvoegsel op bij het schrijven van kenmerken of elementen. Veel van de methoden die worden gebruikt voor het schrijven van elementen en kenmerken, stellen u in staat dit te doen. De methode schrijft bijvoorbeeld WriteStartElement(String, String, String) een starttag en koppelt deze aan een opgegeven naamruimte en voorvoegsel.

Getypte gegevens schrijven

De WriteValue methode accepteert een CLR-object (Common Language Runtime), converteert de invoerwaarde naar de tekenreeksweergave volgens de XSD-regels (XML Schema Definition Language) en schrijft deze uit met behulp van de WriteString methode. Dit is eenvoudiger dan het gebruik van de methoden in de XmlConvert klasse om de getypte gegevens te converteren naar een tekenreekswaarde voordat u deze uitschrijft.

Wanneer u naar tekst schrijft, wordt de getypte waarde geserialiseerd naar tekst met behulp van de XmlConvert regels voor dat schematype.

Zie de WriteValue methode voor standaard XSD-gegevenstypen die overeenkomen met CLR-typen.

De XmlWriter functie kan ook worden gebruikt om naar een XML-gegevensarchief te schrijven. De XPathNavigator klasse kan bijvoorbeeld een XmlWriter object maken om knooppunten voor een XmlDocument object te maken. Als er schemagegevens beschikbaar zijn in het gegevensarchief, genereert de WriteValue methode een uitzondering als u probeert te converteren naar een type dat niet is toegestaan. Als er geen schemagegevens beschikbaar zijn in het gegevensarchief, worden alle waarden als een WriteValue type behandeld met de xsd:anySimpleType methode.

De XML-schrijver sluiten

Wanneer u methoden gebruikt XmlWriter om XML uit te voeren, worden de elementen en kenmerken pas geschreven als u de Close methode aanroept. Als u bijvoorbeeld een XmlWriter object gebruikt om een XmlDocument object te vullen, kunt u de geschreven elementen en kenmerken in het doeldocument pas zien als u het XmlWriter exemplaar sluit.

Asynchroon programmeren

XmlWriter De meeste methoden hebben asynchrone tegenhangers die 'Async' aan het einde van hun methodenamen hebben. Bijvoorbeeld, het asynchrone equivalent van WriteAttributeString is WriteAttributeStringAsync.

Voor de WriteValue methode, die geen asynchrone tegenhanger heeft, converteert u de retourwaarde naar een tekenreeks en gebruikt u in plaats daarvan de WriteStringAsync methode.

Beveiligingsoverwegingen

Houd rekening met het volgende bij het werken met de XmlWriter klasse:

  • Uitzonderingen die door XmlWriter worden gegooid, kunnen padinformatie onthullen die u niet naar de app wilt laten doorgaan. Uw app moet uitzonderingen onderscheppen en ze op de juiste manier verwerken.

  • XmlWriter valideert geen gegevens die worden doorgegeven aan de WriteDocType of WriteRaw methode. U mag geen willekeurige gegevens doorgeven aan deze methoden.

  • Last updated on