Valid content of XElement and XDocument objects (LINQ to XML)
This article describes the valid arguments that can be passed to constructors, and methods that you use to add content to elements and documents.
Valid types for the XElement constructor
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. That's why it's 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, including::
- String
- Double
- Single
- Decimal
- Boolean
- DateTime
- TimeSpan
- DateTimeOffset
- Any type that implements
Object.ToString. - Any type that implements IEnumerable<T>.
When adding complex content, various types can be passed to this method, including:
- 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 types for the XDocument constructor
Attributes and simple content can't be added to a document.
There aren't 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's often more convenient to use XElement as your root node.
Valid types for the XDocument constructor include 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 for 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. |
