XmlTextWriter Class

 

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 System.Xml::XmlWriter class instead.

Namespace:   System.Xml
Assembly:  System.Xml (in System.Xml.dll)

System::Object
  System.Xml::XmlWriter
    System.Xml::XmlTextWriter

public ref class XmlTextWriter : XmlWriter

NameDescription
System_CAPS_pubmethodXmlTextWriter(Stream^, Encoding^)

Creates an instance of the XmlTextWriter class using the specified stream and encoding.

System_CAPS_pubmethodXmlTextWriter(String^, Encoding^)

Creates an instance of the XmlTextWriter class using the specified file.

System_CAPS_pubmethodXmlTextWriter(TextWriter^)

Creates an instance of the XmlTextWriter class using the specified TextWriter.

NameDescription
System_CAPS_pubpropertyBaseStream

Gets the underlying stream object.

System_CAPS_pubpropertyFormatting

Indicates how the output is formatted.

System_CAPS_pubpropertyIndentation

Gets or sets how many IndentChars to write for each level in the hierarchy when Formatting is set to Formatting.Indented.

System_CAPS_pubpropertyIndentChar

Gets or sets which character to use for indenting when Formatting is set to Formatting.Indented.

System_CAPS_pubpropertyNamespaces

Gets or sets a value indicating whether to do namespace support.

System_CAPS_pubpropertyQuoteChar

Gets or sets which character to use to quote attribute values.

System_CAPS_pubpropertySettings

Gets the XmlWriterSettings object used to create this XmlWriter instance.(Inherited from XmlWriter.)

System_CAPS_pubpropertyWriteState

Gets the state of the writer.(Overrides XmlWriter::WriteState.)

System_CAPS_pubpropertyXmlLang

Gets the current xml:lang scope.(Overrides XmlWriter::XmlLang.)

System_CAPS_pubpropertyXmlSpace

Gets an XmlSpace representing the current xml:space scope.(Overrides XmlWriter::XmlSpace.)

NameDescription
System_CAPS_pubmethodClose()

Closes this stream and the underlying stream.(Overrides XmlWriter::Close().)

System_CAPS_pubmethodDispose()

Releases all resources used by the current instance of the XmlWriter class.(Inherited from XmlWriter.)

System_CAPS_protmethodDispose(Boolean)

Releases the unmanaged resources used by the XmlWriter and optionally releases the managed resources.(Inherited from XmlWriter.)

System_CAPS_pubmethodEquals(Object^)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodFlush()

Flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream.(Overrides XmlWriter::Flush().)

System_CAPS_pubmethodFlushAsync()

Asynchronously flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream.(Inherited from XmlWriter.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodLookupPrefix(String^)

Returns the closest prefix defined in the current namespace scope for the namespace URI.(Overrides XmlWriter::LookupPrefix(String^).)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_pubmethodWriteAttributes(XmlReader^, Boolean)

When overridden in a derived class, writes out all the attributes found at the current position in the XmlReader.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteAttributesAsync(XmlReader^, Boolean)

Asynchronously writes out all the attributes found at the current position in the XmlReader.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteAttributeString(String^, String^)

When overridden in a derived class, writes out the attribute with the specified local name and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteAttributeString(String^, String^, String^)

When overridden in a derived class, writes an attribute with the specified local name, namespace URI, and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteAttributeString(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.)

System_CAPS_pubmethodWriteAttributeStringAsync(String^, String^, String^, String^)

Asynchronously writes out the attribute with the specified prefix, local name, namespace URI, and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteBase64(array<Byte>^, Int32, Int32)

Encodes the specified binary bytes as base64 and writes out the resulting text.(Overrides XmlWriter::WriteBase64(array<Byte>^, Int32, Int32).)

System_CAPS_pubmethodWriteBase64Async(array<Byte>^, Int32, Int32)

Asynchronously encodes the specified binary bytes as Base64 and writes out the resulting text.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteBinHex(array<Byte>^, Int32, Int32)

Encodes the specified binary bytes as binhex and writes out the resulting text.(Overrides XmlWriter::WriteBinHex(array<Byte>^, Int32, Int32).)

System_CAPS_pubmethodWriteBinHexAsync(array<Byte>^, Int32, Int32)

Asynchronously encodes the specified binary bytes as BinHex and writes out the resulting text.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteCData(String^)

Writes out a <![CDATA[...]]> block containing the specified text.(Overrides XmlWriter::WriteCData(String^).)

System_CAPS_pubmethodWriteCDataAsync(String^)

Asynchronously writes out a <![CDATA[...]]> block containing the specified text.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteCharEntity(Char)

Forces the generation of a character entity for the specified Unicode character value.(Overrides XmlWriter::WriteCharEntity(Char).)

System_CAPS_pubmethodWriteCharEntityAsync(Char)

Asynchronously forces the generation of a character entity for the specified Unicode character value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteChars(array<Char>^, Int32, Int32)

Writes text one buffer at a time.(Overrides XmlWriter::WriteChars(array<Char>^, Int32, Int32).)

System_CAPS_pubmethodWriteCharsAsync(array<Char>^, Int32, Int32)

Asynchronously writes text one buffer at a time.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteComment(String^)

Writes out a comment <!--...--> containing the specified text.(Overrides XmlWriter::WriteComment(String^).)

System_CAPS_pubmethodWriteCommentAsync(String^)

Asynchronously writes out a comment <!--...--> containing the specified text.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteDocType(String^, String^, String^, String^)

Writes the DOCTYPE declaration with the specified name and optional attributes.(Overrides XmlWriter::WriteDocType(String^, String^, String^, String^).)

System_CAPS_pubmethodWriteDocTypeAsync(String^, String^, String^, String^)

Asynchronously writes the DOCTYPE declaration with the specified name and optional attributes.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteElementString(String^, String^)

Writes an element with the specified local name and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteElementString(String^, String^, String^)

Writes an element with the specified local name, namespace URI, and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteElementString(String^, String^, String^, String^)

Writes an element with the specified prefix, local name, namespace URI, and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteElementStringAsync(String^, String^, String^, String^)

Asynchronously writes an element with the specified prefix, local name, namespace URI, and value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteEndAttribute()

Closes the previous WriteStartAttribute call.(Overrides XmlWriter::WriteEndAttribute().)

System_CAPS_protmethodWriteEndAttributeAsync()

Asynchronously closes the previous WriteStartAttribute call.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteEndDocument()

Closes any open elements or attributes and puts the writer back in the Start state.(Overrides XmlWriter::WriteEndDocument().)

System_CAPS_pubmethodWriteEndDocumentAsync()

Asynchronously closes any open elements or attributes and puts the writer back in the Start state.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteEndElement()

Closes one element and pops the corresponding namespace scope.(Overrides XmlWriter::WriteEndElement().)

System_CAPS_pubmethodWriteEndElementAsync()

Asynchronously closes one element and pops the corresponding namespace scope.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteEntityRef(String^)

Writes out an entity reference as &name;.(Overrides XmlWriter::WriteEntityRef(String^).)

System_CAPS_pubmethodWriteEntityRefAsync(String^)

Asynchronously writes out an entity reference as &name;.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteFullEndElement()

Closes one element and pops the corresponding namespace scope.(Overrides XmlWriter::WriteFullEndElement().)

System_CAPS_pubmethodWriteFullEndElementAsync()

Asynchronously closes one element and pops the corresponding namespace scope.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteName(String^)

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).(Overrides XmlWriter::WriteName(String^).)

System_CAPS_pubmethodWriteNameAsync(String^)

Asynchronously 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).(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteNmToken(String^)

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).(Overrides XmlWriter::WriteNmToken(String^).)

System_CAPS_pubmethodWriteNmTokenAsync(String^)

Asynchronously 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).(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteNode(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.)

System_CAPS_pubmethodWriteNode(XPathNavigator^, Boolean)

Copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteNodeAsync(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.)

System_CAPS_pubmethodWriteNodeAsync(XPathNavigator^, Boolean)

Asynchronously copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteProcessingInstruction(String^, String^)

Writes out a processing instruction with a space between the name and text as follows: <?name text?>.(Overrides XmlWriter::WriteProcessingInstruction(String^, String^).)

System_CAPS_pubmethodWriteProcessingInstructionAsync(String^, String^)

Asynchronously writes out a processing instruction with a space between the name and text as follows: <?name text?>.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteQualifiedName(String^, String^)

Writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace.(Overrides XmlWriter::WriteQualifiedName(String^, String^).)

System_CAPS_pubmethodWriteQualifiedNameAsync(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.)

System_CAPS_pubmethodWriteRaw(array<Char>^, Int32, Int32)

Writes raw markup manually from a character buffer.(Overrides XmlWriter::WriteRaw(array<Char>^, Int32, Int32).)

System_CAPS_pubmethodWriteRaw(String^)

Writes raw markup manually from a string.(Overrides XmlWriter::WriteRaw(String^).)

System_CAPS_pubmethodWriteRawAsync(array<Char>^, Int32, Int32)

Asynchronously writes raw markup manually from a character buffer.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteRawAsync(String^)

Asynchronously writes raw markup manually from a string.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartAttribute(String^)

Writes the start of an attribute with the specified local name.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartAttribute(String^, String^)

Writes the start of an attribute with the specified local name and namespace URI.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartAttribute(String^, String^, String^)

Writes the start of an attribute.(Overrides XmlWriter::WriteStartAttribute(String^, String^, String^).)

System_CAPS_protmethodWriteStartAttributeAsync(String^, String^, String^)

Asynchronously writes the start of an attribute with the specified prefix, local name, and namespace URI.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartDocument()

Writes the XML declaration with the version "1.0".(Overrides XmlWriter::WriteStartDocument().)

System_CAPS_pubmethodWriteStartDocument(Boolean)

Writes the XML declaration with the version "1.0" and the standalone attribute.(Overrides XmlWriter::WriteStartDocument(Boolean).)

System_CAPS_pubmethodWriteStartDocumentAsync()

Asynchronously writes the XML declaration with the version "1.0".(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartDocumentAsync(Boolean)

Asynchronously writes the XML declaration with the version "1.0" and the standalone attribute.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartElement(String^)

When overridden in a derived class, writes out a start tag with the specified local name.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartElement(String^, String^)

When overridden in a derived class, writes the specified start tag and associates it with the given namespace.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteStartElement(String^, String^, String^)

Writes the specified start tag and associates it with the given namespace and prefix.(Overrides XmlWriter::WriteStartElement(String^, String^, String^).)

System_CAPS_pubmethodWriteStartElementAsync(String^, String^, String^)

Asynchronously writes the specified start tag and associates it with the given namespace and prefix.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteString(String^)

Writes the given text content.(Overrides XmlWriter::WriteString(String^).)

System_CAPS_pubmethodWriteStringAsync(String^)

Asynchronously writes the given text content.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteSurrogateCharEntity(Char, Char)

Generates and writes the surrogate character entity for the surrogate character pair.(Overrides XmlWriter::WriteSurrogateCharEntity(Char, Char).)

System_CAPS_pubmethodWriteSurrogateCharEntityAsync(Char, Char)

Asynchronously generates and writes the surrogate character entity for the surrogate character pair.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Boolean)

Writes a Boolean value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(DateTime)

Writes a DateTime value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(DateTimeOffset)

Writes a DateTimeOffset value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Decimal)

Writes a Decimal value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Double)

Writes a Double value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Int32)

Writes a Int32 value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Int64)

Writes a Int64 value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Object^)

Writes the object value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(Single)

Writes a single-precision floating-point number.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteValue(String^)

Writes a String value.(Inherited from XmlWriter.)

System_CAPS_pubmethodWriteWhitespace(String^)

Writes out the given white space.(Overrides XmlWriter::WriteWhitespace(String^).)

System_CAPS_pubmethodWriteWhitespaceAsync(String^)

Asynchronously writes out the given white space.(Inherited from XmlWriter.)

This class implements the XmlWriter class.

System_CAPS_noteNote

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.

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.

.NET Framework
Available since 1.1

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

Return to top
Show: