Valid Content of XElement and XDocument Objects
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

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.

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:

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

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.

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.

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




Constructs an XElement.


Constructs a XDocument.


Adds to the end of the child content of the XElement or XDocument.


Adds content after the XNode.


Adds content before the XNode.


Adds content at the beginning of the child content of the XContainer.


Replaces all content (child nodes and attributes) of an XElement.


Replaces the attributes of an XElement.


Replaces the children nodes with new content.


Replaces a node with new content.

© 2015 Microsoft