System.Xml.XmlTextWriter Class

public class XmlTextWriter : XmlWriter

Base Types

Object
XmlWriter
XmlTextWriter

Assembly

System.Xml

Library

XML

Summary

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.

Description

This class maintains a namespace stack corresponding to all the namespaces defined in the current element stack. Namespaces can be declared manually to override the current namespace declaration. Prefixes can be specified to associate with a namespace. If there are multiple namespace declarations mapping different prefixes to the same namespace URI, this class walks the stack of namespace declarations backwards and picks the closest one.
If namespace conflicts occur inside an element, this class resolves the conflict by generating alternate prefixes. The generated prefixes are named ni, where n is the literal character 'n' and i is a number beginning at one. The number is reset to one for each element. See the example section for a demonstration of this behavior.
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 System.String.Empty are equivalent. System.String.Empty follows the W3C rules.
This class implements the XmlWriter class.

Example

The following example demonstrates how this class resolves namespace conflicts inside an element. In the example, the writer writes an element that contains two attributes. The element and both attributes have the same prefix but different namespaces. The resulting XML fragment is written to the console.
using System;
using System.Xml;

public class WriteFragment 
{
  public static void Main() 
  {
    XmlTextWriter xWriter = new XmlTextWriter(Console.Out);    
    xWriter.WriteStartElement("prefix", "Element1", "namespace"); 
    xWriter.WriteStartAttribute("prefix", "Attr1", "namespace1"); 
    xWriter.WriteString("value1"); 
    xWriter.WriteStartAttribute("prefix", "Attr2", "namespace2"); 
    xWriter.WriteString("value2"); 
    xWriter.Close();           
  }
}
   
The output is
<prefix:Element1 n1:Attr1="value1" n2:Attr2="value2" xmlns:n2="namespace2" xmlns:n1="namespace1" xnlns:prefix="namespace" />

Members

XmlTextWriter Constructors
XmlTextWriter(System.IO.Stream, System.Text.Encoding) Constructor
XmlTextWriter(System.String, System.Text.Encoding) Constructor
XmlTextWriter(System.IO.TextWriter) Constructor

XmlTextWriter Methods
XmlTextWriter.Close Method
XmlTextWriter.Flush Method
XmlTextWriter.LookupPrefix Method
XmlTextWriter.WriteBase64 Method
XmlTextWriter.WriteBinHex Method
XmlTextWriter.WriteCData Method
XmlTextWriter.WriteCharEntity Method
XmlTextWriter.WriteChars Method
XmlTextWriter.WriteComment Method
XmlTextWriter.WriteDocType Method
XmlTextWriter.WriteEndAttribute Method
XmlTextWriter.WriteEndDocument Method
XmlTextWriter.WriteEndElement Method
XmlTextWriter.WriteEntityRef Method
XmlTextWriter.WriteFullEndElement Method
XmlTextWriter.WriteName Method
XmlTextWriter.WriteNmToken Method
XmlTextWriter.WriteProcessingInstruction Method
XmlTextWriter.WriteQualifiedName Method
XmlTextWriter.WriteRaw(System.String) Method
XmlTextWriter.WriteRaw(char[], int, int) Method
XmlTextWriter.WriteStartAttribute Method
XmlTextWriter.WriteStartDocument(bool) Method
XmlTextWriter.WriteStartDocument() Method
XmlTextWriter.WriteStartElement Method
XmlTextWriter.WriteString Method
XmlTextWriter.WriteSurrogateCharEntity Method
XmlTextWriter.WriteWhitespace Method

XmlTextWriter Properties
XmlTextWriter.BaseStream Property
XmlTextWriter.Formatting Property
XmlTextWriter.IndentChar Property
XmlTextWriter.Indentation Property
XmlTextWriter.Namespaces Property
XmlTextWriter.QuoteChar Property
XmlTextWriter.WriteState Property
XmlTextWriter.XmlLang Property
XmlTextWriter.XmlSpace Property

XmlTextWriter(System.IO.Stream, System.Text.Encoding) Constructor

public XmlTextWriter(Stream w, Encoding encoding);

Summary

Constructs and initializes a new instance of the XmlTextWriter class using the specified output stream.

Parameters

w

The Stream to write to.

encoding

The Encoding to generate, or null .

Exceptions

Exception Type Condition

ArgumentException w cannot be written to.
-or-
The encoding is not supported.

ArgumentNullException w is null .

Exception Type	Condition
ArgumentException	w cannot be written to. -or- The encoding is not supported.
ArgumentNullException	w is `null` .

Description

If encoding is null , the stream is written as UTF-8 and the encoding attribute is omitted from the processing instruction.
The following properties are initialized to the specified values:
System.Xml.XmlTextWriter.Formatting to System.Xml.Formatting.None.
System.Xml.XmlTextWriter.Indentation to 2.
System.Xml.XmlTextWriter.IndentChar to the space character.
System.Xml.XmlTextWriter.Namespaces to true .
System.Xml.XmlTextWriter.QuoteChar to the double quote character.
System.Xml.XmlTextWriter.WriteState to System.Xml.WriteState.Start.

XmlTextWriter(System.String, System.Text.Encoding) Constructor

public XmlTextWriter(string filename, Encoding encoding);

Summary

Constructs and initializes a new instance of the XmlTextWriter class using the specified file.

Parameters

filename

A String specifying the path and name of the file to write to.

encoding

The Encoding to generate, or null .

Exceptions

Exception Type Condition

ArgumentException filename is System.String.Empty, contains only white space, or contains one or more implementation-defined invalid characters.
-or-
The encoding is not supported.

ArgumentNullException filename is null .

DirectoryNotFoundException The directory path specified in filename does not exist.

IOException filename includes an invalid syntax for the path or file name.

PathTooLongException The specified path, file name, or both exceeds the system-defined maximum length.

SecurityException The caller does not have the required permissions.

UnauthorizedAccessException Write access is not permitted by the operating system for the path specified in filename.

Exception Type	Condition
ArgumentException	filename is System.String.Empty, contains only white space, or contains one or more implementation-defined invalid characters. -or- The encoding is not supported.
ArgumentNullException	filename is `null` .
DirectoryNotFoundException	The directory path specified in filename does not exist.
IOException	filename includes an invalid syntax for the path or file name.
PathTooLongException	The specified path, file name, or both exceeds the system-defined maximum length.
SecurityException	The caller does not have the required permissions.
UnauthorizedAccessException	Write access is not permitted by the operating system for the path specified in filename.

Description

If filename exists, it is truncated and overwritten with the new content.
If encoding is null , the file is written as UTF-8 and the encoding attribute is omitted from the processing instruction.
The following properties are initialized to the specified values:
System.Xml.XmlTextWriter.Formatting to System.Xml.Formatting.None.
System.Xml.XmlTextWriter.Indentation to 2.
System.Xml.XmlTextWriter.IndentChar to the space character.
System.Xml.XmlTextWriter.Namespaces to true .
System.Xml.XmlTextWriter.QuoteChar to the double quote character.
System.Xml.XmlTextWriter.WriteState to System.Xml.WriteState.Start.

XmlTextWriter(System.IO.TextWriter) Constructor

public XmlTextWriter(TextWriter w);

Summary

Constructs and initializes a new instance of the XmlTextWriter class.

Parameters

w

The TextWriter to write to, initialized to the correct encoding.

Description

The following properties are initialized to the specified values:
System.Xml.XmlTextWriter.Formatting to System.Xml.Formatting.None.
System.Xml.XmlTextWriter.Indentation to 2.
System.Xml.XmlTextWriter.IndentChar to the space character.
System.Xml.XmlTextWriter.Namespaces to true .
System.Xml.XmlTextWriter.QuoteChar to the double quote character.
System.Xml.XmlTextWriter.WriteState to System.Xml.WriteState.Start.
[Note: If a specific encoding is necessary, set the encoding using the constructor of w before instantiating the writer.
]

XmlTextWriter.Close Method

public override void Close();

Summary

Closes the writer.

Description

This method closes all elements and attributes created by the System.Xml.XmlTextWriter.WriteStartElement(System.String,System.String,System.String) and System.Xml.XmlTextWriter.WriteStartAttribute(System.String,System.String,System.String) methods, respectively, that are open when the System.Xml.XmlTextWriter.Close method is called.
This method calls the System.Xml.XmlTextWriter.Flush method to flush the underlying buffered stream and then closes the stream.
This method sets the System.Xml.XmlTextWriter.WriteState to System.Xml.WriteState.Closed.

XmlTextWriter.Flush Method

public override void Flush();

Summary

Clears all buffers and causes any buffered data to be written to the underlying stream.

Description

[Note: This method overrides System.Xml.XmlWriter.Flush.
]

XmlTextWriter.LookupPrefix Method

public override string LookupPrefix(string ns);

Summary

Returns the prefix defined in the current namespace scope for the specified namespace URI.

Parameters

ns

A String specifying the namespace URI.

Return Value

A String containing the corresponding prefix, or System.String.Empty if the prefix is not found and ns is the default namespace, or null if no matching namespace URI is found in the current scope.

Exceptions

Exception Type Condition

ArgumentException ns is null or System.String.Empty.

Exception Type	Condition
ArgumentException	ns is `null` or System.String.Empty.

Description

[Note: This method overrides System.Xml.XmlWriter.LookupPrefix(System.String).
]

XmlTextWriter.WriteBase64 Method

public override void WriteBase64(byte[] buffer, int index, int count);

Summary

Encodes the specified binary bytes as Base64 and writes the resulting text.

Parameters

buffer

A Byte array containing the bytes to encode.

index

A Int32 specifying the position within the array of the first byte to encode.

count

A Int32 specifying the number of bytes to encode.

Exceptions

Exception Type Condition

ArgumentNullException buffer is null .

ArgumentException The buffer length minus index is less than count.

ArgumentOutOfRangeException index or count is less than zero.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentNullException	buffer is `null` .
ArgumentException	The buffer length minus index is less than count.
ArgumentOutOfRangeException	index or count is less than zero.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

[Note: Base64 encoding represents byte sequences in a text form comprised of the 65 US-ASCII characters (A-Z, a-z, 0-9, +, /, =) where each character encodes 6 bits of the binary data.
For more information on Base64 encoding, see RFC 2045 (http://www.ietf.org/rfc/rfc2045).
This method overrides System.Xml.XmlWriter.WriteBase64(System.Byte[],System.Int32,System.Int32).
]

XmlTextWriter.WriteBinHex Method

public override void WriteBinHex(byte[] buffer, int index, int count);

Summary

Encodes the specified binary bytes as BinHex and writes the resulting text.

Parameters

buffer

A Byte array containing the bytes to encode.

index

A Int32 specifying the position within the array of the first byte to encode.

count

A Int32 specifying the number of bytes to encode.

Exceptions

Exception Type Condition

ArgumentNullException buffer is null .

ArgumentException The buffer length minus index is less than count.

ArgumentOutOfRangeException index or count is less than zero.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentNullException	buffer is `null` .
ArgumentException	The buffer length minus index is less than count.
ArgumentOutOfRangeException	index or count is less than zero.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

[Note: For information on BinHex encoding, see RFC 1741 (http://www.ietf.org/rfc/rfc1741).
This method overrides System.Xml.XmlWriter.WriteBinHex(System.Byte[],System.Int32,System.Int32).
]

XmlTextWriter.WriteCData Method

public override void WriteCData(string text);

Summary

Writes out a CDATA block containing the specified text.

Parameters

text

A String specifying the text to place inside the CDATA block.

Exceptions

Exception Type Condition

ArgumentException The text would result in a non-well formed XML document.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	The text would result in a non-well formed XML document.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method writes <![CDATA[text]]>.
If text is null or System.String.Empty, this method writes an empty CDATA block, <![CDATA[]]>.
[Note: This method overrides System.Xml.XmlWriter.WriteCData(System.String).
]

XmlTextWriter.WriteCharEntity Method

public override void WriteCharEntity(char ch);

Summary

Forces the generation of a character entity for the specified Unicode character value.

Parameters

ch

The Char for which to generate the entity.

Exceptions

Exception Type Condition

ArgumentException The character is in the surrogate pair character range, 0xd800 - 0xdfff, or the text would result in a non-well formed XML document.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	The character is in the surrogate pair character range, 0xd800 - 0xdfff, or the text would result in a non-well formed XML document.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method writes the Unicode character in hexadecimal character entity reference format.
[Note: This method overrides System.Xml.XmlWriter.WriteCharEntity(System.Char).
]

XmlTextWriter.WriteChars Method

public override void WriteChars(char[] buffer, int index, int count);

Summary

Writes text a buffer at a time.

Parameters

buffer

A Char array containing the text to write.

index

A Int32 specifying the position within the array of the start of the text to write.

count

A Int32 specifying the number of characters to write.

Exceptions

Exception Type Condition

ArgumentNullException buffer is null .

ArgumentOutOfRangeException index or count is less than zero.
- or -
The buffer length minus index is less than count.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentNullException	buffer is `null` .
ArgumentOutOfRangeException	index or count is less than zero. - or - The buffer length minus index is less than count.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

[Note: This method can be used to write large amounts of text a buffer at a time.
An exception is thrown if surrogate pair characters would be split across multiple buffer writes. This exception must be caught in order to continue writing the next surrogate pair characters. The XML specification defines the valid ranges for surrogate pairs.
This method overrides System.Xml.XmlWriter.WriteChars(System.Char[],System.Int32,System.Int32).
]

XmlTextWriter.WriteComment Method

public override void WriteComment(string text);

Summary

Writes out a comment containing the specified text.

Parameters

text

A String containing the text to place inside the comment.

Exceptions

Exception Type Condition

ArgumentException The text would result in a non-well formed XML document

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	The text would result in a non-well formed XML document
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method writes .
If text is null or System.String.Empty , this method writes a comment with no content, .
[Note: This method overrides System.Xml.XmlWriter.WriteComment(System.String).
]

XmlTextWriter.WriteDocType Method

public override void WriteDocType(string name, string pubid, string sysid, string subset);

Summary

Writes the document type declaration with the specified name and optional attributes.

Parameters

name

A String specifying the name of the document type.

pubid

A String specifying the public identifier, which is an alternative to the system identifier.

sysid

A String specifying the system identifier, which is the URI of the DTD (document type definition) for the document.

subset

A String specifying a URI that contains markup declarations.

Exceptions

Exception Type Condition

ArgumentException name is null or System.String.Empty.
-or-
The value for name would result in invalid XML.

InvalidOperationException This method was called outside the prolog (after the root element).

Exception Type	Condition
ArgumentException	name is `null` or System.String.Empty. -or- The value for name would result in invalid XML.
InvalidOperationException	This method was called outside the prolog (after the root element).

Description

The optional attributes, pubid, sysid, and subset, are not checked for invalid characters.
[Note: A document type declaration is of the following form:
<!DOCTYPE name PUBLIC "pubid" "sysid" [subset]>
This method overrides System.Xml.XmlWriter.WriteDocType(System.String,System.String,System.String,System.String).
]

XmlTextWriter.WriteEndAttribute Method

public override void WriteEndAttribute();

Summary

Closes the attribute started with the System.Xml.XmlTextWriter.WriteStartAttribute(System.String,System.String,System.String) method.

Exceptions

Exception Type Condition

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

[Note: The System.Xml.XmlTextWriter.WriteStartAttribute(System.String,System.String,System.String) and System.Xml.XmlTextWriter.WriteEndElement methods also will close an open attribute if one exists when they are called.
This method overrides System.Xml.XmlWriter.WriteEndAttribute.
]

XmlTextWriter.WriteEndDocument Method

public override void WriteEndDocument();

Summary

Closes open elements and attributes and sets the System.Xml.XmlTextWriter.WriteState back to the System.Xml.WriteState.Start state.

Exceptions

Exception Type Condition

ArgumentException The current instance is in the wrong WriteState, or the document does not have a root element.

Exception Type	Condition
ArgumentException	The current instance is in the wrong WriteState, or the document does not have a root element.

Description

This method closes all elements and attributes created by the System.Xml.XmlTextWriter.WriteStartElement(System.String,System.String,System.String) and System.Xml.XmlTextWriter.WriteStartAttribute(System.String,System.String,System.String) methods, respectively, that are open when the System.Xml.XmlTextWriter.WriteEndDocument method is called.
[Note: After calling this method, the current instance can be used to write a new XML document.
This method overrides System.Xml.XmlWriter.WriteEndDocument.
]

XmlTextWriter.WriteEndElement Method

public override void WriteEndElement();

Summary

Closes an open element and pops the corresponding namespace scope.

Exceptions

Exception Type Condition

InvalidOperationException No element was open, or the System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
InvalidOperationException	No element was open, or the System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

If the open element does not contain content, it is closed as an empty element using " />"; otherwise an end element is written.
[Note: This method overrides System.Xml.XmlWriter.WriteEndElement.
]

XmlTextWriter.WriteEntityRef Method

public override void WriteEntityRef(string name);

Summary

Writes an entity reference with the specified name.

Parameters

name

A String specifying the name of the entity reference.

Exceptions

Exception Type Condition

ArgumentException A String containing the text would result in a non-well formed XML document, or name is either null or System.String.Empty.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	A String containing the text would result in a non-well formed XML document, or name is either `null` or System.String.Empty.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method writes %name;.
[Note: This method overrides System.Xml.XmlWriter.WriteEntityRef(System.String).
]

XmlTextWriter.WriteFullEndElement Method

public override void WriteFullEndElement();

Summary

Closes an open element and pops the corresponding namespace scope.

Exceptions

Exception Type Condition

InvalidOperationException No start tag was open, or the System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
InvalidOperationException	No start tag was open, or the System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method writes an end element regardless of whether there is any content in the element.
[Note: This method overrides System.Xml.XmlWriter.WriteFullEndElement.
]

XmlTextWriter.WriteName Method

public override void WriteName(string name);

Summary

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

Parameters

name

A String specifying the name to write.

Exceptions

Exception Type Condition

ArgumentException name is null or System.String.Empty; or name is not a valid XML Name.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	name is `null` or System.String.Empty; or name is not a valid XML Name.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

If System.Xml.XmlTextWriter.Namespaces is set to true , this method checks that name is also valid according to the W3C Namespaces in XML recommendation (http://www.w3.org/TR/REC-xml-names).
[Note: This method overrides System.Xml.XmlWriter.WriteName(System.String).
]

XmlTextWriter.WriteNmToken Method

public override void WriteNmToken(string name);

Summary

Writes out the specified name, ensuring it is a valid name token (Nmtoken) according to the W3C XML 1.0 recommendation (http://www.w3.org/TR/1998/REC-xml-19980210#NT-Name).

Parameters

name

A String specifying the name to write.

Exceptions

Exception Type Condition

ArgumentException name is null or System.String.Empty; or name is not a valid XML Nmtoken.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	name is `null` or System.String.Empty; or name is not a valid XML Nmtoken.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

[Note: This method overrides System.Xml.XmlWriter.WriteNmToken(System.String).
]

XmlTextWriter.WriteProcessingInstruction Method

public override void WriteProcessingInstruction(string name, string text);

Summary

Writes out a processing instruction with the specified name and text.

Parameters

name

A String specifying the name of the processing instruction.

text

A String specifying the text to include in the processing instruction.

Exceptions

Exception Type Condition

ArgumentException The text would result in a non-well formed XML document.
- or -
name is null or System.String.Empty.
- or -
This method is being used to create an XML declaration after System.Xml.XmlTextWriter.WriteStartDocument has already been called.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	The text would result in a non-well formed XML document. - or - name is `null` or System.String.Empty. - or - This method is being used to create an XML declaration after System.Xml.XmlTextWriter.WriteStartDocument has already been called.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method writes <?nametext?>.
If text is null or System.String.Empty, this method writes a processing instruction with no text content, <?name?>.
[Note: This method overrides System.Xml.XmlWriter.WriteProcessingInstruction(System.String,System.String).
]

XmlTextWriter.WriteQualifiedName Method

public override void WriteQualifiedName(string localName, string ns);

Summary

Writes out the qualified name.

Parameters

localName

A String specifying the local name to write.

ns

A String specifying the namespace URI to associate with localname.

Exceptions

Exception Type Condition

ArgumentException localName is null or System.String.Empty.
-or-
System.Xml.XmlTextWriter.Namespaces is false , and ns is neither null nor System.String.Empty .

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

XmlException localName is not a valid XML name.

Exception Type	Condition
ArgumentException	localName is `null` or System.String.Empty. -or- System.Xml.XmlTextWriter.Namespaces is `false` , and ns is neither `null` nor System.String.Empty .
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.
XmlException	localName is not a valid XML name.

Description

If ns maps to the current default namespace, no prefix is generated.
When writing attribute values, this method generates a prefix if ns is not found. When writing element content, this method throws an exception if ns is not found.
If the current instance supports namespaces (System.Xml.XmlTextWriter.Namespaces is set to true ), this method looks up the prefix that is in scope for the given namespace and checks that the name is valid according to the W3C Namespaces in XML recommendation (http://www.w3.org/TR/REC-xml-names).
[Note: This method overrides System.Xml.XmlWriter.WriteQualifiedName(System.String,System.String).
]

XmlTextWriter.WriteRaw(System.String) Method

public override void WriteRaw(string data);

Summary

Writes raw text from a string.

Parameters

data

A String specifying the text to write.

Exceptions

Exception Type Condition

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

If data is null , System.String.Empty is written.
This method does not encode any characters.
[Note: This method overrides System.Xml.XmlWriter.WriteRaw(System.Char[],System.Int32,System.Int32).
]

XmlTextWriter.WriteRaw(char[], int, int) Method

public override void WriteRaw(char[] buffer, int index, int count);

Summary

Writes raw text from a character array.

Parameters

buffer

A Char array containing the text to write.

index

A Int32 specifying the position within the array of the start of the text to write.

count

A Int32 specifying the number of characters to write.

Exceptions

Exception Type Condition

ArgumentNullException buffer is null .

ArgumentOutOfRangeException index or count is less than zero.
- or -
The buffer length minus index is less than count.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentNullException	buffer is `null` .
ArgumentOutOfRangeException	index or count is less than zero. - or - The buffer length minus index is less than count.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method does not encode any characters.
[Note: This method overrides System.Xml.XmlWriter.WriteRaw(System.Char[],System.Int32,System.Int32).
]

XmlTextWriter.WriteStartAttribute Method

public override void WriteStartAttribute(string prefix, string localName, string ns);

Summary

Writes the start of an attribute with the specified prefix and name, and associates the prefix with the specified namespace URI.

Parameters

prefix

A String specifying the namespace prefix of the attribute.

localName

A String specifying the local name of the attribute.

ns

A String specifying the namespace URI associated with the attribute.

Exceptions

Exception Type Condition

ArgumentException System.Xml.XmlTextWriter.Namespaces is false for the writer, and prefix and ns are not both null .

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	System.Xml.XmlTextWriter.Namespaces is `false` for the writer, and prefix and ns are not both `null` .
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

If any of the input parameters are null or System.String.Empty, the start attribute is written with that parameter missing.
[Note: This method overrides System.Xml.XmlWriter.WriteStartAttribute(System.String,System.String).
]

XmlTextWriter.WriteStartDocument(bool) Method

public override void WriteStartDocument(bool standalone);

Summary

Writes the XML declaration with the version "1.0" and the standalone attribute.

Parameters

standalone

A Boolean where true indicates to write "yes" as the value for the standalone attribute, and false indicates to write "no".

Exceptions

Exception Type Condition

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is not System.Xml.WriteState.Start.

Exception Type	Condition
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is not System.Xml.WriteState.Start.

Description

[Note: When XmlTextWriter is instantiated, the System.Xml.XmlTextWriter.WriteState is set to System.Xml.WriteState.Start. All the "write" methods change the System.Xml.XmlTextWriter.WriteState to a value other than Start . Thus, if this method is not the first "write" method called, a InvalidOperationException is thrown.
If System.Xml.XmlTextWriter.WriteStartDocument has been called and then the System.Xml.XmlTextWriter.WriteProcessingInstruction(System.String,System.String) method is used to create another XML declaration, a ArgumentException will be thrown.
The output of this method with standalone equal to true , an encoding equal to System.Text.Encoding.Unicode, and using the default System.Xml.XmlTextWriter.QuoteChar is:
<?xml version="1.0" encoding="utf-16" standalone="yes"?>
Character encoding is set when the writer is instantiated.
This method overrides System.Xml.XmlWriter.WriteStartDocument.
]

XmlTextWriter.WriteStartDocument() Method

public override void WriteStartDocument();

Summary

Writes the XML declaration with the version "1.0" and no standalone attribute.

Exceptions

Exception Type Condition

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is not System.Xml.WriteState.Start.

Description

[Note: When XmlTextWriter is instantiated, the System.Xml.XmlTextWriter.WriteState is set to System.Xml.WriteState.Start. All the "write" methods change the System.Xml.XmlTextWriter.WriteState to a value other than Start . Thus, if this method is not the first "write" method called, a InvalidOperationException is thrown.
If System.Xml.XmlTextWriter.WriteStartDocument has been called and then the System.Xml.XmlTextWriter.WriteProcessingInstruction(System.String,System.String) method is used to create another XML declaration, a ArgumentException will be thrown.
The output of this method using an encoding equal to System.Text.Encoding.Unicode and the default System.Xml.XmlTextWriter.QuoteChar is
<?xml version="1.0" encoding="utf-16"?>
Character encoding is set when the writer is instantiated.
This method overrides System.Xml.XmlWriter.WriteStartDocument.
]

XmlTextWriter.WriteStartElement Method

public override void WriteStartElement(string prefix, string localName, string ns);

Summary

Writes a start element with the specified name, and associates it with the given namespace and prefix.

Parameters

prefix

A String specifying the namespace prefix of the element.

localName

A String specifying the local name of the element.

ns

A String specifying the namespace URI to associate with the element.

Exceptions

Exception Type Condition

ArgumentException System.Xml.XmlTextWriter.Namespaces is false for the writer, and prefix and ns are not both null .

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

If ns is already in scope and has an associated prefix, the current instance will automatically write that prefix also.
If any of the input parameters are null or System.String.Empty, the start element is written with that parameter missing.
[Note: Write any attributes using the System.Xml.XmlTextWriter.WriteStartAttribute(System.String,System.String,System.String), System.Xml.XmlTextWriter.WriteString(System.String), and System.Xml.XmlTextWriter.WriteEndAttribute methods, then close the element using the System.Xml.XmlTextWriter.WriteEndElement method.
This method overrides System.Xml.XmlWriter.WriteStartElement(System.String,System.String).
]

Example

This example demonstrates the System.Xml.XmlTextWriter.WriteStartElement(System.String,System.String,System.String) method, writing the XML to the console.
using System;
using System.Xml;

public class WriteXml 
{
  public static void Main() 
  {
    XmlTextWriter xWriter =
      new XmlTextWriter(Console.Out);
    xWriter.WriteStartDocument();
    xWriter.WriteStartElement("prefix","element", "namespace");
    xWriter.WriteEndDocument();
  }
}
The output is
<?xml version="1.0" encoding= "someencoding"?>
<prefix:element xmlns:prefix="namespace" />
The value of the encoding attribute is the encoding of the output stream of the console.

XmlTextWriter.WriteString Method

public override void WriteString(string text);

Summary

Writes the specified text.

Parameters

text

A String specifying the text to write.

Exceptions

Exception Type Condition

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed and text is neither null nor System.String.Empty.

Description

This method performs the following conversions before writing the text:

The characters '&', '<', and '>' are replaced with "&", "<", and ">", respectively.

Character values in the range 0x-0x1F (excluding the white space characters 0x9, 0x10, and 0x13) are replaced with numeric character entities ("" through "&#0x1F").

If called in the context of an attribute value, double and single quotes are replaced with """ and "'" respectively.

If text is null or System.String.Empty, this method writes a text node with no data content.
[Note: This method overrides System.Xml.XmlWriter.WriteString(System.String).
]

Example

The following example demonstrates the conversions performed by this method.
using System;
using System.Xml;

public class WriteFrag {

  public static void Main() {

    XmlTextWriter xtWriter =
      new XmlTextWriter(Console.Out);
    xtWriter.WriteString("<1 & 2 = 3>");
  }
}
   
The output is
&lt;1 & 2 = 3>

XmlTextWriter.WriteSurrogateCharEntity Method

public override void WriteSurrogateCharEntity(char lowChar, char highChar);

Summary

Generates and writes the surrogate character entity for the surrogate character pair.

Parameters

lowChar

A Char containing the low surrogate. This must be a value between 0xDC00 and 0xDFFF.

highChar

A Char containing the high surrogate. This must be a value between 0xD800 and 0xDBFF.

Exceptions

Exception Type Condition

ArgumentException An invalid surrogate character pair was passed.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

This method only applies to a writer that uses the UTF-16 encoding type.
The surrogate character entity is written in hexadecimal format. The range for surrogate characters is #x10000 to #x10FFFF. The following formula is used to generate the surrogate character entity: (highChar - 0xD800) * 0x400 + (lowChar - 0xDC00) + 0x10000.
[Note: For both HTML and XML, the document character set (and therefore the notation of numeric character references) is based on UCS [ISO-10646]. A single numeric character reference in a source document may therefore in some cases correspond to two 16-bit units in a string (a high surrogate and a low surrogate). These 16-bit units are referred to as a surrogate pair.
For more information regarding surrogates or characters, refer to section 3.7 of the Unicode 3.0/Unicode 2.0 standard located at http://www.unicode.org, or section 2.2 of the W3C XML 1.0 Recommendation located at http://www.w3.org/TR/REC-xml#charsets .
This method overrides System.Xml.XmlWriter.WriteSurrogateCharEntity(System.Char,System.Char).
]

XmlTextWriter.WriteWhitespace Method

public override void WriteWhitespace(string ws);

Summary

Writes the given white space.

Parameters

ws

A String containing the white space characters.

Exceptions

Exception Type Condition

ArgumentException ws is null or System.String.Empty or contains non-white space characters.

InvalidOperationException The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Description

[Note: This method is used to manually format a document. Use the System.Xml.XmlTextWriter.Formatting property to have the current instance format the output automatically.
This method overrides System.Xml.XmlWriter.WriteWhitespace(System.String).
]

XmlTextWriter.BaseStream Property

public Stream BaseStream { get; }

Summary

Gets the underlying stream used by the writer.

Property Value

A Stream, or null if the current instance does not use an underlying stream.

Description

This property is read-only.
If the current instance was constructed using a TextWriter that is a subclass of the StreamWriter class, this property is equivalent to the System.IO.StreamWriter.BaseStream property.
If the writer was constructed using a Stream, this property returns the Stream passed to the constructor.
If the writer was constructed using a file name, this property returns the Stream representing the file.

XmlTextWriter.Formatting Property

public Formatting Formatting { get; set; }

Summary

Indicates how the output is formatted.

Property Value

One of the members of the Formatting enumeration. The default is System.Xml.Formatting.None (no special formatting).

Description

If this property is set to System.Xml.Formatting.Indented, child elements are indented using the System.Xml.XmlTextWriter.Indentation and System.Xml.XmlTextWriter.IndentChar properties. Only element content will be indented.
[Note: Writing any text content, including System.String.Empty, puts that element into mixed content mode. Child elements do not inherit this "mixed" mode status. A child element of a "mixed" element will do indenting, unless it is also contains "mixed" content. Element content (http://www.w3.org/TR/1998/REC-xml-19980210#sec-element-content) and mixed content (http://www.w3.org/TR/1998/REC-xml-19980210#sec-mixed-content) are defined according to the XML 1.0 definitions of these terms.
]

XmlTextWriter.IndentChar Property

public char IndentChar { get; set; }

Summary

Gets or sets the character to use for indenting when System.Xml.XmlTextWriter.Formatting is set to System.Xml.Formatting.Indented.

Property Value

A Char specifying the character to use for indenting. The default is space (character code 0x20).

Description

[Note: This property can be set to any character. To ensure valid XML, set this property to a valid white space character: 0x9, 0x10, 0x13, or 0x20.
]

XmlTextWriter.Indentation Property

public int Indentation { get; set; }

Summary

Gets or sets how many indentation characters to write for each level in the hierarchy when System.Xml.XmlTextWriter.Formatting is set to System.Xml.Formatting.Indented.

Property Value

A Int32 specifying the number of System.Xml.XmlTextWriter.IndentChar characters to use for each level. The default is 2.

Exceptions

Exception Type Condition

ArgumentException The value to be set is less than zero.

Description

Indentation is performed on the following members of XmlNodeType: DocumentType , Element , Comment , ProcessingInstruction , and CDATA . All other node types are not affected. The XmlTextWriter class does not indent the internal DTD subset.

XmlTextWriter.Namespaces Property

public bool Namespaces { get; set; }

Summary

Gets or sets a value indicating whether the writer supports namespaces.

Property Value

A Boolean where true indicates the writer supports namespaces; otherwise, false . The default is true .

Exceptions

Exception Type Condition

InvalidOperationException The System.Xml.XmlTextWriter.WriteState of the current instance is not System.Xml.WriteState.Start.

Description

This property determines whether the writer supports the XML Namespaces specification (http://www.w3.org/TR/REC-xml-names).
If an attempt is made to set this property after a write operation has occurred, a InvalidOperationException is thrown.

XmlTextWriter.QuoteChar Property

public char QuoteChar { get; set; }

Summary

Gets or sets the character used to quote the value of an attribute.

Property Value

A Char specifying the quotation mark character (" or ') used to enclose the value of an attribute. The default is the double quote.

Exceptions

Exception Type Condition

ArgumentException The value to be set is not the single quote or double quote character.

XmlTextWriter.WriteState Property

public override WriteState WriteState { get; }

Summary

Gets the write state of the writer.

Property Value

One of the members of the WriteState enumeration.

Description

This property is read-only.
[Note: This property overrides System.Xml.XmlWriter.WriteState.
]

XmlTextWriter.XmlLang Property

public override string XmlLang { get; }

Summary

Gets the language attribute, xml:lang, specifying the language in which the content and attribute values of the current element are written.

Property Value

A String containing the language attribute, or null if the language attribute is not specified for the element.

Description

This property is read-only.
[Note: This property overrides System.Xml.XmlWriter.XmlLang.
]

XmlTextWriter.XmlSpace Property

public override XmlSpace XmlSpace { get; }

Summary

Gets the white space attribute, xml:space, specifying how white space is handled in the current element.

Property Value

One of the members of the XmlSpace enumeration, or System.Xml.XmlSpace.None if the white space attribute is not specified for the element.

Description

This property is read-only.
[Note: This property overrides System.Xml.XmlWriter.XmlSpace.
]

Exception Type	Condition
ArgumentException	An invalid surrogate character pair was passed.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

Exception Type	Condition
ArgumentException	ws is `null` or System.String.Empty or contains non-white space characters.
InvalidOperationException	The System.Xml.XmlTextWriter.WriteState is System.Xml.WriteState.Closed.

System.Xml.XmlTextWriter Class

Base Types

Assembly

Library

Summary

Description

Example

See Also

Members

XmlTextWriter(System.IO.Stream, System.Text.Encoding) Constructor

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter(System.String, System.Text.Encoding) Constructor

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter(System.IO.TextWriter) Constructor

Summary

Parameters

Description

See Also

XmlTextWriter.Close Method

Summary

Description

See Also

XmlTextWriter.Flush Method

Summary

Description

See Also

XmlTextWriter.LookupPrefix Method

Summary

Parameters

Return Value

Exceptions

Description

See Also

XmlTextWriter.WriteBase64 Method

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter.WriteBinHex Method

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter.WriteCData Method

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter.WriteCharEntity Method

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter.WriteChars Method

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter.WriteComment Method

Summary

Parameters

Exceptions

Description

See Also

XmlTextWriter.WriteDocType Method

Summary

Parameters