This appendix summarizes useful XML topics and techniques.
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.
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.
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.
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 . |
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>");
The following two sections explain how you can use the XmlTextReader
class and the Document Object Model to read XML code.
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. |
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
.
The following list summarizes some XML-related technologies.
The following sections provide more information about XPath and XSLT.
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.
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.
For an example, see the section “XSLT” in Chapter 24, “XML.”
3.139.82.4