• Article

XContainer.Element Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Gets the first (in document order) child element with the specified XName.

Namespace:  System.Xml.Linq
Assembly:  System.Xml.Linq (in System.Xml.Linq.dll)

Syntax

'Declaration
Public Function Element ( _
    name As XName _
) As XElement

public XElement Element(
    XName name
)

Parameters

Return Value

Type: System.Xml.Linq.XElement
A XElement that matches the specified XName, or nulla null reference (Nothing in Visual Basic).

Remarks

Returns nulla null reference (Nothing in Visual Basic) if there is no element with the specified name.

Some axis methods return collections of elements or attributes. This method returns only a single element.

This method returns nulla null reference (Nothing in Visual Basic) if the element with the specified name is not found. All of the methods that allow you to construct elements (the constructor of XElement, Add, and so on) accept nulla null reference (Nothing in Visual Basic) as a valid argument. This allows you to use a convenient idiom: you can call this method as part of functional construction, and the element is added to the XML tree being constructed if and only if the element exists in the source tree. The following example shows this idiom.

In contrast to Elements, this method is not an axis method. It does not use deferred execution; it simply returns an element when called.

Examples

The following example shows two uses of this method. In one case, the method finds the element in srcTree. In the second case, the method does not find the element in the source tree, no element is added to xmlTree, and no exception is thrown.

Note that the Visual Basic example uses the child XML property. It is also allowable to use the Element method directly in Visual Basic.

Dim output As New StringBuilder
Dim srcTree As XElement = _
        <Root>
            <Element1>1</Element1>
            <Element2>2</Element2>
            <Element3>3</Element3>
            <Element4>4</Element4>
            <Element5>5</Element5>
        </Root>

Dim xmlTree As XElement = _
        <Root>
            <Child1>1</Child1>
            <Child2>2</Child2>
            <Child3>3</Child3>
            <Child4>4</Child4>
            <Child5>5</Child5>
            <%= srcTree.<Element3> %>
            <%= srcTree.<Element9> %>
        </Root>

' Even though Element9 does not exist in srcTree, adding it to the tree
' will not throw an exception.

output.Append(xmlTree)
output.Append(Environment.NewLine)

OutputTextBlock.Text = output.ToString()

StringBuilder output = new StringBuilder();
XElement srcTree = new XElement("Root",
    new XElement("Element1", 1),
    new XElement("Element2", 2),
    new XElement("Element3", 3),
    new XElement("Element4", 4),
    new XElement("Element5", 5)
);
XElement xmlTree = new XElement("Root",
    new XElement("Child1", 1),
    new XElement("Child2", 2),
    new XElement("Child3", 3),
    new XElement("Child4", 4),
    new XElement("Child5", 5),
    srcTree.Element("Element3"),
    // Even though Element9 does not exist in srcTree, the following line
    // will not throw an exception.
    srcTree.Element("Element9")
);
output.Append(xmlTree  + Environment.NewLine);

OutputTextBlock.Text = output.ToString();

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.