This topic has not yet been rated - Rate this topic

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:

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.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.