System.Xml 2.0.0.0 4.0.0.0 System.Object

The method is the preferred mechanism for obtaining instances. The method uses the class to specify which features to implement in the object that is created.

If you're using the object with the method, you should use the property to obtain an object with the correct settings. This ensures that the created object has the correct output settings.

The class provides properties that control data conformance and output format.

For data conformance checks and auto-corrections, use these properties:

Property

Specifies

Value

Default

Whether to check that characters are in the legal XML character set, as defined by W3C.

true or false

true

Whether to check that output is a well-formed XML 1.0 document or fragment.

(document-level), (fragment-level), or (auto-detection)

(document-level conformance)

Whether to add closing tags to all unclosed elements when the method is called.

true or false

true

To specify output format, use these properties:

Property

Specifies

Value

Default

Text encoding to use.

value

Whether to indent elements

true or false

false (no indentation)

Character string to use when indenting (used when is set to true).

String

Two spaces

Character string to use for line breaks.

String

\r\n (carriage return, line feed)

How to handle newline characters.

value: (normalize), (replace), or (leave unchanged)

(replace with characters specified by )

Whether to write attributes on individual lines (has no effect when is false).

true or false

false

Whether to write an XML declaration.

true or false

false

Specifies a set of features to support on the object created by the method.

- Constructor
  2.0.0.0
  4.0.0.0

  The following table shows initial property values for an instance of .

  Property

  Initial Value

  false.

  true.

  false.

  .

  Encoding.UTF8.

  false.

  Two spaces.

  \r\n (carriage return, new line).

  .

  false.

  false.

  true.

  Initializes a new instance of the class.

- Property
  4.0.0.0
  System.Boolean To be added.

  You must set this value to true when you create a new instance if you want to use asynchronous methods on that instance. After the instance is created, the property is read-only. The default value of this property is false.

  This flag is ignored by the overload. This means that if you create a new based on an existing , the async behavior depends on the input , and you cannot use the flag to change the async behavior.

  Gets or sets a value that indicates whether asynchronous methods can be used on a particular instance.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  If the object supports character checking, it throws an exception if any characters are outside the range of legal XML characters specified by the "2.2 Characters" section of the W3C XML 1.0 Recommendation.

  Character checking does not include checking for illegal characters in XML names or checking that all XML names are valid. These checks are part of conformance checking and are always performed.

  Gets or sets a value that indicates whether the XML writer should check to ensure that all characters in the document conform to the "2.2 Characters" section of the W3C XML 1.0 Recommendation.

- Method
  2.0.0.0
  4.0.0.0
  System.Xml.XmlWriterSettings

  The cloned object can be modified without affecting the settings on the original object.

  Creates a copy of the instance.

  The cloned object.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  This setting is useful when you wish to write XML to a stream, and then add extra information to the end of the stream after the has finished writing.

  This property only applies to instances that output XML content to a stream or ; otherwise, this setting is ignored.

  Gets or sets a value indicating whether the should also close the underlying stream or when the method is called.

- Property
  2.0.0.0
  4.0.0.0
  System.Xml.ConformanceLevel To be added.

  The property configures the XML writer to check and guarantee that the stream being written complies with a certain set of rules. The XML data can be checked to see that it conforms to the rules for a well-formed XML 1.0 document or a document fragment. The following table describes the three settings. The default is document-level conformance.

  Setting

  Description

  Ensures that the XML output conforms to the rules for a well-formed XML 1.0 document and can be processed by any conforming processor.

  The document conformance checks include most of the fragment-level checks and also ensure the following:

  The top-level item doesn't have any nodes other than XML Declaration, DTD, element, comment, white space, or processing instruction.

  The XML data has one and only one top-level element node.

  The XML writer doesn't parse DTD information that is written. The user is responsible for ensuring that the DTD is well-formed.

  Ensures that the XML output conforms to the rules for a well-formed XML 1.0 document fragment.

  This setting accepts XML data that has multiple root elements or text nodes at the top level. This level of checking ensures that any processor can consume the stream being read as an XML 1.0 external parsed entity.

  DTD information isn't allowed in document fragments.

  Specifies that the XML writer should determine the level of conformance checking based on the incoming data. This setting can be useful when you don't know whether the generated XML will be a well-formed XML document or a fragment.

  Document conformance checking is applied in the following cases:

  If the method is called.

  If DTD information is written.

  Fragment conformance checking is applied if the XML data contains one of these:

  Text, CDATA, or EntityReference node at the root level.

  More than one element at the root level.

  No element at the root level.

  An is thrown if there is a conflict, such as when you try to write a text node and a DTD at the root level.

  If you are wrapping another object, the outer object doesn't do any additional conformance checking; this is left to the underlying object.

  If the XML writer detects any information that would violate the specified level of conformance, it throws an exception. In some cases, the XML writer automatically corrects the conformance error. For example, the writer closes an unclosed attribute without throwing an exception. The following table shows how various conformance violations are handled in each setting.

  Condition

  DTD information is found.

  Not a violation for this setting. However, the XML writer doesn't check the DTD; the user must ensure that the DTD is well-formed.

  is thrown.

  Document conformance checking is applied.

  is called.

  Not considered a violation for this setting.

  is thrown.

  Document conformance checking is applied.

  is called multiple times.

  is thrown.

  is thrown.

  is thrown.

  A text value appears at the top level (not below an element or attribute node).

  is thrown.

  Not considered a violation.

  Fragment conformance checking is applied.

  Multiple elements or no elements appear at the top level.

  is thrown.

  Not considered a violation.

  Fragment conformance checking is applied.

  Top-level item is white space.

  Not considered a violation.

  Not considered a violation.

  Not considered a violation.

  isn't called to end an attribute node.

  Fixed by XML writer.

  Fixed by XML writer.

  Fixed by XML writer.

  The XML writer is in an improperly nested state (for example, a call is followed by a ).

  is thrown.

  is thrown.

  is thrown.

  Top-level item is an attribute.

  is thrown.

  is thrown.

  is thrown.

  Multiple, contiguous text nodes are found.

  Not considered a violation, but it's the responsibility of the user to concatenate the text nodes.

  Not considered a violation, but it's the responsibility of the user to concatenate the text nodes.

  Not considered a violation, but it's the responsibility of the user to concatenate the text nodes.

  The same namespace prefix is declared twice in an element.

  The XML writer generates a new prefix for the second namespace.

  The XML writer generates a new prefix for the second namespace.

  The XML writer generates a new prefix for the second namespace.

  specifies a prefix and a namespace that isn't declared within that scope, or the prefix is associated with a different namespace.

  The XML writer writes the necessary namespace node.

  The XML writer writes the necessary namespace node.

  The XML writer writes the necessary namespace node.

  specifies a prefix and a namespace that isn't declared within that scope.

  The XML writer writes the necessary namespace node.

  The XML writer writes the necessary namespace node.

  The XML writer writes the necessary namespace node.

  specifies a prefix and a namespace, but the prefix is associated with a different in-scope namespace.

  The XML writer ignores the specified prefix and either looks up the correct prefix or generates a new prefix.

  The XML writer ignores the specified prefix and either looks up the correct prefix or generates a new prefix.

  The XML writer ignores the specified prefix and either looks up the correct prefix or generates a new prefix.

  is used to write element content by using a namespace that doesn't exist within the scope.

  is thrown.

  is thrown.

  is thrown.

  is used to write attribute content by using a namespace that doesn't exist within the scope.

  The XML writer writes the necessary namespace declaration.

  The XML writer writes the necessary namespace declaration.

  The XML writer writes the necessary namespace declaration.

  The xml:space attribute doesn't contain a valid value.

  is thrown.

  is thrown.

  is thrown.

  An invalid name is encountered.

  is thrown.

  is thrown.

  is thrown.

  The xml prefix isn't matched to a URI.

  The XML writer doesn't check for this type of violation.

  The XML writer doesn't check for this type of violation.

  The XML writer doesn't check for this type of violation.

  The xml prefix isn't matched to the http://www.w3.org/XML/1998/namespace URI.

  is thrown.

  is thrown.

  is thrown.

  The xmlns prefix or local name isn't matched to a URI.

  The XML writer doesn't check for this type of violation.

  The XML writer doesn't check for this type of violation.

  The XML writer doesn't check for this type of violation.

  The xmlns prefix or local name isn't matched to the http://www.w3.org/2000/xmlns URI.

  is thrown.

  is thrown.

  is thrown.

  Gets or sets the level of conformance that the XML writer checks the XML output for.

- Property
  2.0.0.0
  4.0.0.0
  System.Text.Encoding To be added.

  The encodes a buffer of characters all at once, rather than character by character. An exception is thrown when the method is called if any encoding errors are encountered.

  The property only applies to the instances that are created either with the specified or with the specified file name. If the instance is created with the specified , the property is overridden by the encoding of the underlying . For example, if this property is set to Unicode (UTF-16) for a particular , but the underlying writer is a (which derives from ) with its encoding set to UTF8, the output will be UTF-8 encoded.

  If the instance is created with other output parameters, the property is ignored.

  In the following example:

  The default value of is Encoding.UTF8.

  The is set to Encoding.Unicode and the ’s encoding overrides the setting.

  The output will be Encoding.Unicode.

  `using (StreamWriter output = new StreamWriter(new FileStream("Xml01.xml", FileMode.Create), Encoding.Unicode)) { using (XmlWriter xmlWriter = XmlWriter.Create(output, new XmlWriterSettings())) { xmlWriter.WriteStartDocument(); xmlWriter.WriteStartElement("Root"); xmlWriter.WriteEndElement(); xmlWriter.WriteEndDocument(); } }`

  Do not accept an object from an untrusted source.

  Gets or sets the type of text encoding to use.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  This property only applies to instances that output text content; otherwise, this setting is ignored.

  The elements are indented as long as the element does not contain mixed content. Once the or method is called to write out a mixed element content, the stops indenting. The indenting resumes once the mixed content element is closed.

  Gets or sets a value indicating whether to indent elements.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  This property only applies to instances that output text content; otherwise, this setting is ignored. The throws an exception if the indent characters would result in invalid XML.

  Gets or sets the character string to use when indenting. This setting is used when the property is set to true.

- Property
  4.0.0.0
  System.Xml.NamespaceHandling To be added. To be added.

  Gets or sets a value that indicates whether the should remove duplicate namespace declarations when writing XML content. The default behavior is for the writer to output all namespace declarations that are present in the writer's namespace resolver.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  This property only applies to instances that output text content; otherwise, this setting is ignored. The throws an exception if the line break characters would result in invalid XML.

  Gets or sets the character string to use for line breaks.

- Property
  2.0.0.0
  4.0.0.0
  System.Xml.NewLineHandling To be added.

  This setting applies when writing text content or attribute values. Each of the values is described below:

  The setting tells the to replace new line characters that would not be otherwise preserved by a normalizing with character entities. This is useful in round-trip scenarios where the output is read by a normalizing . Additional normalization rules apply for attribute values when round tripping since \t, \n and \r are replaced with a space in attribute values when normalized in an .

  The setting tells the to replace new line characters with \r\n, which is the new line format used by the Microsoft Windows operating system. This helps to ensure that the file can be correctly displayed by the Notepad or Microsoft Word applications. This setting also replaces new lines in attributes with character entities to preserve the characters. This is the default value.

  The setting tells the to leave the input unchanged. This setting is used when you not want any new-line processing. This is useful when the output is read by an that does not do any normalization (for example, an with default settings.)

  The following tables show the output of the method when supplied with the input value depending on the property setting. The tables show the output when writing text content and also when writing an attribute value.

  Text Node Value:

  \r\n

  \n

  \r

  \t

  Entitize

  &#D;\n

  \n

  &#D;

  \t

  Replace

  \r\n

  \r\n

  \r\n

  \t

  None

  \r\n

  \n

  \r

  \t

  Attribute Value:

  \r\n

  \n

  \r

  \t

  Entitize

  &#D;&#A;

  &#A;

  &#D;

  &#9;

  Replace

  &#D;&#A;

  &#A;

  &#D;

  &#9;

  None

  \r\n

  \n

  \r

  \t

  The has the following behavior when writing content within a CDATA section, comment, or processing instruction. New lines are never replaced with their character entities, even when the property is set to . This is because character entities are not recognized in CDATA sections, comments or processing instructions. If the property is set to or , the behavior is the same as when writing a text node value.

  The following table describes what a normalizing returns for each white space input. For more information, see sections 2.11 and 3.3.3 of the W3C XML 1.0 Recommendation.

  A normalizing reader is any object created by the method. These objects always perform line break normalization and full normalization of attributes. The object can also be a normalizing reader if it's property is set to true.

  \r\n

  \n

  \r

  \t

  Text Node Value

  \n

  \n

  \n

  \t

  Attribute Value

  single space

  single space

  single space

  single space

  Gets or sets a value indicating whether to normalize line breaks in the output.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  This property only applies to instances that output text content; otherwise, this setting is ignored.

  Gets or sets a value indicating whether to write attributes on a new line.

- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  This property only applies to instances that output text content; otherwise, this setting is ignored.

  If is set to false, The XML declaration is written automatically

  The XML declaration is always written if is set to , even if is set to true.

  The XML declaration is never written if is set to . You can call to explicitly write out an XML declaration.

  Gets or sets a value indicating whether to omit an XML declaration.

- Property
  2.0.0.0
  4.0.0.0
  System.Xml.XmlOutputMethod To be added.

  This property specifies the method used to serialize the output. The output can be serialized using the HTML rules, the XML 1.0 rules, and so on. This setting is set by the XSLT processor and is used internally by Visual Studio.

  Gets the method used to serialize the output.

- Method
  2.0.0.0
  4.0.0.0
  System.Void

  The following table shows the default property values for an instance of .

  Property

  Initial value

  false.

  true.

  false.

  .

  Encoding.UTF8.

  false.

  Two spaces.

  \r\n.

  .

  false.

  false.

  true.

  Resets the members of the settings class to their default values.

- Property
  4.0.0.0
  System.Boolean To be added.

  If you set this flag to false, the output XML file may not be well-formed.

  Gets or sets a value that indicates whether the will add closing tags to all unclosed element tags when the method is called.