Export (0) Print
Expand All

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)

type XmlTextWriter =  
    class 
        inherit XmlWriter 
    end

The XmlTextWriter type exposes the following members.

  NameDescription
Public methodSupported by the XNA FrameworkXmlTextWriter(TextWriter)Creates an instance of the XmlTextWriter class using the specified TextWriter.
Public methodSupported by the XNA FrameworkXmlTextWriter(Stream, Encoding)Creates an instance of the XmlTextWriter class using the specified stream and encoding.
Public methodSupported by the XNA FrameworkXmlTextWriter(String, Encoding)Creates an instance of the XmlTextWriter class using the specified file.
Top

  NameDescription
Public propertySupported by the XNA FrameworkBaseStreamGets the underlying stream object.
Public propertySupported by the XNA FrameworkFormattingIndicates how the output is formatted.
Public propertySupported by the XNA FrameworkIndentationGets or sets how many IndentChars to write for each level in the hierarchy when Formatting is set to Formatting.Indented.
Public propertySupported by the XNA FrameworkIndentCharGets or sets which character to use for indenting when Formatting is set to Formatting.Indented.
Public propertySupported by the XNA FrameworkNamespacesGets or sets a value indicating whether to do namespace support.
Public propertySupported by the XNA FrameworkQuoteCharGets or sets which character to use to quote attribute values.
Public propertySupported by the XNA FrameworkSettingsGets the XmlWriterSettings object used to create this XmlWriter instance. (Inherited from XmlWriter.)
Public propertySupported by the XNA FrameworkWriteStateGets the state of the writer. (Overrides XmlWriter.WriteState.)
Public propertySupported by the XNA FrameworkXmlLangGets the current xml:lang scope. (Overrides XmlWriter.XmlLang.)
Public propertySupported by the XNA FrameworkXmlSpaceGets an XmlSpace representing the current xml:space scope. (Overrides XmlWriter.XmlSpace.)
Top

  NameDescription
Public methodSupported by the XNA FrameworkCloseCloses this stream and the underlying stream. (Overrides XmlWriter.Close().)
Public methodDispose()Releases all resources used by the current instance of the XmlWriter class. (Inherited from XmlWriter.)
Protected methodSupported by the XNA FrameworkDispose(Boolean)Releases the unmanaged resources used by the XmlWriter and optionally releases the managed resources. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by the XNA FrameworkFinalizeAllows 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 FrameworkFlushFlushes whatever is in the buffer to the underlying streams and also flushes the underlying stream. (Overrides XmlWriter.Flush().)
Public methodFlushAsyncAsynchronously flushes whatever is in the buffer to the underlying streams and also flushes the underlying stream. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodSupported by the XNA FrameworkGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodSupported by the XNA FrameworkLookupPrefixReturns the closest prefix defined in the current namespace scope for the namespace URI. (Overrides XmlWriter.LookupPrefix(String).)
Protected methodSupported by the XNA FrameworkMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by the XNA FrameworkToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodSupported by the XNA FrameworkWriteAttributesWhen overridden in a derived class, writes out all the attributes found at the current position in the XmlReader. (Inherited from XmlWriter.)
Public methodWriteAttributesAsyncAsynchronously writes out all the attributes found at the current position in the XmlReader. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteAttributeString(String, String)When overridden in a derived class, writes out the attribute with the specified local name and value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteAttributeString(String, String, String)When overridden in a derived class, writes an attribute with the specified local name, namespace URI, and value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteAttributeString(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.)
Public methodWriteAttributeStringAsyncAsynchronously writes out the attribute with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteBase64Encodes the specified binary bytes as base64 and writes out the resulting text. (Overrides XmlWriter.WriteBase64(Byte[], Int32, Int32).)
Public methodWriteBase64AsyncAsynchronously encodes the specified binary bytes as Base64 and writes out the resulting text. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteBinHexEncodes the specified binary bytes as binhex and writes out the resulting text. (Overrides XmlWriter.WriteBinHex(Byte[], Int32, Int32).)
Public methodWriteBinHexAsyncAsynchronously encodes the specified binary bytes as BinHex and writes out the resulting text. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteCDataWrites out a <![CDATA[...]]> block containing the specified text. (Overrides XmlWriter.WriteCData(String).)
Public methodWriteCDataAsyncAsynchronously writes out a <![CDATA[...]]> block containing the specified text. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteCharEntityForces the generation of a character entity for the specified Unicode character value. (Overrides XmlWriter.WriteCharEntity(Char).)
Public methodWriteCharEntityAsyncAsynchronously forces the generation of a character entity for the specified Unicode character value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteCharsWrites text one buffer at a time. (Overrides XmlWriter.WriteChars(Char[], Int32, Int32).)
Public methodWriteCharsAsyncAsynchronously writes text one buffer at a time. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteCommentWrites out a comment <!--...--> containing the specified text. (Overrides XmlWriter.WriteComment(String).)
Public methodWriteCommentAsyncAsynchronously writes out a comment <!--...--> containing the specified text. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteDocTypeWrites the DOCTYPE declaration with the specified name and optional attributes. (Overrides XmlWriter.WriteDocType(String, String, String, String).)
Public methodWriteDocTypeAsyncAsynchronously writes the DOCTYPE declaration with the specified name and optional attributes. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteElementString(String, String)Writes an element with the specified local name and value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteElementString(String, String, String)Writes an element with the specified local name, namespace URI, and value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteElementString(String, String, String, String)Writes an element with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter.)
Public methodWriteElementStringAsyncAsynchronously writes an element with the specified prefix, local name, namespace URI, and value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteEndAttributeCloses the previous WriteStartAttribute call. (Overrides XmlWriter.WriteEndAttribute().)
Protected methodWriteEndAttributeAsyncAsynchronously closes the previous WriteStartAttribute call. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteEndDocumentCloses any open elements or attributes and puts the writer back in the Start state. (Overrides XmlWriter.WriteEndDocument().)
Public methodWriteEndDocumentAsyncAsynchronously closes any open elements or attributes and puts the writer back in the Start state. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteEndElementCloses one element and pops the corresponding namespace scope. (Overrides XmlWriter.WriteEndElement().)
Public methodWriteEndElementAsyncAsynchronously closes one element and pops the corresponding namespace scope. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteEntityRefWrites out an entity reference as &name;. (Overrides XmlWriter.WriteEntityRef(String).)
Public methodWriteEntityRefAsyncAsynchronously writes out an entity reference as &name;. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteFullEndElementCloses one element and pops the corresponding namespace scope. (Overrides XmlWriter.WriteFullEndElement().)
Public methodWriteFullEndElementAsyncAsynchronously closes one element and pops the corresponding namespace scope. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteNameWrites 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).)
Public methodWriteNameAsyncAsynchronously 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.)
Public methodSupported by the XNA FrameworkWriteNmTokenWrites 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).)
Public methodWriteNmTokenAsyncAsynchronously 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.)
Public methodSupported by the XNA FrameworkWriteNode(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.)
Public methodWriteNode(XPathNavigator, Boolean)Copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged. (Inherited from XmlWriter.)
Public methodWriteNodeAsync(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.)
Public methodWriteNodeAsync(XPathNavigator, Boolean)Asynchronously copies everything from the XPathNavigator object to the writer. The position of the XPathNavigator remains unchanged. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteProcessingInstructionWrites out a processing instruction with a space between the name and text as follows: <?name text?>. (Overrides XmlWriter.WriteProcessingInstruction(String, String).)
Public methodWriteProcessingInstructionAsyncAsynchronously writes out a processing instruction with a space between the name and text as follows: <?name text?>. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteQualifiedNameWrites out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace. (Overrides XmlWriter.WriteQualifiedName(String, String).)
Public methodWriteQualifiedNameAsyncAsynchronously writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteRaw(String)Writes raw markup manually from a string. (Overrides XmlWriter.WriteRaw(String).)
Public methodSupported by the XNA FrameworkWriteRaw(Char[], Int32, Int32)Writes raw markup manually from a character buffer. (Overrides XmlWriter.WriteRaw(Char[], Int32, Int32).)
Public methodWriteRawAsync(String)Asynchronously writes raw markup manually from a string. (Inherited from XmlWriter.)
Public methodWriteRawAsync(Char[], Int32, Int32)Asynchronously writes raw markup manually from a character buffer. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartAttribute(String)Writes the start of an attribute with the specified local name. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartAttribute(String, String)Writes the start of an attribute with the specified local name and namespace URI. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartAttribute(String, String, String)Writes the start of an attribute. (Overrides XmlWriter.WriteStartAttribute(String, String, String).)
Protected methodWriteStartAttributeAsyncAsynchronously writes the start of an attribute with the specified prefix, local name, and namespace URI. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartDocument()Writes the XML declaration with the version "1.0". (Overrides XmlWriter.WriteStartDocument().)
Public methodSupported by the XNA FrameworkWriteStartDocument(Boolean)Writes the XML declaration with the version "1.0" and the standalone attribute. (Overrides XmlWriter.WriteStartDocument(Boolean).)
Public methodWriteStartDocumentAsync()Asynchronously writes the XML declaration with the version "1.0". (Inherited from XmlWriter.)
Public methodWriteStartDocumentAsync(Boolean)Asynchronously writes the XML declaration with the version "1.0" and the standalone attribute. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartElement(String)When overridden in a derived class, writes out a start tag with the specified local name. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartElement(String, String)When overridden in a derived class, writes the specified start tag and associates it with the given namespace. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStartElement(String, String, String)Writes the specified start tag and associates it with the given namespace and prefix. (Overrides XmlWriter.WriteStartElement(String, String, String).)
Public methodWriteStartElementAsyncAsynchronously writes the specified start tag and associates it with the given namespace and prefix. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteStringWrites the given text content. (Overrides XmlWriter.WriteString(String).)
Public methodWriteStringAsyncAsynchronously writes the given text content. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteSurrogateCharEntityGenerates and writes the surrogate character entity for the surrogate character pair. (Overrides XmlWriter.WriteSurrogateCharEntity(Char, Char).)
Public methodWriteSurrogateCharEntityAsyncAsynchronously generates and writes the surrogate character entity for the surrogate character pair. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Boolean)Writes a Boolean value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(DateTime)Writes a DateTime value. (Inherited from XmlWriter.)
Public methodWriteValue(DateTimeOffset)Writes a DateTimeOffset value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Decimal)Writes a Decimal value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Double)Writes a Double value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Int32)Writes a Int32 value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Int64)Writes a Int64 value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Object)Writes the object value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(Single)Writes a single-precision floating-point number. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteValue(String)Writes a String value. (Inherited from XmlWriter.)
Public methodSupported by the XNA FrameworkWriteWhitespaceWrites out the given white space. (Overrides XmlWriter.WriteWhitespace(String).)
Public methodWriteWhitespaceAsyncAsynchronously writes out the given white space. (Inherited from XmlWriter.)
Top

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

This class implements the XmlWriter class.

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, a null reference (Nothing in Visual Basic) 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.

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

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