System.Xml.XmlWriter-klass

Klassen XmlWriter skriver XML-data till en ström, fil, textläsare eller sträng. Den stöder rekommendationer för W3C Extensible Markup Language (XML) 1.0 (fjärde utgåvan) och Namnområden i XML 1.0 (tredje utgåvan).

Med klassens XmlWriter medlemmar kan du:

• Kontrollera att tecknen är juridiska XML-tecken och att element- och attributnamn är giltiga XML-namn.
• Kontrollera att XML-dokumentet är välformat.
• Koda binära byte som Base64 eller BinHex och skriv ut den resulterande texten.
• Skicka värden med vanliga språkkörningstyper i stället för strängar för att undvika att behöva utföra värdekonverteringar manuellt.
• Skriv flera dokument till en utdataström.
• Skriv giltiga namn, kvalificerade namn och namntoken.

Skapa en XML-skrivare

För att skapa en XmlWriter instans, använd XmlWriter.Create-metoden. Om du vill ange den uppsättning funktioner som du vill aktivera på XML-skrivaren skickar du en XmlWriterSettings till Create -metoden. Annars används standardinställningarna. Mer information finns på referenssidorna Create .

Ange utdataformatet

Klassen XmlWriterSettings innehåller flera egenskaper som styr hur XmlWriter utdata formateras:

Egenskaperna Indent och IndentChars styr hur obetydligt tomt utrymme formateras. Om du till exempel vill dra in elementnoder:

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 Använd för att skriva varje attribut på en ny rad med en extra indragsnivå:

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)

Dataöverensstämmelse

En XML-skrivare använder två egenskaper från XmlWriterSettings klassen för att söka efter datakompatibilitet:

• Egenskapen CheckCharacters instruerar XML-skrivaren att kontrollera tecken och utlösa ett XmlException undantag om några tecken ligger utanför det juridiska intervallet, enligt definitionen i W3C.

• Egenskapen ConformanceLevel konfigurerar XML-skrivaren för att kontrollera att dataströmmen som skrivs följer reglerna för ett välformat XML 1.0-dokument eller dokumentfragment, enligt W3C-definitionen. De tre överensstämmelsenivåerna beskrivs i följande tabell. Standardvärdet är Document. Mer information finns i egenskapen XmlWriterSettings.ConformanceLevel och System.Xml.ConformanceLevel-uppräkningen.

  Nivå	Beskrivning
  Document	XML-utdata överensstämmer med reglerna för ett välformat XML 1.0-dokument och kan bearbetas av alla processorer som uppfyller kraven.
  Fragment	XML-utdata överensstämmer med reglerna för ett välformat XML 1.0-dokumentfragment.
  Auto	XML-skrivaren avgör vilken nivå av konformationskontroll som ska tillämpas (dokument eller fragment) baserat på inkommande data.

Skrivelementen

Du kan använda följande XmlWriter metoder för att skriva elementnoder. Exempel finns i metoderna i listan.

Skriv attribut

Du kan använda följande XmlWriter metoder för att skriva attribut på elementnoder. Dessa metoder kan också användas för att skapa namnområdesdeklarationer för ett element, enligt beskrivningen i nästa avsnitt.

Hantera namnområden

Namnområden används för att kvalificera namn på element och attribut i ett XML-dokument. Namnområdesprefix associerar element och attribut med namnområden, som i sin tur är associerade med URI-referenser. Namnområden skapar element- och attributnamns unikhet i ett XML-dokument.

Underhåller XmlWriter en namnområdesstack som motsvarar alla namnområden som definierats i det aktuella namnområdesomfånget. När du skriver element och attribut kan du använda namnområden på följande sätt:

• Deklarera namnområden manuellt med hjälp WriteAttributeString av metoden . Detta kan vara användbart när du vet hur du bäst optimerar antalet namnområdesdeklarationer. Ett exempel finns i WriteAttributeString(String, String, String, String) metoden.

• Åsidosätt den aktuella namnområdesdeklarationen med ett nytt namnområde. I följande kod WriteAttributeString ändrar metoden namnområdes-URI:n för prefixet "x" från "123" till "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()
  

  Koden genererar följande XML-sträng:

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

• Ange ett namnområdesprefix när du skriver attribut eller element. Många av de metoder som används för att skriva element och attribut gör att du kan göra detta. Metoden skriver till exempel WriteStartElement(String, String, String) en starttagg och associerar den med ett angivet namnområde och prefix.

Skriva inskrivna data

Metoden WriteValue accepterar ett CLR-objekt (Common Language Runtime), konverterar indatavärdet till dess strängrepresentation enligt konverteringsregler för XML-schemadefinitionsspråk (XSD) och skriver ut det med hjälp WriteString av metoden. Det här är enklare än att använda metoderna i XmlConvert klassen för att konvertera de inskrivna data till ett strängvärde innan du skriver ut dem.

När du skriver till text serialiseras det inskrivna värdet till text med hjälp av reglerna för den XmlConvert schematypen.

För XSD-standarddatatyper som motsvarar CLR-typer, se WriteValue metoden.

XmlWriter Kan också användas för att skriva till ett XML-datalager. Klassen kan till exempel XPathNavigator skapa ett XmlWriter objekt för att skapa noder för ett XmlDocument objekt. Om datalagret har tillgänglig WriteValue schemainformation utlöser metoden ett undantag om du försöker konvertera till en typ som inte är tillåten. Om datalagret inte har någon tillgänglig WriteValue schemainformation behandlar metoden alla värden som en xsd:anySimpleType typ.

Stäng XML-skrivaren

När du använder metoderna XmlWriter för att producera XML skrivs inte elementen och attributen förrän du anropar metoden Close. Om du till exempel använder XmlWriter för att fylla i ett XmlDocument objekt kan du inte se de skrivna elementen och attributen i måldokumentet förrän du stänger instansen XmlWriter .

Asynkron programmering

De flesta av XmlWriter metoderna har asynkrona motsvarigheter som har "Async" i slutet av sina metodnamn. Till exempel är den asynkrona motsvarigheten till WriteAttributeStringWriteAttributeStringAsync.

WriteValue För metoden, som inte har någon asynkron motsvarighet, konverterar du returvärdet till en sträng och använder WriteStringAsync metoden i stället.

Säkerhetsfrågor

Tänk på följande när du arbetar med XmlWriter klassen:

• Undantag som genereras av XmlWriter kan avslöja sökvägsinformation som du inte vill ska bubblas upp till appen. Appen måste fånga upp undantag och bearbeta dem på rätt sätt.

• XmlWriter verifierar inte några data som skickas till WriteDocType metoden eller WriteRaw . Du bör inte skicka godtyckliga data till dessa metoder.