XmlWriter.Create Method

Definition

Creates a new XmlWriter instance.

Overloads

Create(StringBuilder, XmlWriterSettings)

Creates a new XmlWriter instance using the StringBuilder and XmlWriterSettings objects.

Create(String, XmlWriterSettings)

Creates a new XmlWriter instance using the filename and XmlWriterSettings object.

Create(TextWriter, XmlWriterSettings)

Creates a new XmlWriter instance using the TextWriter and XmlWriterSettings objects.

Create(Stream, XmlWriterSettings)

Creates a new XmlWriter instance using the stream and XmlWriterSettings object.

Create(XmlWriter, XmlWriterSettings)

Creates a new XmlWriter instance using the specified XmlWriter and XmlWriterSettings objects.

Create(StringBuilder)

Creates a new XmlWriter instance using the specified StringBuilder.

Create(String)

Creates a new XmlWriter instance using the specified filename.

Create(TextWriter)

Creates a new XmlWriter instance using the specified TextWriter.

Create(Stream)

Creates a new XmlWriter instance using the specified stream.

Create(XmlWriter)

Creates a new XmlWriter instance using the specified XmlWriter object.

Remarks

Some of the Create overloads include a settings parameter that accepts an XmlWriterSettings object. You can use this object to:

  • Specify which features you want supported on the created XmlWriter object.

  • Reuse the XmlWriterSettings object to create multiple writer objects. The XmlWriterSettings object is copied and marked read-only for each created writer. Changes to the settings on an XmlWriterSettings instance do not affect existing writers with the same settings. Thus, you can use the same settings to create multiple writers with the same functionality. Or, you can modify the settings on an XmlWriterSettings instance and create a new writer with a different set of features.

  • Add features to an existing XML writer. The Create method can accept another XmlWriter object. The underlying XmlWriter object does not have to be an XML writer created by the static Create method. For example, you can specify a user-defined XML writer to add additional features to.

  • Take full advantage of features such as better conformance checking and compliance to the XML 1.0 recommendation that are available only on XmlWriter objects created by the static Create method.

If you use a Create overload that doesn't accept an XmlWriterSettings object, the following default writer settings are used:

Setting Default
CheckCharacters true
CloseOutput false
ConformanceLevel ConformanceLevel.Document
Encoding Encoding.UTF8
Indent false
IndentChars Two spaces
NamespaceHandling Default (no removal)
NewLineChars \r\n (carriage return, line feed) for non-Unix platforms, or \n (line feed) for Unix platforms
NewLineHandling NewLineHandling.Replace
NewLineOnAttributes false
OmitXmlDeclaration false
OutputMethod XmlOutputMethod.Xml
WriteEndDocumentOnClose true

Note

Although the .NET Framework includes the XmlTextWriter class, which is a concrete implementation of the XmlWriter class, we recommend that you create XmlWriter instances by using the Create method.

Create(StringBuilder, XmlWriterSettings)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the StringBuilder and XmlWriterSettings objects.

C#
public static System.Xml.XmlWriter Create(System.Text.StringBuilder output, System.Xml.XmlWriterSettings settings);
C#
public static System.Xml.XmlWriter Create(System.Text.StringBuilder output, System.Xml.XmlWriterSettings? settings);

Parameters

output
StringBuilder

The StringBuilder to which to write to. Content written by the XmlWriter is appended to the StringBuilder.

settings
XmlWriterSettings

The XmlWriterSettings object used to configure the new XmlWriter instance. If this is null, a XmlWriterSettings with default settings is used.

If the XmlWriter is being used with the Transform(String, XmlWriter) method, you should use the OutputSettings property to obtain an XmlWriterSettings object with the correct settings. This ensures that the created XmlWriter object has the correct output settings.

Returns

An XmlWriter object.

Exceptions

The builder value is null.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(String, XmlWriterSettings)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the filename and XmlWriterSettings object.

C#
public static System.Xml.XmlWriter Create(string outputFileName, System.Xml.XmlWriterSettings? settings);
C#
public static System.Xml.XmlWriter Create(string outputFileName, System.Xml.XmlWriterSettings settings);

Parameters

outputFileName
String

The file to which you want to write. The XmlWriter creates a file at the specified path and writes to it in XML 1.0 text syntax. The outputFileName must be a file system path.

settings
XmlWriterSettings

The XmlWriterSettings object used to configure the new XmlWriter instance. If this is null, a XmlWriterSettings with default settings is used.

If the XmlWriter is being used with the Transform(String, XmlWriter) method, you should use the OutputSettings property to obtain an XmlWriterSettings object with the correct settings. This ensures that the created XmlWriter object has the correct output settings.

Returns

An XmlWriter object.

Exceptions

The url value is null.

Examples

The following example creates an XmlWriter object with the defined settings.

C#
using System;
using System.IO;
using System.Xml;
using System.Text;

public class Sample {

  public static void Main() {

    XmlWriter writer = null;

    try {

       // Create an XmlWriterSettings object with the correct options.
       XmlWriterSettings settings = new XmlWriterSettings();
       settings.Indent = true;
       settings.IndentChars = ("\t");
       settings.OmitXmlDeclaration = true;

       // Create the XmlWriter object and write some content.
       writer = XmlWriter.Create("data.xml", settings);
       writer.WriteStartElement("book");
       writer.WriteElementString("item", "tesing");
       writer.WriteEndElement();
    
       writer.Flush();
     }
     finally  {
        if (writer != null)
          writer.Close();
     }
  }
}

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 2.0, 2.1

Create(TextWriter, XmlWriterSettings)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the TextWriter and XmlWriterSettings objects.

C#
public static System.Xml.XmlWriter Create(System.IO.TextWriter output, System.Xml.XmlWriterSettings settings);
C#
public static System.Xml.XmlWriter Create(System.IO.TextWriter output, System.Xml.XmlWriterSettings? settings);

Parameters

output
TextWriter

The TextWriter to which you want to write. The XmlWriter writes XML 1.0 text syntax and appends it to the specified TextWriter.

settings
XmlWriterSettings

The XmlWriterSettings object used to configure the new XmlWriter instance. If this is null, a XmlWriterSettings with default settings is used.

If the XmlWriter is being used with the Transform(String, XmlWriter) method, you should use the OutputSettings property to obtain an XmlWriterSettings object with the correct settings. This ensures that the created XmlWriter object has the correct output settings.

Returns

An XmlWriter object.

Exceptions

The text value is null.

Examples

The following example writes out an XML string.

C#
XmlWriterSettings settings = new XmlWriterSettings();
settings.OmitXmlDeclaration = true;
StringWriter sw = new StringWriter();

using (XmlWriter writer = XmlWriter.Create(sw, settings))
{
    writer.WriteStartElement("book");
    writer.WriteElementString("price", "19.95");
    writer.WriteEndElement();
    writer.Flush();

    String output = sw.ToString();
}

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(Stream, XmlWriterSettings)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the stream and XmlWriterSettings object.

C#
public static System.Xml.XmlWriter Create(System.IO.Stream output, System.Xml.XmlWriterSettings settings);
C#
public static System.Xml.XmlWriter Create(System.IO.Stream output, System.Xml.XmlWriterSettings? settings);

Parameters

output
Stream

The stream to which you want to write. The XmlWriter writes XML 1.0 text syntax and appends it to the specified stream.

settings
XmlWriterSettings

The XmlWriterSettings object used to configure the new XmlWriter instance. If this is null, a XmlWriterSettings with default settings is used.

If the XmlWriter is being used with the Transform(String, XmlWriter) method, you should use the OutputSettings property to obtain an XmlWriterSettings object with the correct settings. This ensures that the created XmlWriter object has the correct output settings.

Returns

An XmlWriter object.

Exceptions

The stream value is null.

Examples

The following example writes an XML fragment to a memory stream.

C#
XmlWriterSettings settings = new XmlWriterSettings();
settings.OmitXmlDeclaration = true;
settings.ConformanceLevel = ConformanceLevel.Fragment;
settings.CloseOutput = false;

// Create the XmlWriter object and write some content.
MemoryStream strm = new MemoryStream();
XmlWriter writer = XmlWriter.Create(strm, settings);
writer.WriteElementString("orderID", "1-456-ab");
writer.WriteElementString("orderID", "2-36-00a");
writer.Flush();
writer.Close();

// Do additional processing on the stream.

Remarks

XmlWriter always writes a Byte Order Mark (BOM) to the underlying data stream; however, some streams must not have a BOM. To omit the BOM, create a new XmlWriterSettings object and set the Encoding property to be a new UTF8Encoding object with the Boolean value in the constructor set to false.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(XmlWriter, XmlWriterSettings)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the specified XmlWriter and XmlWriterSettings objects.

C#
public static System.Xml.XmlWriter Create(System.Xml.XmlWriter output, System.Xml.XmlWriterSettings settings);
C#
public static System.Xml.XmlWriter Create(System.Xml.XmlWriter output, System.Xml.XmlWriterSettings? settings);

Parameters

output
XmlWriter

The XmlWriter object that you want to use as the underlying writer.

settings
XmlWriterSettings

The XmlWriterSettings object used to configure the new XmlWriter instance. If this is null, a XmlWriterSettings with default settings is used.

If the XmlWriter is being used with the Transform(String, XmlWriter) method, you should use the OutputSettings property to obtain an XmlWriterSettings object with the correct settings. This ensures that the created XmlWriter object has the correct output settings.

Returns

An XmlWriter object that is wrapped around the specified XmlWriter object.

Exceptions

The writer value is null.

Remarks

This method allows you add additional features to an underlying XmlWriter object. The underlying XmlWriter object can be an object created by the XmlWriter.Create method, or an object created using the XmlTextWriter implementation.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(StringBuilder)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the specified StringBuilder.

C#
public static System.Xml.XmlWriter Create(System.Text.StringBuilder output);

Parameters

output
StringBuilder

The StringBuilder to which to write to. Content written by the XmlWriter is appended to the StringBuilder.

Returns

An XmlWriter object.

Exceptions

The builder value is null.

Remarks

When you use this overload, an XmlWriterSettings object with default settings is used to create the XML writer.

Setting Default
CheckCharacters true
CloseOutput false
ConformanceLevel ConformanceLevel.Document
Encoding Encoding.UTF8
Indent false
IndentChars Two spaces
NamespaceHandling Default (no removal)
NewLineChars \r\n (carriage return, line feed) for non-Unix platforms, or \n (line feed) for Unix platforms
NewLineHandling NewLineHandling.Replace
NewLineOnAttributes false
OmitXmlDeclaration false
OutputMethod XmlOutputMethod.Xml
WriteEndDocumentOnClose true

If you want to specify the features to support on the created XML writer, use an overload that takes an XmlWriterSettings object as one of its arguments, and pass in a XmlWriterSettings object with your custom settings.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(String)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the specified filename.

C#
public static System.Xml.XmlWriter Create(string outputFileName);

Parameters

outputFileName
String

The file to which you want to write. The XmlWriter creates a file at the specified path and writes to it in XML 1.0 text syntax. The outputFileName must be a file system path.

Returns

An XmlWriter object.

Exceptions

The url value is null.

Examples

The following example creates an XmlWriter object and writes a book node.

C#
using (XmlWriter writer = XmlWriter.Create("output.xml"))
{
    writer.WriteStartElement("book");
    writer.WriteElementString("price", "19.95");
    writer.WriteEndElement();
    writer.Flush();
}

Remarks

When you use this overload, an XmlWriterSettings object with default settings is used to create the XML writer.

Setting Default
CheckCharacters true
CloseOutput false
ConformanceLevel ConformanceLevel.Document
Encoding Encoding.UTF8
Indent false
IndentChars Two spaces
NamespaceHandling Default (no removal)
NewLineChars \r\n (carriage return, line feed) for non-Unix platforms, or \n (line feed) for Unix platforms
NewLineHandling NewLineHandling.Replace
NewLineOnAttributes false
OmitXmlDeclaration false
OutputMethod XmlOutputMethod.Xml
WriteEndDocumentOnClose true

If you want to specify the features to support on the created XML writer, use an overload that takes an XmlWriterSettings object as one of its arguments, and pass in a XmlWriterSettings object with your custom settings.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 2.0, 2.1

Create(TextWriter)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the specified TextWriter.

C#
public static System.Xml.XmlWriter Create(System.IO.TextWriter output);

Parameters

output
TextWriter

The TextWriter to which you want to write. The XmlWriter writes XML 1.0 text syntax and appends it to the specified TextWriter.

Returns

An XmlWriter object.

Exceptions

The text value is null.

Examples

The following example creates a writer that outputs to the console.

C#
using (XmlWriter writer = XmlWriter.Create(Console.Out))
{
    writer.WriteStartElement("book");
    writer.WriteElementString("price", "19.95");
    writer.WriteEndElement();
    writer.Flush();
}

Remarks

When you use this overload, an XmlWriterSettings object with default settings is used to create the XML writer.

Setting Default
CheckCharacters true
CloseOutput false
ConformanceLevel ConformanceLevel.Document
Encoding Encoding.UTF8
Indent false
IndentChars Two spaces
NamespaceHandling Default (no removal)
NewLineChars \r\n (carriage return, line feed) for non-Unix platforms, or \n (line feed) for Unix platforms
NewLineHandling NewLineHandling.Replace
NewLineOnAttributes false
OmitXmlDeclaration false
OutputMethod XmlOutputMethod.Xml
WriteEndDocumentOnClose true

If you want to specify the features to support on the created writer, use an overload that takes an XmlWriterSettings object as one of its arguments, and pass in an XmlWriterSettings object with your custom settings.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(Stream)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the specified stream.

C#
public static System.Xml.XmlWriter Create(System.IO.Stream output);

Parameters

output
Stream

The stream to which you want to write. The XmlWriter writes XML 1.0 text syntax and appends it to the specified stream.

Returns

An XmlWriter object.

Exceptions

The stream value is null.

Examples

The following example writes an XML fragment to a memory stream. (It uses the Create(Stream, XmlWriterSettings) overload, which also configures the settings on the new XML writer instance.)

C#
XmlWriterSettings settings = new XmlWriterSettings();
settings.OmitXmlDeclaration = true;
settings.ConformanceLevel = ConformanceLevel.Fragment;
settings.CloseOutput = false;

// Create the XmlWriter object and write some content.
MemoryStream strm = new MemoryStream();
XmlWriter writer = XmlWriter.Create(strm, settings);
writer.WriteElementString("orderID", "1-456-ab");
writer.WriteElementString("orderID", "2-36-00a");
writer.Flush();
writer.Close();

// Do additional processing on the stream.

Remarks

When you use this overload, an XmlWriterSettings object with the following default settings is used to create the XML writer:

Setting Default
CheckCharacters true
CloseOutput false
ConformanceLevel ConformanceLevel.Document
Encoding Encoding.UTF8
Indent false
IndentChars Two spaces
NamespaceHandling Default (no removal)
NewLineChars \r\n (carriage return, line feed) for non-Unix platforms, or \n (line feed) for Unix platforms
NewLineHandling NewLineHandling.Replace
NewLineOnAttributes false
OmitXmlDeclaration false
OutputMethod XmlOutputMethod.Xml
WriteEndDocumentOnClose true

If you want to specify the features to support on the created writer, use an overload that takes an XmlWriterSettings object as one of its arguments, and pass in an XmlWriterSettings object with your custom settings.

Also, XmlWriter always writes a Byte Order Mark (BOM) to the underlying data stream; however, some streams must not have a BOM. To omit the BOM, create a new XmlWriterSettings object and set the Encoding property to be a new UTF8Encoding object with the Boolean value in the constructor set to false.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

Create(XmlWriter)

Source:
XmlWriter.cs
Source:
XmlWriter.cs
Source:
XmlWriter.cs

Creates a new XmlWriter instance using the specified XmlWriter object.

C#
public static System.Xml.XmlWriter Create(System.Xml.XmlWriter output);

Parameters

output
XmlWriter

The XmlWriter object that you want to use as the underlying writer.

Returns

An XmlWriter object that is wrapped around the specified XmlWriter object.

Exceptions

The writer value is null.

Remarks

This method allows you add features to an underlying XmlWriter object. The underlying XmlWriter object can be an object created by the XmlWriter.Create method, or an object created using the XmlTextWriter implementation.

When you use this overload, an XmlWriterSettings object with default settings is used to create the XML writer.

Setting Default
CheckCharacters true
CloseOutput false
ConformanceLevel ConformanceLevel.Document
Encoding Encoding.UTF8
Indent false
IndentChars Two spaces
NamespaceHandling Default (no removal)
NewLineChars \r\n (carriage return, line feed) for non-Unix platforms, or \n (line feed) for Unix platforms
NewLineHandling NewLineHandling.Replace
NewLineOnAttributes false
OmitXmlDeclaration false
OutputMethod XmlOutputMethod.Xml
WriteEndDocumentOnClose true

If you want to specify the features to support on the created XML writer, use an overload that takes an XmlWriterSettings object as one of its arguments, and pass in a XmlWriterSettings object with your custom settings.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0