Class XMLWriter

Filter to write an XML document from a SAX event stream.

Inheritance
object
XMLFilter
XMLWriter
Inherited Members
Namespace: TagSoup
Assembly: Lucene.Net.Benchmark.dll
Syntax
public class XMLWriter : XMLFilter, IXMLFilter, IXMLReader, IEntityResolver, IDTDHandler, IContentHandler, IErrorHandler, ILexicalHandler
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Constructors

XMLWriter()

Create a new XML writer.

Write to standard output.

Declaration
public XMLWriter()
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

XMLWriter(IXMLReader)

Create a new XML writer.

Use the specified XML reader as the parent.

Declaration
public XMLWriter(IXMLReader xmlreader)
Parameters
Type Name Description
IXMLReader xmlreader

The parent in the filter chain, or null for no parent.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

XMLWriter(IXMLReader, TextWriter)

Create a new XML writer.

Use the specified XML reader as the parent, and write to the specified writer.

Declaration
public XMLWriter(IXMLReader xmlreader, TextWriter writer)
Parameters
Type Name Description
IXMLReader xmlreader

The parent in the filter chain, or null for no parent.
TextWriter writer

The output destination, or null to use standard output.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

XMLWriter(TextWriter)

Create a new XML writer.

Write to the writer provided.

Declaration
public XMLWriter(TextWriter writer)
Parameters
Type Name Description
TextWriter writer

The output destination, or null to use standard output.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

Fields

CDATA_SECTION_ELEMENTS

Filter to write an XML document from a SAX event stream.

Declaration
public const string CDATA_SECTION_ELEMENTS = "cdata-section-elements"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

DOCTYPE_PUBLIC

Filter to write an XML document from a SAX event stream.

Declaration
public const string DOCTYPE_PUBLIC = "doctype-public"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

DOCTYPE_SYSTEM

Filter to write an XML document from a SAX event stream.

Declaration
public const string DOCTYPE_SYSTEM = "doctype-system"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

ENCODING

Filter to write an XML document from a SAX event stream.

Declaration
public const string ENCODING = "encoding"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

INDENT

Filter to write an XML document from a SAX event stream.

Declaration
public const string INDENT = "indent"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

MEDIA_TYPE

Filter to write an XML document from a SAX event stream.

Declaration
public const string MEDIA_TYPE = "media-type"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

METHOD

Filter to write an XML document from a SAX event stream.

Declaration
public const string METHOD = "method"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

OMIT_XML_DECLARATION

Filter to write an XML document from a SAX event stream.

Declaration
public const string OMIT_XML_DECLARATION = "omit-xml-declaration"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

STANDALONE

Filter to write an XML document from a SAX event stream.

Declaration
public const string STANDALONE = "standalone"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

VERSION

Filter to write an XML document from a SAX event stream.

Declaration
public const string VERSION = "version"
Field Value
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

Methods

Characters(char[], int, int)

Write character data. Pass the event on down the filter chain for further processing.

Declaration
public override void Characters(char[] ch, int start, int length)
Parameters
Type Name Description
char[] ch

The array of characters to write.
int start

The starting position in the array.
int length

The number of characters to write.
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the characters, or if a handler further down the filter chain raises an exception.
See Also

Characters(string)

Write a string of character data, with XML escaping.

This is a convenience method that takes an XML string, converts it to a character array, then invokes Characters(char[], int, int).

Declaration
public virtual void Characters(string data)
Parameters
Type Name Description
string data

The character data.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the string, or if a handler further down the filter chain raises an exception.
See Also

Comment(char[], int, int)

Report an XML comment anywhere in the document.

This callback will be used for comments inside or outside the document element, including comments in the external DTD subset(if read). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events(if used).
Declaration
public virtual void Comment(char[] ch, int start, int length)
Parameters
Type Name Description
char[] ch

An array holding the characters in the comment.
int start

The starting position in the array.
int length

The number of characters to use from the array.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

DataElement(string, string)

Write an element with character data content but no attributes or Namespace URI.

This is a convenience method to write a complete element with character data content, including the start tag and end tag. The method provides an empty string for the Namespace URI, and empty string for the qualified name, and an empty attribute list.

This method invokes StartElement(string, string, string, IAttributes), followed by Characters(string), followed by EndElement(string, string, string).

Declaration
public virtual void DataElement(string localName, string content)
Parameters
Type Name Description
string localName

The element's local name.
string content

The character data content.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.
See Also

DataElement(string, string, string)

Write an element with character data content but no attributes.

This is a convenience method to write a complete element with character data content, including the start tag and end tag. This method provides an empty string for the qname and an empty attribute list.

This method invokes StartElement(string, string, string, IAttributes), followed by Characters(string), followed by EndElement(string, string, string).

Declaration
public virtual void DataElement(string uri, string localName, string content)
Parameters
Type Name Description
string uri

The element's Namespace URI.
string localName

The element's local name.
string content

The character data content.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.
See Also

DataElement(string, string, string, IAttributes, string)

Write an element with character data content.

This is a convenience method to write a complete element with character data content, including the start tag and end tag.

This method invokes StartElement(string, string, string, IAttributes), followed by Characters(string), followed by EndElement(string, string, string).

Declaration
public virtual void DataElement(string uri, string localName, string qName, IAttributes atts, string content)
Parameters
Type Name Description
string uri

The element's Namespace URI.
string localName

The element's local name.
string qName

The element's default qualified name.
IAttributes atts

The element's attributes.
string content

The character data content.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.
See Also

EmptyElement(string)

Add an empty element without a Namespace URI, qname or attributes.

This method will supply an empty string for the qname, and empty string for the Namespace URI, and an empty attribute list. It invokes EmptyElement(string, string, string, IAttributes) directly.

Declaration
public virtual void EmptyElement(string localName)
Parameters
Type Name Description
string localName

The element's local name.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.
See Also

EmptyElement(string, string)

Add an empty element without a qname or attributes.

This method will supply an empty string for the qname and an empty attribute list. It invokes EmptyElement(string, string, string, IAttributes) directly.

Declaration
public virtual void EmptyElement(string uri, string localName)
Parameters
Type Name Description
string uri

The element's Namespace URI.
string localName

The element's local name.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.
See Also

EmptyElement(string, string, string, IAttributes)

Write an empty element. This method writes an empty element tag rather than a start tag followed by an end tag. Both a StartElement(string, string, string, IAttributes) and an EndElement(string, string, string) event will be passed on down the filter chain.

Declaration
public virtual void EmptyElement(string uri, string localName, string qName, IAttributes atts)
Parameters
Type Name Description
string uri

The element's Namespace URI, or the empty string if the element has no Namespace or if Namespace processing is not being performed.
string localName

The element's local name (without prefix). This parameter must be provided.
string qName

The element's qualified name (with prefix), or the empty string if none is available. This parameter is strictly advisory: the writer may or may not use the prefix attached.
IAttributes atts

The element's attribute list.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the empty tag, or if a handler further down the filter chain raises an exception.
See Also

EndCDATA()

Report the end of a CDATA section.

Declaration
public virtual void EndCDATA()
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

EndDTD()

Report the end of DTD declarations.

This method is intended to report the end of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.
Declaration
public virtual void EndDTD()
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

EndDocument()

Write a newline at the end of the document. Pass the event on down the filter chain for further processing.

Declaration
public override void EndDocument()
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the newline, or if a handler further down the filter chain raises an exception.
See Also

EndElement(string)

End an element without a Namespace URI or qname.

This method will supply an empty string for the qName and an empty string for the Namespace URI. It invokes EndElement(string, string, string) directly.

Declaration
public virtual void EndElement(string localName)
Parameters
Type Name Description
string localName

The element's local name.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the end tag, or if a handler further down the filter chain raises an exception.
See Also

EndElement(string, string)

End an element without a qname.

This method will supply an empty string for the qName. It invokes EndElement(string, string, string) directly.

Declaration
public virtual void EndElement(string uri, string localName)
Parameters
Type Name Description
string uri

The element's Namespace URI.
string localName

The element's local name.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the end tag, or if a handler further down the filter chain raises an exception.
See Also

EndElement(string, string, string)

Write an end tag. Pass the event on down the filter chain for further processing.

Declaration
public override void EndElement(string uri, string localName, string qName)
Parameters
Type Name Description
string uri

The Namespace URI, or the empty string if none is available.
string localName

The element's local (unprefixed) name (required).
string qName

The element's qualified (prefixed) name, or the empty string is none is available. This method will use the qName as a template for generating a prefix if necessary, but it is not guaranteed to use the same qName.
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the end tag, or if a handler further down the filter chain raises an exception.
See Also

EndEntity(string)

Report the end of an entity.

Declaration
public virtual void EndEntity(string name)
Parameters
Type Name Description
string name

The name of the entity that is ending.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

Flush()

Flush the output.

This method flushes the output stream. It is especially useful when you need to make certain that the entire document has been written to output but do not want to close the output stream.

This method is invoked automatically by the EndDocument() method after writing a document.

Declaration
public virtual void Flush()
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

ForceNSDecl(string)

Force a Namespace to be declared on the root element.

By default, the XMLWriter will declare only the Namespaces needed for an element; as a result, a Namespace may be declared many places in a document if it is not used on the root element.

This method forces a Namespace to be declared on the root element even if it is not used there, and reduces the number of xmlns attributes in the document.

Declaration
public virtual void ForceNSDecl(string uri)
Parameters
Type Name Description
string uri

The Namespace URI to declare.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

ForceNSDecl(string, string)

Force a Namespace declaration with a preferred prefix.

This is a convenience method that invokes SetPrefix(string, string) then ForceNSDecl(string).

Declaration
public virtual void ForceNSDecl(string uri, string prefix)
Parameters
Type Name Description
string uri

The Namespace URI to declare on the root element.
string prefix

The preferred prefix for the Namespace, or "" for the default Namespace.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

GetOutputProperty(string)

Filter to write an XML document from a SAX event stream.

Declaration
public virtual string GetOutputProperty(string key)
Parameters
Type Name Description
string key
Returns
Type Description
string
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

GetPrefix(string)

Get the current or preferred prefix for a Namespace URI.

Declaration
public virtual string GetPrefix(string uri)
Parameters
Type Name Description
string uri

The Namespace URI.
Returns
Type Description
string

The preferred prefix, or "" for the default Namespace.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

IgnorableWhitespace(char[], int, int)

Write ignorable whitespace. Pass the event on down the filter chain for further processing.

Declaration
public override void IgnorableWhitespace(char[] ch, int start, int length)
Parameters
Type Name Description
char[] ch

The array of characters to write.
int start

The starting position in the array.
int length

The number of characters to write.
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the whitespace, or if a handler further down the filter chain raises an exception.
See Also

ProcessingInstruction(string, string)

Write a processing instruction. Pass the event on down the filter chain for further processing.

Declaration
public override void ProcessingInstruction(string target, string data)
Parameters
Type Name Description
string target

The PI target.
string data

The PI data.
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the PI, or if a handler further down the filter chain raises an exception.
See Also

Reset()

Reset the writer.

This method is especially useful if the writer throws an exception before it is finished, and you want to reuse the writer for a new document. It is usually a good idea to invoke Flush() before resetting the writer, to make sure that no output is lost.

This method is invoked automatically by the StartDocument() method before writing a new document.

Note: this method will not clear the prefix or URI information in the writer or the selected output writer.

Declaration
public virtual void Reset()
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

SetOutput(TextWriter)

Set a new output destination for the document.

Declaration
public virtual void SetOutput(TextWriter writer)
Parameters
Type Name Description
TextWriter writer

The output destination, or null to use standard output.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

SetOutputProperty(string, string)

Filter to write an XML document from a SAX event stream.

Declaration
public virtual void SetOutputProperty(string key, string value)
Parameters
Type Name Description
string key
string value
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

SetPrefix(string, string)

Specify a preferred prefix for a Namespace URI.

Note that this method does not actually force the Namespace to be declared; to do that, use the ForceNSDecl(string) method as well.

Declaration
public virtual void SetPrefix(string uri, string prefix)
Parameters
Type Name Description
string uri

The Namespace URI.
string prefix

The preferred prefix, or "" to select the default Namespace.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

See Also

StartCDATA()

Report the start of a CDATA section.

Declaration
public virtual void StartCDATA()
Remarks

The contents of the CDATA section will be reported through the regular Characters(char[], int, int) event; this event is intended only to report the boundary.

Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

StartDTD(string, string, string)

Report the start of DTD declarations, if any.

Declaration
public virtual void StartDTD(string name, string publicId, string systemId)
Parameters
Type Name Description
string name

The document type name.
string publicId

The declared public identifier for the external DTD subset, or null if none was declared.
string systemId

The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)
Remarks

This method is intended to report the beginning of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

All declarations reported through IDTDHandler or IDeclHandler events must appear between the startDTD and EndDTD() events. Declarations are assumed to belong to the internal DTD subset unless they appear between StartEntity(string) and EndEntity(string) events. Comments and processing instructions from the DTD should also be reported between the StartDTD(string, string, string) and EndDTD() events, in their original order of(logical) occurrence; they are not required to appear in their correct locations relative to IDTDHandler or IDeclHandler events, however.

Note that the start / endDTD events will appear within the start / endDocument events from IContentHandler and before the first StartElement(string, string, string, IAttributes) event.
Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

StartDocument()

Write the XML declaration at the beginning of the document. Pass the event on down the filter chain for further processing.

Declaration
public override void StartDocument()
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the XML declaration, or if a handler further down the filter chain raises an exception.
See Also

StartElement(string)

Start a new element without a qname, attributes or a Namespace URI.

This method will provide an empty string for the Namespace URI, and empty string for the qualified name, and a default empty attribute list. It invokes #startElement(string, string, string, Attributes)} directly.

Declaration
public virtual void StartElement(string localName)
Parameters
Type Name Description
string localName

The element's local name.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the start tag, or if a handler further down the filter chain raises an exception.
See Also

StartElement(string, string)

Start a new element without a qname or attributes.

This method will provide a default empty attribute list and an empty string for the qualified name. It invokes StartElement(string, string, string, IAttributes) directly.

Declaration
public virtual void StartElement(string uri, string localName)
Parameters
Type Name Description
string uri

The element's Namespace URI.
string localName

The element's local name.
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the start tag, or if a handler further down the filter chain raises an exception.
See Also

StartElement(string, string, string, IAttributes)

Write a start tag. Pass the event on down the filter chain for further processing.

Declaration
public override void StartElement(string uri, string localName, string qName, IAttributes atts)
Parameters
Type Name Description
string uri

The Namespace URI, or the empty string if none is available.
string localName

The element's local (unprefixed) name (required).
string qName

The element's qualified (prefixed) name, or the empty string is none is available. This method will use the qName as a template for generating a prefix if necessary, but it is not guaranteed to use the same qName.
IAttributes atts

The element's attribute list (must not be null).
Overrides
Remarks

This class can be used by itself or as part of a SAX event stream: it takes as input a series of SAX2 ContentHandler events and uses the information in those events to write an XML document. Since this class is a filter, it can also pass the events on down a filter chain for further processing (you can use the XMLWriter to take a snapshot of the current state at any point in a filter chain), and it can be used directly as a ContentHandler for a SAX2 XMLReader.

The client creates a document by invoking the methods for standard SAX2 events, always beginning with the StartDocument() method and ending with the EndDocument() method. There are convenience methods provided so that clients to not have to create empty attribute lists or provide empty strings as parameters; for example, the method invocation 

w.StartElement("foo");

is equivalent to the regular SAX2 ContentHandler method

w.StartElement("", "foo", "", new Attributes());

Except that it is more efficient because it does not allocate a new empty attribute list each time. The following code will send a simple XML document to standard output: 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.StartElement("greeting");
    w.Characters("Hello, world!");
    w.EndElement("greeting");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <greeting>Hello, world!</greeting>

In fact, there is an even simpler convenience method, DataElement(string, string), designed for writing elements that contain only character data, so the code to generate the document could be shortened to 

XMLWriter w = new XMLWriter();
    w.StartDocument();
    w.DataElement("greeting", "Hello, world!");
    w.EndDocument();

Whitespace

According to the XML Recommendation, all whitespace in an XML document is potentially significant to an application, so this class never adds newlines or indentation. If you insert three elements in a row, as in 

w.DataElement("item", "1");
    w.DataElement("item", "2");
    w.DataElement("item", "3");

you will end up with

<item>1</item><item>3</item><item>3</item>

You need to invoke one of the Characters methods explicitly to add newlines or indentation. Alternatively, you can use DataWriter, which is derived from this class -- it is optimized for writing purely data-oriented (or field-oriented) XML, and does automatic linebreaks and indentation (but does not support mixed content properly).

Namespace Support

The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes. By default, the XML writer will generate Namespace declarations in the form _NS1, _NS2, etc., wherever they are needed, as in the following example: 

w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <_NS1:foo xmlns:_NS1="http://www.foo.com/ns/"/>

In many cases, document authors will prefer to choose their own prefixes rather than using the (ugly) default names. The XML writer allows two methods for selecting prefixes:

  1. the qualified name
  2. the SetPrefix(string, string) method.

Whenever the XML writer finds a new Namespace URI, it checks to see if a qualified (prefixed) name is also available; if so it attempts to use the name's prefix (as long as the prefix is not already in use for another Namespace URI).

Before writing a document, the client can also pre-map a prefix to a Namespace URI with the setPrefix method: 

w.SetPrefix("http://www.foo.com/ns/", "foo");
    w.StartDocument();
    w.EmptyElement("http://www.foo.com/ns/", "foo");
    w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo:foo xmlns:foo="http://www.foo.com/ns/"/>

The default Namespace simply uses an empty string as the prefix:

w.SetPrefix("http://www.foo.com/ns/", "");
                                                                              w.StartDocument();
                                                                              w.EmptyElement("http://www.foo.com/ns/", "foo");
                                                                              w.EndDocument();

The resulting document will look like this:

<?xml version="1.0" standalone="yes"?>
                                                         <foo xmlns="http://www.foo.com/ns/"/>

By default, the XML writer will not declare a Namespace until it is actually used. Sometimes, this approach will create a large number of Namespace declarations, as in the following example: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title xmlns:dc="http://www.purl.org/dc/">A Dark Night</dc:title>
    <dc:creator xmlns:dc="http://www.purl.org/dc/">Jane Smith</dc:title>
    <dc:date xmlns:dc="http://www.purl.org/dc/">2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

The "rdf" prefix is declared only once, because the RDF Namespace is used by the root element and can be inherited by all of its descendants; the "dc" prefix, on the other hand, is declared three times, because no higher element uses the Namespace. To solve this problem, you can instruct the XML writer to predeclare Namespaces on the root element even if they are not used there: 

w.ForceNSDecl("http://www.purl.org/dc/");

Now, the "dc" prefix will be declared on the root element even though it's not needed there, and can be inherited by its descendants: 

<xml version="1.0" standalone="yes"?>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dc="http://www.purl.org/dc/">
    <rdf:Description about="http://www.foo.com/ids/books/12345">
    <dc:title>A Dark Night</dc:title>
    <dc:creator>Jane Smith</dc:title>
    <dc:date>2000-09-09</dc:title>
    </rdf:Description>
    </rdf:RDF>

This approach is also useful for declaring Namespace prefixes that be used by qualified names appearing in attribute values or character data.

Exceptions
Type Condition
SAXException

If there is an error writing the start tag, or if a handler further down the filter chain raises an exception.
See Also

StartEntity(string)

Report the beginning of some internal and external XML entities.

Declaration
public virtual void StartEntity(string name)
Parameters
Type Name Description
string name

The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
Remarks

The reporting of parameter entities (including the external DTD subset) is optional, and SAX2 drivers that report LexicalHandler events may not implement it; you can use the http://xml.org/sax/features/lexical-handler/parameter-entities feature to query or control the reporting of parameter entities.

General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]".

When a SAX2 driver is providing these events, all other events must be properly nested within start/end entity events. There is no additional requirement that events from IDeclHandler or IDTDHandler be properly ordered.

Note that skipped entities will be reported through the SkippedEntity(string) event, which is part of the ContentHandler interface.

Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances:
  • general entities within attribute values
  • parameter entities within declarations

These will be silently expanded, with no indication of where the original entity boundaries were.

Note also that the boundaries of character references (which are not really entities anyway) are not reported.

All start/endEntity events must be properly nested.
Exceptions
Type Condition
SAXException

The application may raise an exception.
See Also

Implements

See Also