The System.Xml.XmlWriter class writes XML data to a stream, file, text reader, or string. It supports the W3C tp://www.w3.org/TR/2006/REC-xml-20060816/ and tp://www.w3.org/TR/REC-xml-names/ recommendations.

The members of the System.Xml.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 System.Xml.XmlWriter instance, use the erload:System.Xml.XmlWriter.Create method. To specify the set of features you want to enable on the XML writer, pass an System.Xml.XmlWriterSettings to the erload:System.Xml.XmlWriter.Create method. Otherwise, default settings are used. See the erload:System.Xml.XmlWriter.Create reference pages for details.

Specifying the output format

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

XmlWriterSettings.Encoding	Specifies the text encoding to use. The default is Encoding.UTF8.
XmlWriterSettings.Indent	Indicates whether to indent elements. The default is false (no indentation).
XmlWriterSettings.IndentChars	Specifies the character string to use when indenting. The default is two spaces.
XmlWriterSettings.NewLineChars	Specifies the character string to use for line breaks. The default is \r\n (carriage return, line feed).
XmlWriterSettings.NewLineHandling	Specifies how to handle newline characters.
XmlWriterSettings.NewLineOnAttributes	Indicates whether to write attributes on a new line. XmlWriterSettings.Indent should be set to true when using this property. The default is false.
XmlWriterSettings.OmitXmlDeclaration	Indicates whether to write an XML declaration. The default is false.

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

code reference: XmlWriter_v2#8

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

code reference: XmlWriter_v2#9

Data conformance

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

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

• The XmlWriterSettings.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 ConformanceLevel.Document. For details, see the XmlWriterSettings.ConformanceLevel property and the System.Xml.ConformanceLevel enumeration.

Writing elements

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

erload:System.Xml.XmlWriter.WriteElementString	Write an entire element node, including a string value.
erload:System.Xml.XmlWriter.WriteStartElement	To write an element value by using multiple method calls. For example, you can call erload:System.Xml.XmlWriter.WriteValue to write a typed value, XmlWriter.WriteCharEntity(char) to write a character entity, erload:System.Xml.XmlWriter.WriteAttributeString to write an attribute, or you can write a child element. This is a more sophisticated version of the erload:System.Xml.XmlWriter.WriteElementString method. To close the element, you call the XmlWriter.WriteEndElement or XmlWriter.WriteFullEndElement method.
erload:System.Xml.XmlWriter.WriteNode	To copy an element node found at the current position of an System.Xml.XmlReader or System.Xml.XPath.XPathNavigator object. When called, it copies everything from the source object to the System.Xml.XmlWriter instance.

Writing attributes

You can use the following System.Xml.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.

erload:System.Xml.XmlWriter.WriteAttributeString	To write an entire attribute node, including a string value.
erload:System.Xml.XmlWriter.WriteStartAttribute	To write the attribute value using multiple method calls. For example, you can call erload:System.Xml.XmlWriter.WriteValue to write a typed value. This is a more sophisticated version of the erload:System.Xml.XmlWriter.WriteElementString method. To close the element, you call the XmlWriter.WriteEndAttribute method.
XmlWriter.WriteAttributes(XmlReader, bool)	To copy all the attributes found at the current position of an System.Xml.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 System.Xml.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 XmlWriter.WriteAttributeString(string, string, string, string) method. This can be useful when you know how to best optimize the number of namespace declarations. For an example, see the XmlWriter.WriteAttributeString(string, string, string, string) method.

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

  code reference: XmlWriter_v2#18

  The code generates the following XML string:

• 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 XmlWriter.WriteStartElement(string, string, string) method writes a start tag and associates it with a specified namespace and prefix.

Writing typed data

The erload:System.Xml.XmlWriter.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 XmlWriter.WriteString(string) method. This is easier than using the methods in the System.Xml.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 System.Xml.XmlConvert rules for that schema type.

For default XSD data types that correspond to CLR types, see the erload:System.Xml.XmlWriter.WriteValue method.

The System.Xml.XmlWriter can also be used to write to an XML data store. For example, the System.Xml.XPath.XPathNavigator class can create an System.Xml.XmlWriter object to create nodes for an System.Xml.XmlDocument object. If the data store has schema information available to it, the erload:System.Xml.XmlWriter.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 erload:System.Xml.XmlWriter.WriteValue method treats all values as an xsd:anySimpleType type.

Closing the XML writer

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

Asynchronous programming

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

For the erload:System.Xml.XmlWriter.WriteValue method, which doesn't have an asynchronous counterpart, convert the return value to a string and use the XmlWriter.WriteStringAsync(string) method instead.

Security considerations

Consider the following when working with the System.Xml.XmlWriter class:

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

• System.Xml.XmlWriter does not validate any data that is passed to the XmlWriter.WriteDocType(string, string, string, string) or erload:System.Xml.XmlWriter.WriteRaw method. You should not pass arbitrary data to these methods.

All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.

Namespace: System.Xml
Assembly: System.Xml (in System.Xml.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0, 4.0.0.0