Appendix V
XML
This appendix summarizes useful XML topics and techniques.
Special Characters
The following table lists five special characters defined for use in XML files.
| Character | Code |
< | < |
> | > |
& | & |
' | ' |
" | " |
You can also include special characters inside CDATA sections. A CDATA section begins with <![CDATA[ and includes all the following text until it reaches the closing sequence ]]>. The CDATA can include carriage returns, ampersands, quotes, and other special characters.
Writing XML Data
The .NET Framework provides two main ways to write XML data: the XmlWriter class and the XML Document Object Model. The following two sections describe these approaches.
XmlWriter
The XmlWriter class provides methods for writing the pieces of an XML file. To use an XmlWriter to write XML data into a file, call the class’s Create method to create the file. Then use the other methods to write the pieces of the XML document into the file.
The following table lists the most useful XmlWriter methods.
| Method | Purpose |
Close | Closes the writer’s underlying stream. |
Create | Creates an XmlWriter associated with a file, stream, StringBuilder, or other object. |
Dispose | Frees the writer’s resources. (You can use the using statement to ensure that the writer is disposed.) |
Flush | Flushes output to the underlying stream. |
WriteAttributeString | Writes an attribute with a specified name and value. |
WriteCData | Writes CDATA. |
WriteComment | Writes a comment. |
WriteElementString | Writes an element with a specified name and text value. |
WriteEndAttribute | Ends an attribute started with WriteStartAttribute. |
WriteEndDocument | Ends the document. |
WriteName | Writes a name. |
WriteStartAttribute | Starts an attribute. |
WriteStartDocument | Starts the document. |
WriteStartElement | Starts an element. |
WriteString | Writes a string, escaping special characters such as < and > if necessary. |
WriteValue | Writes a value such as a bool, int, or double. |
The XmlTextWriter class, which inherits from XmlWriter, works much as XmlWriter does but it can produce nicely indented output. Simply create an XmlTextWriter instead of an XmlWriter, set its Formatting property to Indented, and create the XML file using the methods described in the preceding table.
Document Object Model
The XML Document Object Model (DOM) provides a more structured way to build XML documents. It uses objects to create an in-memory model of an XML document. You can then manipulate the model and save the result into an XML file or string.
Two of the most important classes for manipulating the DOM are XDocument and XElement.
The XDocument class represents an XML document. Its most useful properties are Declaration, which gets or sets the document’s XML declaration, and Root, which returns the document’s root element.
The following table lists the XDocument class’s most useful methods.
| Method | Purpose |
Add | Adds an item to the document’s child collection. (Note that you can add only one child, the root element, to the document.) |
DescendantNodes | Returns a collection of XNode objects that are descendants of the document. |
Descendants | Returns a collection of XElement objects that are descendants of the document. If you specify a name, the method returns only elements with that name. |
Load | Loads the document from a filename, stream, or XmlReader. |
Parse | Creates a new XDocument from an XML string. |
Save | Saves the document into a file, stream, or writer. |
ToString | Returns the document’s indented XML code. |
WriteTo | Writes the document into an XmlWriter. |
The XElement class represents an element in an XML document. The following table lists the XElement class’s most useful properties.
| Property | Purpose |
Document | Returns the XDocument that contains the element. |
FirstAttribute | Gets the element’s first attribute. |
FirstNode | Gets the element’s first child node. |
HasAttributes | Returns true if the element has attributes. |
HasElements | Returns true if the element has child elements. |
IsEmpty | Returns true if the element contains no content. (It still might have attributes.) |
LastAttribute | Gets the element’s last attribute. |
LastNode | Gets the element’s last child node. |
Name | Gets or sets the element’s name. |
NextNode | Returns the next node in the element’s parent’s child list. |
NodeType | Gets the node’s type. |
Parent | Gets the element’s parent element. |
PreviousNode | Returns the previous node in the element’s parent’s child list. |
Value | Gets or sets the node’s text contents. |
The following table lists the XElement class’s most useful methods.
| Method | Purpose |
Add | Adds an item at the end of the element’s child collection. |
AddAfterSelf | Adds an item to the parent’s child collection after this element. |
AddBeforeSelf | Adds an item to the parent’s child collection before this element. |
AddFirst | Adds an item at the beginning of the element’s child collection. |
Ancestors | Returns a collection of XElement objects that are ancestors of the element. If you specify a name, the method returns only elements with that name. |
Attribute | Returns an attribute with a specific name. |
Attributes | Returns a collection containing this element’s attributes. If you specify a name, the collection includes only attributes with that name. |
DescendantNodes | Returns a collection of XNode objects that are descendants of the element. |
Descendants | Returns a collection of XElement objects that are descendants of the element. If you specify a name, the method returns only elements with that name. |
DescendantsAndSelf | Returns a collection of XElement objects that includes this element and its descendants. If you specify a name, the method returns only elements with that name. |
Element | Returns the first child element with a specified name. |
Elements | Returns a collection holding the element’s children. If you specify a name, the method returns only elements with that name. |
ElementsAfterSelf | Returns a collection holding the element’s siblings that come after this element. If you specify a name, the method returns only elements with that name. |
ElementsBeforeSelf | Returns a collection holding the element’s siblings that come before this element. If you specify a name, the method returns only elements with that name. |
IsAfter | Returns true if this node comes after another specified node in a document. |
IsBefore | Returns true if this node comes before another specified node in a document. |
Load | Loads the element from a filename, stream, or reader. |
Nodes | Returns a collection holding this element’s child nodes. |
NodesAfterSelf | Returns a collection holding the node’s siblings that come after this node. |
NodesBeforeSelf | Returns a collection holding the node’s siblings that come before this node. |
Parse | Creates an XElement from an XML string. |
Remove | Removes this element from its parent. |
RemoveAll | Removes all nodes and attributes from this element. |
RemoveAttributes | Removes this element’s attributes. |
RemoveNodes | Removes this element’s child nodes. |
ReplaceAll | Replaces the element’s child nodes and attributes with specified new ones. |
ReplaceAttributes | Replaces the element’s attributes with specified new ones. |
ReplaceNodes | Replaces the element’s child nodes with specified new ones. |
ReplaceWith | Replaces this node with new specified content. |
Save | Saves the element into a file, stream, or writer. |
SetAttributeValue | Sets, adds, or removes an attribute. |
SetElementValue | Sets, adds, or removes a child element. |
SetValue | Sets the element’s value. |
ToString | Returns the element’s indented XML code. |
WriteTo | Writes the element into an XmlWriter. |
XML Literals
C# doesn’t support XML literals but it does support multiline string literals and they work almost as well. Simply use the XElement.Parse method to parse a multiline string holding the XML code, as in the following example.
XElement student = XElement.Parse(
@"<Student>
<FirstName>Arthur</FirstName>
<LastName>Andrews</LastName>
<StudentID>83746</StudentID>
</Student>");Reading XML Data
The following two sections explain how you can use the XmlTextReader class and the Document Object Model to read XML code.
XmlTextReader
The XmlTextReader class provides fast, forward-only, noncached methods for reading XML data. It provides methods to move through an XML file one node at a time and to examine the data provided by each node.
To use an XmlTextReader, use the class’s constructor or the XmlReader class’s static Create method to create an object associated with the file or input stream that you want to read. Use the object’s Read method to read the next node from the XML data. After you read a node, you can use the reader’s properties and methods to determine the node’s name, type, attributes, content, and other properties.
The following table lists the most useful XmlReader properties.
| Property | Meaning |
AttributeCount | Returns the number of attributes the node has. |
Depth | Returns the depth of the current node in the XML hierarchy. |
EOF | Returns true when the reader is at the end of the XML data. |
HasAttributes | Returns true if the node has attributes. |
HasValue | Returns true if the node can have a value. |
IsEmptyElement | Returns true if the node is an empty element as in <Overdue />. |
Item | Gets a node attribute by index or name. (This is the class’s indexer, so you use it as in reader[0] instead of invoking the Item property explicitly.) |
Name | Returns the node’s name. |
Value | Returns the text value of the current node. |
The following table lists the XmlReader class’s most useful methods.
| Method | Purpose |
Create | Creates a new reader associated with a string, stream, file, or other data source. |
Dispose | Frees the object’s resources. You can include a using statement to automatically call Dispose. |
GetAttribute | Gets an attribute for the current node by index or name. (Similar to the Item property.) |
IsName | Returns true if its parameter is a valid XML name. |
MoveToAttribute | Moves the reader to an attribute specified by index or name. |
MoveToContent | Moves the reader to the current node’s content. |
MoveToElement | Moves the reader to the element containing the reader’s current position. For example, if you move the reader to examine an element’s attributes, the method moves the reader back to the element’s node. |
MoveToFirstAttribute | Moves the reader to the current node’s first attribute node. |
MoveToNextAttribute | Moves the reader to the current node’s next attribute node. |
Read | Reads the next node from the XML data. |
ReadInnerXml | Returns the current node’s descendants as an XML string. |
ReadOuterXml | Returns the current node’s subtree (including the current node) as an XML string. |
ReadToDescendant | Moves the reader to a subelement with a specified name. |
ReadToNextSibling | Moves the reader past the rest of the current node to its next sibling. |
Skip | Skips the current node’s children. |
Document Object Model
You can use the DOM to load and study an existing XML file.
To load an object model from XML data, simply call the XDocument class’s static Load method, passing it a filename, stream, or XmlReader.
Related Technologies
The following list summarizes some XML-related technologies.
- XSL (Extensible Stylesheet Language)—This refers to a family of languages and tools for reformatting XML data. It includes
- XSLT (XSL Transform)—A language for transforming XML data into other formats such as plain text, HTML, rearranged XML documents, or XSL FO.
- XSL FO (XSL Formatting Objects)—A language for formatting XML data for output for screen, PDFs, printers, and so forth.
- XPath—This is a query language used by XSL and other XML tools to find and identify items within XML data.
- XQuery—A somewhat SQL-like language for querying XML data.
- DTD (Document Type Definition)—An XML data file validation language. You use DTD to define the required structure of an XML file. Then you can validate a particular XML file to see if it satisfies those requirements.
- XSD (XML Schema Definition)—Another XML data file validation language. See DTD.
- XLink—A language for defining hyperlinks in XML data.
- SOAP (Simple Object Access Protocol)—A protocol that lets applications (often running on different computers) exchange data.
- WSDL (Web Services Definition Language)—A language for describing web services.
- RSS (Really Simple Syndication)—A format for XML news feeds and sites that post news-like items.
The following sections provide more information about XPath and XSLT.
XPath
XPath is a language for identifying items in XML data. An XPath query looks vaguely like a file’s pathname in a directory hierarchy. The query can also include operators that work as wildcards, filter the results, and specify relationships among nodes.
The following table lists the most useful operators that you can use in an XPath query.
| Operator | Meaning |
/ | Selects an immediate child. |
// | Selects descendants. |
. | The current node. |
.. | The current node’s parent. |
* | Matches anything. |
@ | Attribute prefix for matching an attribute. For example, @Cost matches an attribute named Cost. |
@* | Selects all attributes. |
() | Groups operations. |
[ ] | Applies a filter. For example, //Planet[@Name="Earth"] matches Planet elements that have a Name attribute with value Earth. |
[ ] | Subscript operator for accessing items in a collection. |
+ | Addition. |
- | Subtraction. |
Div | Floating-point division. |
* | Multiplication. |
Mod | Modulus. |
When a query filters results, it can include the boolean and comparison operators listed in the following table.
| Operator | Meaning |
And | Logical AND |
Or | Logical OR |
not() | Logical NOT |
= | Equals |
!= | Not equals |
< | Less than |
<= | Less than or equal |
> | Greater than |
>= | Greater than or equal |
For more information on XPath, see the following links.
- “XPath Reference” at msdn.microsoft.com/library/ms256115.aspx
- “XPath Examples” at msdn.microsoft.com/library/ms256086.aspx
XSLT
XSLT is a language that you can use to transform XML data into a new format. It’s a fairly complicated language, so there isn’t room to cover it in any depth here. To learn the language, see the following links.
- “XSLT Tutorial” at www.w3schools.com/xsl/default.asp
- “XSLT Elements Reference” at www.w3schools.com/xsl/xsl_w3celementref.asp
- “XSL Transformations (XSLT) Version 1.0” at www.w3.org/TR/xslt
For an example, see the section “XSLT” in Chapter 24, “XML.”