Export (0) Print
Expand All

XContainer.Element Method

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)

'Declaration
Public Function Element ( _
	name As XName _
) As XElement
'Usage
Dim instance As XContainer 
Dim name As XName 
Dim returnValue As XElement 

returnValue = instance.Element(name)

Parameters

name
Type: System.Xml.Linq.XName

The XName to match.

Return Value

Type: System.Xml.Linq.XElement
A XElement that matches the specified XName, or Nothing.

Returns Nothing 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 Nothing 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 Nothing 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.

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 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.

Console.WriteLine(xmlTree)

This example produces the following output:

<Root>
  <Child1>1</Child1>
  <Child2>2</Child2>
  <Child3>3</Child3>
  <Child4>4</Child4>
  <Child5>5</Child5>
  <Element3>3</Element3>
</Root>

The following is the same example, but in this case the XML is in a namespace. For more information, see Working with XML Namespaces.

Imports <xmlns:aw="http://www.adventure-works.com">

Module Module1
    Sub Main()
        Dim srcTree As XElement = _ 
            <aw:Root>
                <aw:Element1>1</aw:Element1>
                <aw:Element2>2</aw:Element2>
                <aw:Element3>3</aw:Element3>
                <aw:Element4>4</aw:Element4>
                <aw:Element5>5</aw:Element5>
            </aw:Root>

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

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

        Console.WriteLine(xmlTree)
    End Sub
End Module

This example produces the following output:

<aw:Root xmlns:aw="http://www.adventure-works.com">
  <aw:Child1>1</aw:Child1>
  <aw:Child2>2</aw:Child2>
  <aw:Child3>3</aw:Child3>
  <aw:Child4>4</aw:Child4>
  <aw:Child5>5</aw:Child5>
  <aw:Element3>3</aw:Element3>
</aw:Root>

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5

.NET Compact Framework

Supported in: 3.5

XNA Framework

Supported in: 3.0

Community Additions

ADD
Show:
© 2015 Microsoft