XLinq
.NET
Language Integrated Query
for
XML Data
September 2005May 2006
Notice
© 2005 2006 Microsoft Corporation. All rights reserved.
Microsoft, Windows, Visual Basic, Visual C#, and Visual C++
are either registered trademarks or trademarks of Microsoft Corporation in the
U.S.A. and/or other countries/regions.
Other product and company names mentioned herein may be the
trademarks of their respective owners.
The
example companies, organizations, products, domain names, e-mail addresses,
logos, people, places, and events depicted herein are fictitious. No association with any real company,
organization, product, domain name, email address, logo, person, places, or
events is intended or should be inferred.Table of
Contents
1.
Introduction........................................................................................................................... 1
1.1
Sample XML...................................................................................................................... 1
2.
Programming XML with XLinq.............................................................................................. 3
2.1
XLinq Design Principles....................................................................................................... 3
2.1.1
Key Concepts............................................................................................................... 3
2.1.1.1
Functional Construction........................................................................................... 3
2.1.1.2
Document "Free".................................................................................................... 4
2.1.1.3
XML Names.......................................................................................................... 6
2.1.1.4
Text as value.......................................................................................................... 6
2.2
The XLinq Class Hierarchy.................................................................................................. 7
2.3
XML Names....................................................................................................................... 8
2.3.1.1
XML Prefixes and Output........................................................................................ 9
2.4
Loading existing XML................................................................................................ 9 XML 10
2.5
Creating XML from Scratch.................................................................................. 10 Scratch 11
2.6
Traversing XML............................................................................................................... 12
2.6.1.1
Getting the Children of an XML Element.................................................. 12 Element....................................................................................................................................... 13
2.6.1.2
Getting the Parent and Document of an XML Element............................................. 14
2.7
Manipulating XML............................................................................................................ 14
2.7.1.1
Inserting
XML............................................................................................. 14 XML....................................................................................................................................... 15
2.7.2
Deleting XML............................................................................................................. 15
2.7.3
Updating XML.................................................................................................. 15 XML.......................................................................................................................................... 16
2.7.4 Careful of Be careful with deferred query execution.................................................... 16
2.8
Working with Attributes..................................................................................................... 17
2.8.1
Adding XML Attributes............................................................................................... 17
2.8.2
Getting XML
Attributes............................................................................. 17 Attributes.......................................................................................................................................... 18
2.8.3
Deleting XML
Attributes............................................................................ 17 Attributes.......................................................................................................................................... 18
2.9
Working with other types of XML Nodes............................................................................ 18
2.10 Annotating nodes with
user-defined information........................................................... 19
2.11 Outputting XML................................................................................................... 18 XML 20
2.12 Streaming XML............................................................................................................. 20
3. Querying
XML with XLinq........................................................................................ 19 XLinq 21
3.1
Querying XML........................................................................................................ 19 XML 21
3.1.1
Standard Query Operators and XML................................................................... 19 XML.......................................................................................................................................... 21
3.1.1.1
Creating multiple peer nodes in a select.......................................................... 20 select....................................................................................................................................... 22
3.1.1.2
Handling Null in a Transform............................................................... 20 Transform....................................................................................................................................... 22
3.1.2
XML Query
Extensions............................................................................ 21 Extensions.......................................................................................................................................... 23
3.1.2.1
Elements and
Content............................................................................. 21 Content....................................................................................................................................... 23
3.1.2.2
Descendants and Ancestors................................................................... 22 Ancestors....................................................................................................................................... 24
3.1.2.3 Attributes........................................................................................... 23 Attributes....................................................................................................................................... 25
3.1.2.4
ElementsBeforeThis, ElementsAfterThis, ContentBeforeThis, ContentAfterThis..... 23 NodesBeforeThis,
NodesAfterThis.................................................................................. 25
3.1.2.5
Technical Note: XML Query Extensions............................................... 24 Extensions....................................................................................................................................... 26
3.1.3
XML
Transformation....................................................................... 24 Transformation.......................................................................................................................................... 26
3.2
Using Query Expressions with XML.......................................................................... 26 XML 28
4. Mixing XML
and other data
models......................................................................... 27 models 29
4.1
Reading from a database to XML.............................................................................. 27 XML 29
4.2
Reading XML and Updating a Database.............................................................. 28 Database 30
5. Layered
Technologies Over
XLinq............................................................................. 29 XLinq 31
5.1
XLinq in Visual Basic 9.0............................................................................................. 29 9.0 31
5.1.1
XML Literals................................................................................................ 29 Literals.......................................................................................................................................... 31
5.1.2 Late Bound XML...................................................................... 30 Xml Axis Properties.......................................................................................................................................... 32
5.1.3
Putting it all
together..................................................................................... 31 together.......................................................................................................................................... 33
5.2
Schema aware XML Programming............................................................. 32 Programming 34
6. XLinq PDC Preview May 2006 CTP Release Notes.................................................... 34 Notes 37
6.1 Changes since the PDC 2005
Preview.................................................................................. 37
6.1.1 Axis names....................................................................................................................... 37
6.1.2 Annotations are supported on
container nodes................................................................ 37
6.1.3 XNamespace class added.................................................................................................. 37
6.1.4 Changes to XNode class................................................................................................... 37
6.1.5 XText class is now public.................................................................................................. 37
6.1.6 XElement Prefix resolution
methods................................................................................ 37
6.1.7 XAttribute........................................................................................................................ 38
6.1.8 New class XStreamingElement.......................................................................................... 38
6.1.9 XDocumentType.............................................................................................................. 38
6.1.10 XDocument.................................................................................................................... 38
6.1.11 XDeclaration no longer
inherits from XNode.................................................................. 38
6.2 Non-exhaustive list of planned
features in future releases.................................................. 38
7. References........................................................................................................... 37 References 39
1. Introduction
XML has achieved tremendous
adoption as a basis for formatting data whether in Word files, on the wire, in
configuration files, or in databases … XML seems to be everywhere. Yet, from a development perspective, XML is
still hard to work with. If you ask the
average software developer to work in XML you will likely hear a heavy
sigh. The API choices for working with
XML seem to be either aged and verbose such as DOM or XML specific such as
XQuery or XSLT which require motivation, study, and time to master. XLinq, a component of the LINQ project, aims
to address this issue. XLinq is a
modernized in-memory XML programming API designed to take advantage of the latest
.NET Framework language innovations. It
provides both DOM and XQuery/XPath like functionality in a consistent
programming experience across the different LINQ-enabled data access
technologies.
There are two major
perspectives for thinking about and understanding XLinq. From one perspective you can think of XLinq
as a member of the LINQ Project family of technologies with XLinq providing an
XML Language Integrated Query capability along with a consistent query
experience for objects, relational database (DLinq), and other data access
technologies as they become LINQ-enabled.
From a another perspective you can think of XLinq as a full feature
in-memory XML programming API comparable to a modernized, redesigned Document
Object Model (DOM) XML Programming API. API plus a few key features from XPath and XSLT.
XLinq was developed with
Language Integrated Query over XML in mind from the beginning. It takes advantage of the Standard Query
Operators and adds query extensions specific to XML. From an XML perspective XLinq provides the
query and transformation power of XQuery and XPath integrated into .NET
Framework languages that implement the LINQ pattern (e.g., C#, VB, etc.). This provides a consistent query experience
across LINQ enabled APIs and allows you to combine XML queries and transforms
with queries from other data sources. We
will go in more depth on XLinq's query capability in section 3, "Querying
XML with XLinq".
Just as significant as the
Language Integrated Query capabilities of XLinq is the fact that XLinq
represents a new, modernized in-memory XML Programming API. XLinq was designed to be a cleaner,
modernized API, as well as fast and lightweight. XLinq uses modern language features (e.g.,
generics and nullable types) and diverges from the DOM programming model with a
variety of innovations to simplify programming against XML. Even without Language Integrated Query
capabilities XLinq represents a significant stride forward for XML
programming. The next section of this
document, "Programming XML", provides more detail on the in-memory
XML Programming API aspect of XLinq.
XLinq is a language-agnostic component of the LINQ Project.
The samples in most of this document are shown in C# for brevity. XLinq can be
used just as well with a LINQ-enabled version of the VB.NET compiler. Section 5.1, "XLinq in Visual Basic
9.0" discusses VB specific programming with XLinq in more detail.
1.1 Sample XML
For the purposes of this paper
let's establish a simple XML contact list sample that we can use throughout our
discussion.
<contacts>
<contact>
<name>Patrick Hines</name>
<phone type="home">206-555-0144</phone>
<phone type="work">425-555-0145</phone>
<address>
<street1>123 Main St</street1>
<city>Mercer Island</city>
<state>WA</state>
<postal>68042</postal>
</address>
<netWorth>10</netWorth>
</contact>
<contact>
<name>Gretchen Rivas</name>
<phone type="mobile">206-555-0163</phone>
<address>
<street1>123 Main St</street1>
<city>Mercer Island</city>
<state>WA</state>
<postal>68042</postal>
</address>
<netWorth>11</netWorth>
</contact>
<contact>
<name>Scott MacDonald</name>
<phone type="home">925-555-0134</phone>
<phone type="mobile">425-555-0177</phone>
<address>
<street1>345 Stewart
St</street1>
<city>Chatsworth</city>
<state>CA</state>
<postal>91746</postal>
</address>
<netWorth>500000</netWorth>
</contact>
</contacts>
2. Programming XML with XLinq
This section details how to
program with XLinq independent of Language Integrated Query. Because XLinq provides a fully featured
in-memory XML programming API you can do all of the things you would expect
when reading and manipulating XML. A few
examples include the following:
· Load XML into
memory in a variety of ways (file, XmlReader, etc.).
· Create an XML tree
from scratch.
· Insert new XML
Elements into an in-memory XML tree.
· Delete XML Elements
out of an in-memory XML tree.
· Save XML to a
variety of output types (file, XmlWriter, etc.).
And much more. You should be able to accomplish pretty much any most XML programming task tasks you run into using this
technology.
2.1 XLinq Design
Principles
XLinq is designed to be a
lightweight XML programming API. This
is true from both a conceptual perspective, emphasizing a straightforward, easy
to use programming model, and from a memory and performance perspective. Its public data model is aligned as much as
possible with the W3C XML Information Set.
2.1.1 Key
Concepts
This section outlines some key
concepts that differentiate XLinq from other XML programming APIs, in particular
the current predominant XML programming API, the W3C DOM.
2.1.1.1 Functional
Construction
In object oriented programming
when you create object graphs, and correspondingly in W3C DOM, when creating an
XML tree, you build up the XML tree in a bottom-up manner. For example using XmlDocument (the DOM implementation from
Microsoft) this would be a typical way to create an XML tree.
XmlDocument doc = new XmlDocument();
XmlElement name =
doc.CreateElement("name");
name.InnerText = "Patrick Hines";
XmlElement phone1 =
doc.CreateElement("phone");
phone1.SetAttribute("type", "home");
phone1.InnerText = "206-555-0144";
XmlElement phone2 =
doc.CreateElement("phone");
phone2.SetAttribute("type", "work");
phone2.InnerText = "425-555-0145";
XmlElement street1 =
doc.CreateElement("street1");
street1.InnerText = "123 Main St";
XmlElement city =
doc.CreateElement("city");
city.InnerText = "Mercer Island";
XmlElement state =
doc.CreateElement("state");
state.InnerText = "WA";
XmlElement postal =
doc.CreateElement("postal");
postal.InnerText = "68042";
XmlElement address =
doc.CreateElement("address");
address.AppendChild(street1);
address.AppendChild(city);
address.AppendChild(state);
address.AppendChild(postal);
XmlElement contact = doc.CreateElement("contact");
contact.AppendChild(name);
contact.AppendChild(phone1);
contact.AppendChild(phone2);
contact.AppendChild(address);
XmlElement contacts =
doc.CreateElement("contacts");
contacts.AppendChild(contact);
doc.AppendChild(contacts);
This style of coding provides
few clues to the structure of the XML tree.
XLinq supports this approach to constructing an XML tree but also
supports an alternative approach referred to as functional construction. Here is how you would construct the same XML
tree by using XLinq functional construction.
XElement contacts =
new XElement("contacts",
new XElement("contact",
new XElement("name", "Patrick
Hines"),
new XElement("phone", "206-555-0144",
new XAttribute("type",
"home")),
new XElement("phone", "425-555-0145",
new XAttribute("type",
"work")),
new XElement("address",
new XElement("street1", "123
Main St"),
new XElement("city", "Mercer
Island"),
new XElement("state", "WA"),
new XElement("postal", "68042")
)
)
);
Notice that by indenting (and
squinting a bit) the code to construct the XML tree shows the structure of the
underlying XML.
Functional construction is
described further section 2.5, "Creating XML from Scratch".
2.1.1.2 Document
"Free"
When programming XML your
primary focus is usually on XML elements and perhaps attributes. This makes sense because an XML tree, other
than at the leaf level, is composed of XML elements and your primary goal when
working with XML is traversing or manipulating the XML elements that make up
the XML tree. In XLinq you can work
directly with XML elements in a natural way.
For example you can do the following:
· Create XML elements
directly (without an XML document involved at all)
· Load them from XML
that exists in a file
· Save (write) them
to a writer
Compare this to W3C DOM, in
which the XML document is used as a logical container for the XML tree. In DOM XML nodes, including elements and
attributes, must be created in the context of an XML document. Here is a fragment of the code from the
previous example to create a name element:
XmlDocument doc = new XmlDocument();
XmlElement name =
doc.CreateElement("name");
Note how the XML document is a
fundamental concept in DOM. XML nodes
are created in the context of the XML document.
If you want to use an element across multiple documents you must import
the nodes across documents. This is
an unnecessary layer of complexity that XLinq avoids.
In XLinq you create XML
elements directly:
XElement name = new XElement("name");
You do not have to create an
XML Document to hold the XML tree. The
XLinq object model does provide an XML document to use if necessary, for
example if you have to add a comment or processing instruction at the top of
the document. The following is an
example of how to create an XML Document with an XML Declaration, Comment, and
Processing Instruction along with the contacts content.
XDocument contactsDoc = =
new
new XDocument(
new
new XDeclaration("1.0", "UTF-8", "utf-8", "yes"),