Edit

Share via


XmlWriterSettings.ConformanceLevel Property

Definition

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

public:
 property System::Xml::ConformanceLevel ConformanceLevel { System::Xml::ConformanceLevel get(); void set(System::Xml::ConformanceLevel value); };
public System.Xml.ConformanceLevel ConformanceLevel { get; set; }
member this.ConformanceLevel : System.Xml.ConformanceLevel with get, set
Public Property ConformanceLevel As ConformanceLevel

Property Value

One of the enumeration values that specifies the level of conformance (document, fragment, or automatic detection). The default is Document.

Examples

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

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.
Dim settings As XmlWriterSettings = New XmlWriterSettings()
settings.OmitXmlDeclaration = true
settings.ConformanceLevel = ConformanceLevel.Fragment
settings.CloseOutput = false

' Create the XmlWriter object and write some content.
Dim strm as MemoryStream = new MemoryStream()
Dim writer As XmlWriter = 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

The XmlWriterSettings.ConformanceLevel 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
Document 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.
Fragment 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.
Auto 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 WriteStartDocument 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 XmlException 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 XmlWriter 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 Document Fragment Auto
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. XmlException is thrown. Document conformance checking is applied.
WriteStartDocument is called. Not considered a violation for this setting. XmlException is thrown. Document conformance checking is applied.
WriteStartDocument is called multiple times. XmlException is thrown. XmlException is thrown. XmlException is thrown.
A text value appears at the top level (not below an element or attribute node). XmlException is thrown. Not considered a violation. Fragment conformance checking is applied.
Multiple elements or no elements appear at the top level. XmlException 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.
WriteEndAttribute 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 WriteStartElement call is followed by a WriteEndAttribute). XmlException is thrown. XmlException is thrown. XmlException is thrown.
Top-level item is an attribute. XmlException is thrown. XmlException is thrown. XmlException 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.
WriteStartElement 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.
WriteStartAttribute 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.
WriteStartAttribute 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.
WriteQualifiedName is used to write element content by using a namespace that doesn't exist within the scope. XmlException is thrown. XmlException is thrown. XmlException is thrown.
WriteQualifiedName 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. XmlException is thrown. XmlException is thrown. XmlException is thrown.
An invalid name is encountered. XmlException is thrown. XmlException is thrown. XmlException 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. XmlException is thrown. XmlException is thrown. XmlException 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. XmlException is thrown. XmlException is thrown. XmlException is thrown.

Applies to