XmlTextWriter Class

Definition

Namespace:

System.Xml

Assembly:

System.Xml.ReaderWriter.dll

Represents a writer that provides a fast, non-cached, forward-only way of generating streams or files containing XML data that conforms to the W3C Extensible Markup Language (XML) 1.0 and the Namespaces in XML recommendations.

Starting with the .NET Framework 2.0, we recommend that you use the XmlWriter class instead.

public ref class XmlTextWriter : System::Xml::XmlWriter

public class XmlTextWriter : System.Xml.XmlWriter

type XmlTextWriter = class
    inherit XmlWriter

Public Class XmlTextWriter
Inherits XmlWriter

Inheritance

Object

XmlWriter

XmlTextWriter

Remarks

This class implements the XmlWriter class.

Note

Starting with the .NET Framework 2.0, we recommend that you create XmlWriter instances by using the XmlWriter.Create method and the XmlWriterSettings class to take advantage of new functionality.

XmlTextWriter maintains a namespace stack corresponding to all the namespaces defined in the current element stack. Using XmlTextWriter you can declare namespaces manually.

w.WriteStartElement("root");  
w.WriteAttributeString("xmlns", "x", null, "urn:1");  
w.WriteStartElement("item","urn:1");  
w.WriteEndElement();  
w.WriteStartElement("item","urn:1");  
w.WriteEndElement();  
w.WriteEndElement();  

The above C# code produces the following output. XmlTextWriter promotes the namespace declaration to the root element to avoid having it duplicated on the two child elements. The child elements pick up the prefix from the namespace declaration.

<root xmlns:x="urn:1">  
 <x:item/>  
 <x:item/>  
</x:root>  

XmlTextWriter also allows you to override the current namespace declaration. In the following example, the namespace URI "123" is overridden by "abc" to produce the XML element <x:node xmlns:x="abc"/>.

w.WriteStartElement("x","node","123");  
w.WriteAttributeString("xmlns","x",null,"abc");  

By using the write methods that take a prefix as an argument you can also specify which prefix to use. In the following example, two different prefixes are mapped to the same namespace URI to produce the XML text <x:root xmlns:x="urn:1"><y:item xmlns:y="urn:1"/></x:root>.

XmlTextWriter w = new XmlTextWriter(Console.Out);  
w.WriteStartElement("x","root","urn:1");  
 w.WriteStartElement("y","item","urn:1");  
 w.WriteEndElement();  
w.WriteEndElement();  
w.Close();  

If there are multiple namespace declarations mapping different prefixes to the same namespace URI, XmlTextWriter walks the stack of namespace declarations backwards and picks the closest one.

XmlTextWriter w = new XmlTextWriter(Console.Out);  
w.Formatting = Formatting.Indented;  
w.WriteStartElement("x","root","urn:1");  
w.WriteStartElement("y","item","urn:1");  
w.WriteAttributeString("attr","urn:1","123");  
w.WriteEndElement();  
w.WriteEndElement();  
w.Close();  

In the above C# example, because the WriteAttributeString call does not specify a prefix, the writer uses the last prefix pushed onto the namespace stack, and produces the following XML:

<x:root xmlns:x="urn:1">  
 <y:item y:attr="123" xmlns:y="urn:1" />  
</x:root>  

If namespace conflicts occur, XmlTextWriter resolves them by generating alternate prefixes. For example, if an attribute and element have the same prefix but different namespaces, XmlWriter generates an alternate prefix for the attribute. The generated prefixes are named n{i} where i is a number beginning at 1. The number is reset to 1 for each element.

Attributes which are associated with a namespace URI must have a prefix (default namespaces do not apply to attributes). This conforms to section 5.2 of the W3C Namespaces in XML recommendation. If an attribute references a namespace URI, but does not specify a prefix, the writer generates a prefix for the attribute.

When writing an empty element, an additional space is added between tag name and the closing tag, for example <item />. This provides compatibility with older browsers.

When a String is used as method parameter, null and String.Empty are equivalent. String.Empty follows the W3C rules.

To write strongly typed data, use the XmlConvert class to convert data types to string. For example, the following C# code converts the data from Double to String and writes the element <price>19.95</price>.

Double price = 19.95;  
writer.WriteElementString("price", XmlConvert.ToString(price));  

XmlTextWriter does not check for the following:

• Invalid characters in attribute and element names.

• Unicode characters that do not fit the specified encoding. If the Unicode characters do not fit the specified encoding, the XmlTextWriter does not escape the Unicode characters into character entities.

• Duplicate attributes.

• Characters in the DOCTYPE public identifier or system identifier.

Security Considerations

The following items are things to consider when working with the XmlTextWriter class.

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

• When you pass the XmlTextWriter to another application the underlying stream is exposed to that application. If you need to pass the XmlTextWriter to a semi-trusted application, you should use an XmlWriter object created by the Create method instead.

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

• If the default settings are changed, there is no guarantee that the generated output is well-formed XML data.

• Do not accept supporting components, such as an Encoding object, from an untrusted source.

Constructors

XmlTextWriter(Stream, Encoding)	Creates an instance of the XmlTextWriter class using the specified stream and encoding.
XmlTextWriter(String, Encoding)	Creates an instance of the XmlTextWriter class using the specified file.
XmlTextWriter(TextWriter)	Creates an instance of the XmlTextWriter class using the specified TextWriter.

Properties

BaseStream	Gets the underlying stream object.
Formatting	Indicates how the output is formatted.
Indentation	Gets or sets how many IndentChars to write for each level in the hierarchy when Formatting is set to Formatting.Indented.
IndentChar	Gets or sets which character to use for indenting when Formatting is set to Formatting.Indented.
Namespaces	Gets or sets a value indicating whether to do namespace support.
QuoteChar	Gets or sets which character to use to quote attribute values.
Settings	Gets the XmlWriterSettings object used to create this XmlWriter instance. (Inherited from XmlWriter)
WriteState	Gets the state of the writer.
XmlLang	Gets the current xml:lang scope.
XmlSpace	Gets an XmlSpace representing the current xml:space scope.

Methods

Close()	Closes this stream and the underlying stream.
Dispose()	Releases all resources used by the current instance of the XmlWriter class. (Inherited from XmlWriter)
Dispose(Boolean)	Releases the unmanaged resources used by the XmlWriter and optionally releases the managed resources. (Inherited from XmlWriter)
DisposeAsync()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously. (Inherited from XmlWriter)
DisposeAsyncCore()	Performs application-defined tasks associated with freeing, releasing, or resetting managed resources asynchronously. (Inherited from XmlWriter)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
Flush()	Flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream.
FlushAsync()	Asynchronously flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream. (Inherited from XmlWriter)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
LookupPrefix(String)	Returns the closest prefix defined in the current namespace scope for the namespace URI.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)
WriteAttributes(XmlReader, Boolean)	When overridden in a derived class, writes out all the attributes found at the current position in the XmlReader. (Inherited from XmlWriter)
WriteAttributesAsync(XmlReader, Boolean)	Asynchronously writes out all the attributes found at the current position in the XmlReader. (Inherited from XmlWriter)
WriteAttributeString(String, String)	When overridden in a derived class, writes out the attribute with the specified local name and value. (Inherited from XmlWriter)
WriteAttributeString(String, String, String)	When overridden in a derived class, writes an attribute with the specified local name, namespace URI, and value. (Inherited from XmlWriter)
WriteAttributeString(String, String, String, String)	When overridden in a derived class, writes out the attribute with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter)
WriteAttributeStringAsync(String, String, String, String)	Asynchronously writes out the attribute with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter)
WriteBase64(Byte[], Int32, Int32)	Encodes the specified binary bytes as base64 and writes out the resulting text.
WriteBase64Async(Byte[], Int32, Int32)	Asynchronously encodes the specified binary bytes as Base64 and writes out the resulting text. (Inherited from XmlWriter)
WriteBinHex(Byte[], Int32, Int32)	Encodes the specified binary bytes as binhex and writes out the resulting text.
WriteBinHexAsync(Byte[], Int32, Int32)	Asynchronously encodes the specified binary bytes as BinHex and writes out the resulting text. (Inherited from XmlWriter)
WriteCData(String)	Writes out a <![CDATA[...]]> block containing the specified text.
WriteCDataAsync(String)	Asynchronously writes out a <![CDATA[...]]> block containing the specified text. (Inherited from XmlWriter)
WriteCharEntity(Char)	Forces the generation of a character entity for the specified Unicode character value.
WriteCharEntityAsync(Char)	Asynchronously forces the generation of a character entity for the specified Unicode character value. (Inherited from XmlWriter)
WriteChars(Char[], Int32, Int32)	Writes text one buffer at a time.
WriteCharsAsync(Char[], Int32, Int32)	Asynchronously writes text one buffer at a time. (Inherited from XmlWriter)
WriteComment(String)	Writes out a comment <!--...--> containing the specified text.
WriteCommentAsync(String)	Asynchronously writes out a comment <!--...--> containing the specified text. (Inherited from XmlWriter)
WriteDocType(String, String, String, String)	Writes the DOCTYPE declaration with the specified name and optional attributes.
WriteDocTypeAsync(String, String, String, String)	Asynchronously writes the DOCTYPE declaration with the specified name and optional attributes. (Inherited from XmlWriter)
WriteElementString(String, String)	Writes an element with the specified local name and value. (Inherited from XmlWriter)
WriteElementString(String, String, String)	Writes an element with the specified local name, namespace URI, and value. (Inherited from XmlWriter)
WriteElementString(String, String, String, String)	Writes an element with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter)
WriteElementStringAsync(String, String, String, String)	Asynchronously writes an element with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter)
WriteEndAttribute()	Closes the previous WriteStartAttribute(String, String, String) call.
WriteEndAttributeAsync()	Asynchronously closes the previous WriteStartAttribute(String, String) call. (Inherited from XmlWriter)
WriteEndDocument()	Closes any open elements or attributes and puts the writer back in the Start state.
WriteEndDocumentAsync()	Asynchronously closes any open elements or attributes and puts the writer back in the Start state. (Inherited from XmlWriter)
WriteEndElement()	Closes one element and pops the corresponding namespace scope.
WriteEndElementAsync()	Asynchronously closes one element and pops the corresponding namespace scope. (Inherited from XmlWriter)
WriteEntityRef(String)	Writes out an entity reference as &name;.
WriteEntityRefAsync(String)	Asynchronously writes out an entity reference as &name;. (Inherited from XmlWriter)
WriteFullEndElement()	Closes one element and pops the corresponding namespace scope.
WriteFullEndElementAsync()	Asynchronously closes one element and pops the corresponding namespace scope. (Inherited from XmlWriter)
WriteName(String)	Writes out the specified name, ensuring it is a valid name according to the W3C XML 1.0 recommendation.
WriteNameAsync(String)	Asynchronously writes out the specified name, ensuring it is a valid name according to the W3C XML 1.0 recommendation (https://www.w3.org/TR/1998/REC-xml-19980210#NT-Name). (Inherited from XmlWriter)
WriteNmToken(String)	Writes out the specified name, ensuring it is a valid NmToken according to the W3C XML 1.0 recommendation.
WriteNmTokenAsync(String)	Asynchronously writes out the specified name, ensuring it is a valid NmToken according to the W3C XML 1.0 recommendation (https://www.w3.org/TR/1998/REC-xml-19980210#NT-Name). (Inherited from XmlWriter)
WriteNode(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. (Inherited from XmlWriter)
WriteNode(XPathNavigator, Boolean)	Copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged. (Inherited from XmlWriter)
WriteNodeAsync(XmlReader, Boolean)	Asynchronously copies everything from the reader to the writer and moves the reader to the start of the next sibling. (Inherited from XmlWriter)
WriteNodeAsync(XPathNavigator, Boolean)	Asynchronously copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged. (Inherited from XmlWriter)
WriteProcessingInstruction(String, String)	Writes out a processing instruction with a space between the name and text as follows: <?name text?>.
WriteProcessingInstructionAsync(String, String)	Asynchronously writes out a processing instruction with a space between the name and text as follows: <?name text?>. (Inherited from XmlWriter)
WriteQualifiedName(String, String)	Writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace.
WriteQualifiedNameAsync(String, String)	Asynchronously writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace. (Inherited from XmlWriter)
WriteRaw(Char[], Int32, Int32)	Writes raw markup manually from a character buffer.
WriteRaw(String)	Writes raw markup manually from a string.
WriteRawAsync(Char[], Int32, Int32)	Asynchronously writes raw markup manually from a character buffer. (Inherited from XmlWriter)
WriteRawAsync(String)	Asynchronously writes raw markup manually from a string. (Inherited from XmlWriter)
WriteStartAttribute(String)	Writes the start of an attribute with the specified local name. (Inherited from XmlWriter)
WriteStartAttribute(String, String)	Writes the start of an attribute with the specified local name and namespace URI. (Inherited from XmlWriter)
WriteStartAttribute(String, String, String)	Writes the start of an attribute.
WriteStartAttributeAsync(String, String, String)	Asynchronously writes the start of an attribute with the specified prefix, local name, and namespace URI. (Inherited from XmlWriter)
WriteStartDocument()	Writes the XML declaration with the version "1.0".
WriteStartDocument(Boolean)	Writes the XML declaration with the version "1.0" and the standalone attribute.
WriteStartDocumentAsync()	Asynchronously writes the XML declaration with the version "1.0". (Inherited from XmlWriter)
WriteStartDocumentAsync(Boolean)	Asynchronously writes the XML declaration with the version "1.0" and the standalone attribute. (Inherited from XmlWriter)
WriteStartElement(String)	When overridden in a derived class, writes out a start tag with the specified local name. (Inherited from XmlWriter)
WriteStartElement(String, String)	When overridden in a derived class, writes the specified start tag and associates it with the given namespace. (Inherited from XmlWriter)
WriteStartElement(String, String, String)	Writes the specified start tag and associates it with the given namespace and prefix.
WriteStartElementAsync(String, String, String)	Asynchronously writes the specified start tag and associates it with the given namespace and prefix. (Inherited from XmlWriter)
WriteString(String)	Writes the given text content.
WriteStringAsync(String)	Asynchronously writes the given text content. (Inherited from XmlWriter)
WriteSurrogateCharEntity(Char, Char)	Generates and writes the surrogate character entity for the surrogate character pair.
WriteSurrogateCharEntityAsync(Char, Char)	Asynchronously generates and writes the surrogate character entity for the surrogate character pair. (Inherited from XmlWriter)
WriteValue(Boolean)	Writes a Boolean value. (Inherited from XmlWriter)
WriteValue(DateTime)	Writes a DateTime value. (Inherited from XmlWriter)
WriteValue(DateTimeOffset)	Writes a DateTimeOffset value. (Inherited from XmlWriter)
WriteValue(Decimal)	Writes a Decimal value. (Inherited from XmlWriter)
WriteValue(Double)	Writes a Double value. (Inherited from XmlWriter)
WriteValue(Int32)	Writes a Int32 value. (Inherited from XmlWriter)
WriteValue(Int64)	Writes a Int64 value. (Inherited from XmlWriter)
WriteValue(Object)	Writes the object value. (Inherited from XmlWriter)
WriteValue(Single)	Writes a single-precision floating-point number. (Inherited from XmlWriter)
WriteValue(String)	Writes a String value. (Inherited from XmlWriter)
WriteWhitespace(String)	Writes out the given white space.
WriteWhitespaceAsync(String)	Asynchronously writes out the given white space. (Inherited from XmlWriter)

Extension Methods

ConfigureAwait(IAsyncDisposable, Boolean)

Configures how awaits on the tasks returned from an async disposable are performed.

See also

• XML Documents and Data