Valid Content of XElement and XDocument Objects

This topic describes the valid arguments that can be passed to constructors and methods that you use to add content to elements and documents.

Valid Content

Queries often evaluate to IEnumerable<T> of XElement or IEnumerable<T> of XAttribute. You can pass collections of XElement or XAttribute objects to the XElement constructor. Therefore, it is convenient to pass the results of a query as content into methods and constructors that you use to populate XML trees.

When adding simple content, various types can be passed to this method. Valid types include the following:

• String

• Double

• Single

• Decimal

• Boolean

• DateTime

• TimeSpan

• DateTimeOffset

• Any type that implements ToString.

• Any type that implements IEnumerable<T>.

When adding complex content, various types can be passed to this method:

• XObject

• XNode

• XAttribute

• Any type that implements IEnumerable<T>

If an object implements IEnumerable<T>, the collection in the object is enumerated, and all items in the collection are added. If the collection contains XNode or XAttribute objects, each item in the collection is added separately. If the collection contains text (or objects that are converted to text), the text in the collection is concatenated and added as a single text node.

If content is null, nothing is added. When passing a collection items in the collection can be null. A null item in the collection has no effect on the tree.

An added attribute must have a unique name within its containing element.

When adding XNode or XAttribute objects, if the new content has no parent, then the objects are simply attached to the XML tree. If the new content already is parented and is part of another XML tree, then the new content is cloned, and the newly cloned content is attached to the XML tree.

Valid Content for Documents

Attributes and simple content cannot be added to a document.

There are not many scenarios that require you to create an XDocument. Instead, you can usually create your XML trees with an XElement root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use XElement as your root node.

Valid content for a document includes the following:

• Zero or one XDocumentType objects. The document types must come before the element.

• Zero or one element.

• Zero or more comments.

• Zero or more processing instructions.

• Zero or more text nodes that contain only white space.

Constructors and Functions that Allow Adding Content

The following methods allow you to add child content to an XElement or an XDocument:

Method	Description
XElement	Constructs an XElement.
XDocument	Constructs a XDocument.
Add	Adds to the end of the child content of the XElement or XDocument.
AddAfterSelf	Adds content after the XNode.
AddBeforeSelf	Adds content before the XNode.
AddFirst	Adds content at the beginning of the child content of the XContainer.
ReplaceAll	Replaces all content (child nodes and attributes) of an XElement.
ReplaceAttributes	Replaces the attributes of an XElement.
ReplaceNodes	Replaces the children nodes with new content.
ReplaceWith	Replaces a node with new content.

See Also

Concepts

Creating XML Trees