Export (0) Print
Expand All

XmlWriter Class

Represents a writer that provides a fast, non-cached, forward-only way to generate streams or files that contain XML data.

System.Object
  System.Xml.XmlWriter

Namespace:  System.Xml
Assemblies:   System.Xml.ReaderWriter (in System.Xml.ReaderWriter.dll)
  System.Xml (in System.Xml.dll)

public abstract class XmlWriter : IDisposable

The XmlWriter type exposes the following members.

  NameDescription
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsXmlWriterInitializes a new instance of the XmlWriter class.
Top

  NameDescription
Public propertySupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsSettingsGets the XmlWriterSettings object used to create this XmlWriter instance.
Public propertySupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStateWhen overridden in a derived class, gets the state of the writer.
Public propertySupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsXmlLangWhen overridden in a derived class, gets the current xml:lang scope.
Public propertySupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsXmlSpaceWhen overridden in a derived class, gets an XmlSpace representing the current xml:space scope.
Top

  NameDescription
Public methodSupported by the XNA FrameworkCloseWhen overridden in a derived class, closes this stream and the underlying stream.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(Stream)Creates a new XmlWriter instance using the specified stream.
Public methodStatic memberSupported by the XNA FrameworkCreate(String)Creates a new XmlWriter instance using the specified filename.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(StringBuilder)Creates a new XmlWriter instance using the specified StringBuilder.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(TextWriter)Creates a new XmlWriter instance using the specified TextWriter.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(XmlWriter)Creates a new XmlWriter instance using the specified XmlWriter object.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(Stream, XmlWriterSettings)Creates a new XmlWriter instance using the stream and XmlWriterSettings object.
Public methodStatic memberSupported by the XNA FrameworkCreate(String, XmlWriterSettings)Creates a new XmlWriter instance using the filename and XmlWriterSettings object.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(StringBuilder, XmlWriterSettings)Creates a new XmlWriter instance using the StringBuilder and XmlWriterSettings objects.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(TextWriter, XmlWriterSettings)Creates a new XmlWriter instance using the TextWriter and XmlWriterSettings objects.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreate(XmlWriter, XmlWriterSettings)Creates a new XmlWriter instance using the specified XmlWriter and XmlWriterSettings objects.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsDispose()Releases all resources used by the current instance of the XmlWriter class.
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsDispose(Boolean)Releases the unmanaged resources used by the XmlWriter and optionally releases the managed resources.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsFlushWhen overridden in a derived class, flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream.
Public methodSupported in .NET for Windows Store appsFlushAsyncAsynchronously flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsLookupPrefixWhen overridden in a derived class, returns the closest prefix defined in the current namespace scope for the namespace URI.
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteAttributesWhen overridden in a derived class, writes out all the attributes found at the current position in the XmlReader.
Public methodSupported in .NET for Windows Store appsWriteAttributesAsyncAsynchronously writes out all the attributes found at the current position in the XmlReader.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteAttributeString(String, String)When overridden in a derived class, writes out the attribute with the specified local name and value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteAttributeString(String, String, String)When overridden in a derived class, writes an attribute with the specified local name, namespace URI, and value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteAttributeString(String, String, String, String)When overridden in a derived class, writes out the attribute with the specified prefix, local name, namespace URI, and value.
Public methodSupported in .NET for Windows Store appsWriteAttributeStringAsyncAsynchronously writes out the attribute with the specified prefix, local name, namespace URI, and value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteBase64When overridden in a derived class, encodes the specified binary bytes as Base64 and writes out the resulting text.
Public methodSupported in .NET for Windows Store appsWriteBase64AsyncAsynchronously encodes the specified binary bytes as Base64 and writes out the resulting text.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteBinHexWhen overridden in a derived class, encodes the specified binary bytes as BinHex and writes out the resulting text.
Public methodSupported in .NET for Windows Store appsWriteBinHexAsyncAsynchronously encodes the specified binary bytes as BinHex and writes out the resulting text.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteCDataWhen overridden in a derived class, writes out a <![CDATA[...]]> block containing the specified text.
Public methodSupported in .NET for Windows Store appsWriteCDataAsyncAsynchronously writes out a <![CDATA[...]]> block containing the specified text.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteCharEntityWhen overridden in a derived class, forces the generation of a character entity for the specified Unicode character value.
Public methodSupported in .NET for Windows Store appsWriteCharEntityAsyncAsynchronously forces the generation of a character entity for the specified Unicode character value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteCharsWhen overridden in a derived class, writes text one buffer at a time.
Public methodSupported in .NET for Windows Store appsWriteCharsAsyncAsynchronously writes text one buffer at a time.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteCommentWhen overridden in a derived class, writes out a comment <!--...--> containing the specified text.
Public methodSupported in .NET for Windows Store appsWriteCommentAsyncAsynchronously writes out a comment <!--...--> containing the specified text.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteDocTypeWhen overridden in a derived class, writes the DOCTYPE declaration with the specified name and optional attributes.
Public methodSupported in .NET for Windows Store appsWriteDocTypeAsyncAsynchronously writes the DOCTYPE declaration with the specified name and optional attributes.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteElementString(String, String)Writes an element with the specified local name and value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteElementString(String, String, String)Writes an element with the specified local name, namespace URI, and value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteElementString(String, String, String, String)Writes an element with the specified prefix, local name, namespace URI, and value.
Public methodSupported in .NET for Windows Store appsWriteElementStringAsyncAsynchronously writes an element with the specified prefix, local name, namespace URI, and value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteEndAttributeWhen overridden in a derived class, closes the previous WriteStartAttribute call.
Protected methodSupported in .NET for Windows Store appsWriteEndAttributeAsyncAsynchronously closes the previous WriteStartAttribute call.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteEndDocumentWhen overridden in a derived class, closes any open elements or attributes and puts the writer back in the Start state.
Public methodSupported in .NET for Windows Store appsWriteEndDocumentAsyncAsynchronously closes any open elements or attributes and puts the writer back in the Start state.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteEndElementWhen overridden in a derived class, closes one element and pops the corresponding namespace scope.
Public methodSupported in .NET for Windows Store appsWriteEndElementAsyncAsynchronously closes one element and pops the corresponding namespace scope.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteEntityRefWhen overridden in a derived class, writes out an entity reference as &name;.
Public methodSupported in .NET for Windows Store appsWriteEntityRefAsyncAsynchronously writes out an entity reference as &name;.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteFullEndElementWhen overridden in a derived class, closes one element and pops the corresponding namespace scope.
Public methodSupported in .NET for Windows Store appsWriteFullEndElementAsyncAsynchronously closes one element and pops the corresponding namespace scope.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteNameWhen overridden in a derived class, writes out the specified name, ensuring it is a valid name according to the W3C XML 1.0 recommendation (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name).
Public methodSupported in .NET for Windows Store appsWriteNameAsyncAsynchronously writes out the specified name, ensuring it is a valid name according to the W3C XML 1.0 recommendation (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name).
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteNmTokenWhen overridden in a derived class, writes out the specified name, ensuring it is a valid NmToken according to the W3C XML 1.0 recommendation (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name).
Public methodSupported in .NET for Windows Store appsWriteNmTokenAsyncAsynchronously writes out the specified name, ensuring it is a valid NmToken according to the W3C XML 1.0 recommendation (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name).
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteNode(XmlReader, Boolean)When overridden in a derived class, copies everything from the reader to the writer and moves the reader to the start of the next sibling.
Public methodWriteNode(XPathNavigator, Boolean)Copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged.
Public methodSupported in .NET for Windows Store appsWriteNodeAsync(XmlReader, Boolean)Asynchronously copies everything from the reader to the writer and moves the reader to the start of the next sibling.
Public methodWriteNodeAsync(XPathNavigator, Boolean)Asynchronously copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteProcessingInstructionWhen overridden in a derived class, writes out a processing instruction with a space between the name and text as follows: <?name text?>.
Public methodSupported in .NET for Windows Store appsWriteProcessingInstructionAsyncAsynchronously writes out a processing instruction with a space between the name and text as follows: <?name text?>.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteQualifiedNameWhen overridden in a derived class, writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace.
Public methodSupported in .NET for Windows Store appsWriteQualifiedNameAsyncAsynchronously writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteRaw(String)When overridden in a derived class, writes raw markup manually from a string.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteRaw(Char[], Int32, Int32)When overridden in a derived class, writes raw markup manually from a character buffer.
Public methodSupported in .NET for Windows Store appsWriteRawAsync(String)Asynchronously writes raw markup manually from a string.
Public methodSupported in .NET for Windows Store appsWriteRawAsync(Char[], Int32, Int32)Asynchronously writes raw markup manually from a character buffer.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartAttribute(String)Writes the start of an attribute with the specified local name.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartAttribute(String, String)Writes the start of an attribute with the specified local name and namespace URI.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartAttribute(String, String, String)When overridden in a derived class, writes the start of an attribute with the specified prefix, local name, and namespace URI.
Protected methodSupported in .NET for Windows Store appsWriteStartAttributeAsyncAsynchronously writes the start of an attribute with the specified prefix, local name, and namespace URI.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartDocument()When overridden in a derived class, writes the XML declaration with the version "1.0".
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartDocument(Boolean)When overridden in a derived class, writes the XML declaration with the version "1.0" and the standalone attribute.
Public methodSupported in .NET for Windows Store appsWriteStartDocumentAsync()Asynchronously writes the XML declaration with the version "1.0".
Public methodSupported in .NET for Windows Store appsWriteStartDocumentAsync(Boolean)Asynchronously writes the XML declaration with the version "1.0" and the standalone attribute.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartElement(String)When overridden in a derived class, writes out a start tag with the specified local name.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartElement(String, String)When overridden in a derived class, writes the specified start tag and associates it with the given namespace.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartElement(String, String, String)When overridden in a derived class, writes the specified start tag and associates it with the given namespace and prefix.
Public methodSupported in .NET for Windows Store appsWriteStartElementAsyncAsynchronously writes the specified start tag and associates it with the given namespace and prefix.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStringWhen overridden in a derived class, writes the given text content.
Public methodSupported in .NET for Windows Store appsWriteStringAsyncAsynchronously writes the given text content.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteSurrogateCharEntityWhen overridden in a derived class, generates and writes the surrogate character entity for the surrogate character pair.
Public methodSupported in .NET for Windows Store appsWriteSurrogateCharEntityAsyncAsynchronously generates and writes the surrogate character entity for the surrogate character pair.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Boolean)Writes a Boolean value.
Public methodSupported by the XNA FrameworkWriteValue(DateTime)Writes a DateTime value.
Public methodSupported in .NET for Windows Store appsWriteValue(DateTimeOffset)Writes a DateTimeOffset value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Decimal)Writes a Decimal value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Double)Writes a Double value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Int32)Writes a Int32 value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Int64)Writes a Int64 value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Object)Writes the object value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(Single)Writes a single-precision floating-point number.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteValue(String)Writes a String value.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteWhitespaceWhen overridden in a derived class, writes out the given white space.
Public methodSupported in .NET for Windows Store appsWriteWhitespaceAsyncAsynchronously writes out the given white space.
Top

  NameDescription
Explicit interface implemetationPrivate methodSupported by the XNA FrameworkIDisposable.DisposeFor a description of this member, see IDisposable.Dispose.
Top

The XmlWriter class writes XML data to a stream, file, text reader, or string. It supports the W3C Extensible Markup Language (XML) 1.0 (fourth edition) and Namespaces in XML 1.0 (third edition) recommendations.

The members of the XmlWriter class enable you to:

  • Verify that the characters are legal XML characters and that element and attribute names are valid XML names.

  • Verify that the XML document is well-formed.

  • Encode binary bytes as Base64 or BinHex, and write out the resulting text.

  • Pass values by using common language runtime types instead of strings, to avoid having to manually perform value conversions.

  • Write multiple documents to one output stream.

  • Write valid names, qualified names, and name tokens.

In this section:

Creating an XML writer
Specifying the output format
Data conformance
Writing elements
Writing attributes
Handling namespaces
Writing typed data
Closing the XML writer
Asynchronous programming
Security considerations

Creating an XML writer

To create an XmlWriter instance, use the XmlWriter.Create method. To specify the set of features you want to enable on the XML writer, pass an XmlWriterSettings to the Create method. Otherwise, default settings are used. See the Create reference pages for details.

Specifying the output format

The XmlWriterSettings class includes several properties that control how XmlWriter output is formatted:

Property

Description

Encoding

Specifies the text encoding to use. The default is Encoding.UTF8.

Indent

Indicates whether to indent elements. The default is false (no indentation).

IndentChars

Specifies the character string to use when indenting. The default is two spaces.

NewLineChars

Specifies the character string to use for line breaks. The default is \r\n (carriage return, line feed).

NewLineHandling

Specifies how to handle newline characters.

NewLineOnAttributes

Indicates whether to write attributes on a new line. Indent should be set to true when using this property. The default is false.

OmitXmlDeclaration

Indicates whether to write an XML declaration. The default is false.

The Indent and IndentChars properties control how insignificant white space is formatted. For example, to indent element nodes:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Use the NewLineOnAttributes to write each attribute on a new line with one extra level of indentation:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Data conformance

An XML writer uses two properties from the XmlWriterSettings class to check for data conformance:

  • The CheckCharacters property instructs the XML writer to check characters and throw an XmlException exception if any characters are outside the legal range, as defined by the W3C.

  • The ConformanceLevel property configures the XML writer to check that the stream being written complies with the rules for a well-formed XML 1.0 document or document fragment, as defined by the W3C. The three conformance levels are described in the following table. The default is Document. For details, see the XmlWriterSettings.ConformanceLevel property and the System.Xml.ConformanceLevel enumeration.

    Level

    Description

    Document

    The XML output conforms to the rules for a well-formed XML 1.0 document and can be processed by any conforming processor.

    Fragment

    The XML output conforms to the rules for a well-formed XML 1.0 document fragment.

    Auto

    The XML writer determines which level of conformation checking to apply (document or fragment) based on the incoming data.

Writing elements

You can use the following XmlWriter methods to write element nodes. For examples, see the methods listed.

Use

To

WriteElementString

Write an entire element node, including a string value.

WriteStartElement

To write an element value by using multiple method calls. For example, you can call WriteValue to write a typed value, WriteCharEntity to write a character entity, WriteAttributeString to write an attribute, or you can write a child element. This is a more sophisticated version of the WriteElementString method.

To close the element, you call the WriteEndElement or WriteFullEndElement method.

WriteNode

To copy an element node found at the current position of an XmlReader or XPathNavigator object. When called, it copies everything from the source object to the XmlWriter instance.

Writing attributes

You can use the following XmlWriter methods to write attributes on element nodes. These methods can also be used to create namespace declarations on an element, as discussed in the next section.

Use

To

WriteAttributeString

To write an entire attribute node, including a string value.

WriteStartAttribute

To write the attribute value using multiple method calls. For example, you can call WriteValue to write a typed value. This is a more sophisticated version of the WriteElementString method.

To close the element, you call the WriteEndAttribute method.

WriteAttributes

To copy all the attributes found at the current position of an XmlReader object. The attributes that are written depend on the type of node the reader is currently positioned on:

  • For an attribute node, it writes the current attribute, and then the rest of the attributes until the element closing tag.

  • For an element node, it writes all attributes contained by the element.

  • For an XML declaration node, it writes all the attributes in the declaration.

  • For all other node types, the method throws an exception.

Handling namespaces

Namespaces are used to qualify element and attribute names in an XML document. Namespace prefixes associate elements and attributes with namespaces, which are in turn associated with URI references. Namespaces create element and attribute name uniqueness in an XML document.

The XmlWriter maintains a namespace stack that corresponds to all the namespaces defined in the current namespace scope. When writing elements and attributes you can utilize namespaces in the following ways:

  • Declare namespaces manually by using the WriteAttributeString method. This can be useful when you know how to best optimize the number of namespace declarations. For an example, see the WriteAttributeString(String, String, String, String) method.

  • Override the current namespace declaration with a new namespace. In the following code, the WriteAttributeString method changes the namespace URI for the "x" prefix from "123" to "abc".

    writer.WriteStartElement("x", "root", "123");
    writer.WriteStartElement("item");
    writer.WriteAttributeString("xmlns", "x", null, "abc");
    writer.WriteEndElement();
    writer.WriteEndElement();
    

    The code generates the following XML string:

    <x:root xmlns:x="123">
      <item xmlns:x="abc" />
    </x:root>
    
  • Specify a namespace prefix when writing attributes or elements. Many of the methods used to write element and attributes enable you to do this. For example, the WriteStartElement(String, String, String) method writes a start tag and associates it with a specified namespace and prefix.

Writing typed data

The WriteValue method accepts a common language runtime (CLR) object, converts the input value to its string representation according to XML schema definition language (XSD) data type conversion rules, and writes it out by using the WriteString method. This is easier than using the methods in the XmlConvert class to convert the typed data to a string value before writing it out.

When writing to text, the typed value is serialized to text by using the XmlConvert rules for that schema type.

For default XSD data types that correspond to CLR types, see the WriteValue method.

The XmlWriter can also be used to write to an XML data store. For example, the XPathNavigator class can create an XmlWriter object to create nodes for an XmlDocument object. If the data store has schema information available to it, the WriteValue method throws an exception if you try to convert to a type that is not allowed.If the data store does not have schema information available to it, the WriteValue method treats all values as an xsd:anySimpleType type.

Closing the XML writer

When you use XmlWriter methods to output XML, the elements and attributes are not written until you call the Close method. For example, if you are using XmlWriter to populate an XmlDocument object, you won't be able to see the written elements and attributes in the target document until you close the XmlWriter instance.

Asynchronous programming

Most of the XmlWriter methods have asynchronous counterparts that have "Async" at the end of their method names. For example, the asynchronous equivalent of WriteAttributeString is WriteAttributeStringAsync.

For the WriteValue method, which doesn't have an asynchronous counterpart, convert the return value to a string and use the WriteStringAsync method instead.

Security considerations

Consider the following when working with the XmlWriter class:

  • Exceptions thrown by the XmlWriter can disclose path information that you do not want bubbled up to the app. Your app must catch exceptions and process them appropriately.

  • XmlWriter does not validate any data that is passed to the WriteDocType or WriteRaw method. You should not pass arbitrary data to these methods.

The following example code shows how to use the asynchronous API to generate XML.

async Task TestWriter(Stream stream) 
{
    XmlWriterSettings settings = new XmlWriterSettings();
    settings.Async = true;

    using (XmlWriter writer = XmlWriter.Create(stream, settings)) {
        await writer.WriteStartElementAsync("pf", "root", "http://ns");
        await writer.WriteStartElementAsync(null, "sub", null);
        await writer.WriteAttributeStringAsync(null, "att", null, "val");
        await writer.WriteStringAsync("text");
        await writer.WriteEndElementAsync();
        await writer.WriteProcessingInstructionAsync("pName", "pValue");
        await writer.WriteCommentAsync("cValue");
        await writer.WriteCDataAsync("cdata value");
        await writer.WriteEndElementAsync();
        await writer.FlushAsync();
    }
}

.NET Framework

Supported in: 4.5.3, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft