Reading Fragments of XML with an XmlReader
The XmlReader, by default,
expects all XML documents to be well-formed. However, there are occasions when
you want to read fragments of XML that may not be strictly well-formed, and
also be able to validate these where possible. To read fragments of XML, you
set the ConformanceLevel property of the XmlReaderSettings instance to ConformanceLevel.Fragment before you
create the XmlReader(s):
rs.ConformanceLevel = ConformanceLevel.Fragment
However, XML fragments do not usually
contain enough information for the XmlReader to be able to
read the document. They may not contain the required namespace declarations, or
the <?xml...?> declaration that defines the language, encoding and white-space
treatment required for the document. In other words, the context for
reading the document may well be missing.
To get round this, you will usually have to
provide the missing information by creating and populating an appropriate XmlParserContext instance. This process starts by adding a new NameTable to hold the namespace declarations to the XmlReaderSettings and then creating a new XmlNamespaceManager over
this. You then add the required namespaces to the XmlNamespaceManager:
rs.NameTable = New NameTable()
Dim nsm As New XmlNamespaceManager(rs.NameTable)
nsm.AddNamespace("rv",
"http://myns/slidesdemo/reviewdate")
Then you can create the new XmlParserContext using the XmlNamespaceManager, and optionally include the language
and white-space handling values you want. And, to specify the encoding of the
document, you just set the Encoding property of the XmlParserContext instance to an appropriate encoding class instance:
Dim xpc As XmlParserContext = New
XmlParserContext(rs.NameTable, _
nsm,
"en", XmlSpace.Default)
xpc.Encoding = New UTF8Encoding()
Then you can create the XmlReader from the XmlReaderSettings instance using the overload of the static Create method that accepts an XmlParserContext instance:
Dim xr As XmlReader = XmlReader.Create("C:\temp\myfile.xml",
rs, xpc)
Now you can read XML fragments that match
the settings in the XmlParserContext. The example page we've been using so far allows you to specify the
following XML fragment as the source, and turn on fragment conformance, using
code like that we've just been discussing. Notice that - with the exception of
the reviewed element - the fragment does not contain any namespace declarations
or prefixes. The namespace prefix on the reviewed element is
acceptable because we create the NameTable containing
this namespace declaration as part of the XmlParserContext we use
to read this fragment:
<slides>
<slide position="1">
<title>Agenda</title>
<rv:reviewed>2004-05-10T00:00:00</rv:reviewed>
</slide>
<slide position="2">
<title>Introduction</title>
<rv:reviewed>2003-10-22T00:00:00</rv:reviewed>
</slide>
</slides>
Figure 5 shows the result, and you can see
the contents of the XML fragment listed above. If you turn off fragment
checking and try to read this fragment (whereupon the appropriate XmlParserContext is not created), you'll see that an error is raised because the "rv" prefix is not declared.
Figure 5 - Reading an XML
Fragment with an XmlReaderSettings and XmlReader Class
Validating Fragments of XML with an XmlReader
Validation is also supported for XML
fragments, as you can see if you turn on validation in the example page. You
can select an invalid fragment and try reading this to see the effects. The
invalid fragment contains the element <rv:reviewed>yes</rv:reviewed>, which is illegal because the schema for this section of XML (slidesrev.xsd in the schema data\subfolder) defines this element as an xs:dateTimetype. Figure 6 shows the results.
Figure 6 - Validating an XML
Fragment with an XmlReaderSettings and XmlReader Class
However, when you read fragments of XML, you often find that
validation warnings are encountered. We specified that warnings should be
raised by setting the ReportValidationWarnings flag in the ValidationFlags property of the XmlReaderSettings instance in our example when a custom error handler is used. If you set the
checkboxes in the example page for validation, custom validation error handling
and warnings reporting, as well as the fragment conformance option, you'll see
these warnings appear when you attempt to read the slides-invalid-fragment.xml file - as shown in Figure 7.
Figure 7 - Displaying Validation
Warnings and Errors for an XML Fragment
Using an XmlResolver to Limit Access to Resources
The final feature that the example we've
been using so far demonstrates is how you can control access to resources when
using an XmlReader. This could be useful if, for example, you want to limit access to
a particular folder or set of XML disk files. By default, the XmlReader uses an XmlResolver that is created internally to resolve references, URLs and paths to
the resources it uses. However, you can create your own XmlResolver instance and use this to set the XmlResolver property of the XmlReaderSettings instance before you create your XmlReader(s).
The first step is to create a PermissionSet that defines the permissions you will demand when the XmlReader tries to access a resource. By specifying PermissionState.None in the constructor, you indicate that no permission demand will be made - and
so access will fail. Note that you must import the System.Security and System.Security.Permissions namespaces when writing code to control access to resources like
this:
Dim ps As New PermissionSet(PermissionState.None)
Now you can create individual permissions,
and add them to the PermissionSet. In the example page, we want to be able to access the folder named data that contains the XML disk files, and so we create a FileIOPermission instance that gives read access to this folder:
Dim fpdata As New FileIOPermission(FileIOPermissionAccess.Read,
Server.MapPath("./data/"))
ps.AddPermission(fpdata)
Then we can create a new XmlSecureResolver (a class that inherits from XmlResolver) and specify
this permission set, then use it to set the XmlResolver property of the XmlReaderSettings instance we're using:
rs.XmlResolver = New XmlSecureResolver(New XmlUrlResolver,
ps)
If you run the example page, and set the
checkbox to block access to all folders, you'll find that an error is displayed
- as shown in Figure 8. This is because the code in the example page does not
add the FileIOPermission to the PermissionSet unless you also set the "Allow access..." checkbox as well.
Figure 8 - Preventing Access to
Resources with an XmlSecureResolver
This error is trapped by the Try..Catch construct around the call to the Create method of the XmlReaderSettings instance. We specifically catch instances of a SecurityException, and display the message then exit from the routine. The SecurityException class exposes a range of properties that describe the exception, but we're only
using the Message property in our example page:
Try
' ... create the XmlReader using the XmlReaderSettings
...
Catch secx As SecurityException
builder.Append("<p><b>ERROR
creating XmlReader:</b><br />")
builder.Append("Message = "
& secx.Message & "</p>")
Label1.Text &= builder.ToString()
Return
Catch ex As Exception
' ... handle exceptions for other errors
here ...
End Try
If you now set the checkbox to allow access
to the data folder, the XmlReader is able to read the XML file
and display the contents as it does when using its default XmlResolver.
Wrapping or "Pipelining" XmlReader Instances
One of the options when you create an XmlReader or XmlWriter using the static Create methods is to
specify as the source (the first parameter of the Create method) another XmlReader or XmlWriter, or an existing TextReader or TextWriter. You can create a new XmlReader instance over
an existing XmlReader or TextReader, and create a new XmlWriter instance over
an existing XmlWriter or TextWriter.
This process is called wrapping or pipelining,
and allows you to add new features to an existing reader or writer as you
create a new instance from it. For example, you can add validation support to
an XmlReader created over an existing XmlReader that does not
validate the incoming XML, or even over a TextReader that is
already referencing an XML document. Notice, however, that you cannot remove features that are already enabled on the source reader or writer. This could,
if permitted, prevent the source reader or writer from behaving correctly.
We provide an example named pipelinereaders.aspx that demonstrates wrapping an XmlReader with another XmlReader. It starts by creating an XmlReader using an XmlReaderSettings instance in the same way as the previous example, but only sets a
few properties of the XmlReaderSettings. The XmlReader is created over the same invalid XML document as you saw in the
previous example:
' create an XmlReaderSettings instance and
set some properties
Dim rs1 As New XmlReaderSettings()
rs1.CloseInput = True
rs1.IgnoreComments = True
rs1.IgnoreWhitespace = True
' declare a variable to hold an XmlReader
Dim xr As XmlReader = Nothing
Try
' create the XmlReader using this first XmlReaderSettings
instance
Dim sPath As String = Server.MapPath("data/slides-invalid-content.xml")
xr = XmlReader.Create(sPath, rs1)
builder.Append("Created
non-validating XmlReader<br />")
Catch ex As Exception
' ... display error details here ...
End Try
Now a new XmlReaderSettings instance is created. By layering over an existing XmlReader, the new XmlReaderwill assume the settings of the existing XmlReader, which you can add to through the new XmlReaderSettings instance. In this case we'll add validation to the new XmlReader.
The next section of code shows the new XmlReaderSettings instance being created, and the validation features set in the same
way as we did in the previous example. This includes adding a custom event
handler to the ValidationEventHandler event of the XmlReaderSettings instance:
' create an new XmlReaderSettings instance
and set some properties
Dim rs2 As New XmlReaderSettings()
' create and populate an XmlSchemaSet
instance
Dim ss As New XmlSchemaSet()
ss.Add("http://myns/slidesdemo", Server.MapPath("data/schema/slides.xsd"))
ss.Add("http://myns/slidesdemo/reviewdate",
Server.MapPath("data/schema/slidesrev.xsd"))
' add XmlSchemaSet to XmlReaderSettings and
turn on validation
rs2.Schemas = ss
rs2.ValidationType = ValidationType.Schema
rs2.ValidationFlags = (rs2.ValidationFlags
+ XmlSchemaValidationFlags.ProcessSchemaLocation)
' add a custom handler for validation
events
AddHandler rs.ValidationEventHandler, AddressOf
MyValidationHandler
Now we create a new XmlReader using the new XmlReaderSettings instance, by specifying
the original XmlReader as the first parameter of the Create method. Then we
call a separate routine named ShowReadToMethods to
display some values from the XML document:
' declare a variable to hold the validating
XmlReader
Dim vxr As XmlReader = Nothing
Try
' create XmlReader using XmlReaderSettings
instance and existing non-validating XmlReader
vxr = XmlReader.Create(xr, rs2)
' display a couple of values from the
invalid XML document
ShowReadToMethods(vxr)
Catch ex As Exception
' ... display error details here ...
End Try
The ShowReadToMethodsroutine
uses the new ReadToXxx methods of the XmlReader class, so
we'll look at this code in the next section when we examine these methods in
more detail. In the meantime, Figure 9 shows the result. You can see that the
document has been validated as it was being read and displayed, and that
processing does not stop when the first validation error is encountered. The
output in the page shows each reader being created, the values of some nodes in
the document, and the messages generated by the custom validation handler we
specified when we created the second XmlReaderSettings instance.
Figure 9 - Wrapping One XmlReader
with another XmlReader that Performs Validation
Two Useful New Features of the XmlReader Class
As well as the use of the static Create methods and the "settings" classes we've just described,
the XmlReader in version 2.0 of System.Xml provides
other new features and opportunities. The two we'll look at here are:
- Reading up to specific
elements or fragments
- Reading typed values
from an XML document
Reading Up To Specific Elements or Fragments
When reading XML documents with an XmlReader where you
want to locate a specific element or attribute node, one of
the most laborious and inefficient parts of the process is actually reading up
to that node. In version 2.0, the XmlReader exposes some
new methods that you can use. These are the ReadToDescendant, ReadToFollowing and ReadToNextSibling methods, which allow you to easily skip over nodes and content
until you arrive at the element node you require.
The example page named pipelinereaders.aspx we used in the previous section demonstrates some of these methods. After
creating the XmlReader that performs validation, the code calls a routine named ShowReadToMethods,
passing in the XmlReader.
This listing shows the ShowReadToMethods routine in full. You can see from this how easy it is to navigate through a
document using these new methods:
Sub ShowReadToMethods(ByVal vxr As XmlReader)
' move to the first descendant slide element
builder.Append("Executing the ReadToDescendant(""slide"")
method<br />")
If vxr.ReadToDescendant("slide")
Then
builder.Append("Found element
'" & vxr.Name)
' display the value of the position
attribute
vxr.MoveToAttribute("position")
builder.Append("' with position
attribute = '" & vxr.Value & "'<br />")
Else
builder.Append("Cannot execute the
<b>ReadToDescendant</b> method.<br />")
End If
' move to the next slide element
builder.Append("Executing the ReadToNextSibling(""slide"")
method<br />")
If vxr.ReadToNextSibling("slide")
Then
builder.Append("Found element
'" & vxr.Name)
' display the value of the position
attribute
vxr.MoveToAttribute("position")
builder.Append("' with position
attribute = '" & vxr.Value & "'<br />")
Else
builder.Append("Cannot execute the
<b>ReadToNextSibling</b> method.<br />")
End If
' move back to element so that ReadToDescendant
can be called next
vxr.MoveToElement()
' move to the title element
builder.Append("Executing the ReadToDescendant(""title"")
method<br />")
If vxr.ReadToDescendant("title")
Then
builder.Append("Found element
'" & vxr.Name)
' display the value of the element
vxr.Read()
builder.Append("' with value =
'" & vxr.Value & "'<br />")
Else
builder.Append("Cannot execute the
<b>ReadToDescendant</b> method.<br />")
End If
' move to the third slide element
builder.Append("Executing the ReadToFollowing(""slide"")
method<br />")
If vxr.ReadToFollowing("slide")
Then
builder.Append("Found element
'" & vxr.Name)
' display the value of the position
attribute
vxr.MoveToAttribute("position")
builder.Append("' with position
attribute = '" & vxr.Value & "'<br />")
Else
builder.Append("Cannot execute the
<b>ReadToFollowing</b> method.<br />")
End If
' move back to element so that ReadToDescendant
can be called next
vxr.MoveToElement()
' move to the reviewed element
builder.Append("Executing the ReadToDescendant(""reviewed"",
_
""http://myns/slidesdemo/reviewdate"")
method<br />")
' NOTE: could have used just "rv:reviewed"
here instead
If vxr.ReadToDescendant("reviewed",
"http://myns/slidesdemo/reviewdate") Then
builder.Append("Found element
'" & vxr.Name)
' display the value of the element
vxr.Read()
builder.Append("' with value =
'" & vxr.Value & "'<br />")
Else
builder.Append("Cannot execute the
<b>ReadToDescendant</b> method.<br />")
End If
End Sub
You can see from this that the ReadToXxx methods return a Boolean value that indicates if they managed to move to the specified nodes in the
document. The routine displays a message in the page before each call to the ReadToDescendant, ReadToFollowing and ReadToNextSibling methods, and the name and value of the node it moved to if the
method succeeds (for the slide elements that have no value, it
displays the value of the position attribute instead). If it cannot
perform the move, the routine displays a message to this effect.
If you look back at Figure 9, you'll see
the results. The code starts by moving to the first descendant slide element using ReadToDescendant("slide"), and then to the next slide element by
calling ReadToNextSibling("slide").
This element has an invalid value for its position attribute, as indicated by the
text generated by the custom validation handler included in the page. Next, the
code calls the MoveToElement method so that the reader is positioned on the slide element itself, and not on the
child text node, before calling ReadToDescendant("title") to move to the title element within
this slide element.
At this point, the only way to get back to previous level in
the node hierarchy, to be able to move to the next slide element, is to call ReadToFollowing("slide").
This method moves through the document in the order that the nodes appear in
the XML, rather than in a hierarchical manner. Notice that, on the way there,
the reader has to read the reviewed child element of the current slide element, which also contains an invalid value - as
shown by the second validation message in the page.
After displaying the value of the position attribute of the third slide element, the
code calls MoveToElement to get back to the element node, and then ReadToDescendant("reviewed","http://myns/slidesdemo/reviewdate") to get to the reviewed element. The reviewed element is in a separate namespace
and has the prefix "rv",
and so we specify the namespace URI as well as the local name of the element.
Alternatively, as noted in the comments in the code, we could specify the
qualified name of the element instead - using the more compact form ReadToDescendant("rv:reviewed").
Reading Typed Values from an XML Document
The XML Infoset model effectively views XML
documents as typed data - often as the equivalent of rowsets such as you'd find
in an ADO.NET DataTable or DataSet. This is achieved by layering the schema over the XML so that each
node (element or attribute) is exposed as an instance of the relevant data
type. In the System.Xml classes, this means standard CLR types such as String, Int32, Boolean, DateTime, etc. To allow you to access documents as typed data, the XmlReader exposes a series of new methods named ReadContentAsXxx and ReadElementContentAsXxx,
where Xxx is the name of the data type. There is also a generic ReadValueAs method, where you specify the data type of the node that you want
to query.
The example page we used at the start of
this article reads some values from the XML document as CLR typed instances
using the ReadContentAsXxx and ReadElementContentAsXxx methods. It reads the value of the position attribute on each slide element as an Int32 integer value (these are defined in the schema as of type xs:unsignedByte) using the ReadContentAsInt method of the XmlReader class. It also reads the value
of the reviewed elements for each slide, which are defined in the schema as of
type xs:dateTime)
as DateTime instances using the ReadElementContentAsDateTime method.
After creating the XmlReader, the code calls the Read method
repeatedly (until it returns False), so that each node is read from the XML document in
turn. If the current node is an element, and this is the start tag, the name
and the value type name (as returned by the ValueType property) are added to the StringBuilder that
will display the results after the complete document has been processed.
However, if validation is enabled for the XmlReader (the checkbox named chkValidate will
be set in this case in our example), the schema will expose the values as the
correct data types and so we can use the appropriate method to extract the
value as a CLR data-typed instance. We do this for the reviewed element, using the ReadElementContentAsDateTime method:
While xr.Read()
If xr.IsStartElement() Then
builder.Append("Element Name:
" & xr.Name)
builder.Append(" ValueType:
" & xr.ValueType.ToString() & "<br />")
If chkValidate.Checked And xr.LocalName
= "reviewed" Then
Dim dt As DateTime = xr.ReadElementContentAsDateTime()
builder.Append("Element Typed
value: " & dt.ToString() & "<br />")
End If
...
Now the code checks if the current element
node has any attributes. If so, it iterates through them in the same way as you
would in System.Xml version 1.x when using an XmlTextReader. The name,
value type and value of each one can then be displayed. However, when
validation is enabled and the current attribute is named position, the code can call the ReadContentAsInt method of the XmlReader to get
the value as an Int32 type as well:
...
If xr.HasAttributes Then
While xr.MoveToNextAttribute()
builder.Append(" - Attribute
Name: " & xr.Name)
builder.Append(" ValueType:
" & xr.ValueType.ToString())
builder.Append("
Value: '" & xr.Value & "'")
If chkValidate.Checked And xr.LocalName
= "position" Then
Dim pos As
Int32 = xr.ReadContentAsInt()
builder.Append("
Typed value: " & pos.ToString())
End If
builder.Append("<br
/>")
End While
End If
End If
...
Finally, the code checks to see if the
current node is the child text node that contains the value of an element (XmlNodeType.Text). Elements in an XML document have their value stored in a child
node, and so this must be handled separately when using an XmlReader. In this case there is no node name (the parent element node
contains the name), but the value can be extracted and displayed:
...
If xr.NodeType = XmlNodeType.Text Then
builder.Append("Element String
Value: '" & xr.Value & "'" & "<br
/>")
End If
End While
Figure 10 shows the readersettings.aspx example page
displaying the XML content when validation is disabled and when it is enabled.
You can see the CLR data type names returned by the ValueType property, and the typed value
that is obtained by calling the appropriate ReadContentAsXxx method when
validation is enabled. The position attribute actually appears as a System.Byte type, but there is no ReadContentAsByte method so the ReadContentAsInt method is used instead to return an Int32 instance. And the reviewed element
appears as a DateTime type as expected, but notice that calling any of the ReadElementContentAsXxxx methods
consumes (i.e. reads) the element value - the child text node - so it does not
appear when the code checks for nodes of type XmlNodeType.Text at the end of the
iteration loop.
Figure 10 - Reading Values from an XML Document as CLR Typed Instances
Summary
In this series of three articles, we explore how the new
features of the XmlReader and XmlWriter classes in version 2.0 of the .NET Framework can be used to read and write XML
documents, and interact with the new XML document store objects. In this first
article, we've concentrated on the XmlReader class, and the new XmlReaderSettings class that makes it easy to generate single or multiple instances of XmlReader with a
range of useful properties. We looked at:
- The new "settings" classes and static Create methods for XmlReader and XmlWriter
- Creating and using an XmlReader to read XML documents and
fragments
- Two of the useful new features of the XmlReader class
The XmlReaderSettings and XmlWriterSettings classes hold a wide range of settings that you may need to apply when you
create an XmlReader or an XmlWriter.
In conjunction with the new static Create methods of XmlReader and XmlWriter, they allow you to store these
settings for use whenever you need to create a reader or writer, saving time
and making the whole process a lot more transparent and efficient.
The XmlReaderSettings class provides features that allow you to specify the general behavior of the XmlReader(s) you
create, such as reading or ignoring DTDs, schemas, white-space, comments, etc.
It also provides features to add validation for XML documents or fragments of
XML, control access to resources, add credentials for accessing remote or
secured resources, and more.
The XmlReader class itself also exposes several useful new features. In particular, in this
article, we looked at how navigation in a document is improved through the new ReadTo methods,
and how you can now access the content of the XML as CLR typed values.
In the next article, we'll move on to look at the XmlWriter class,
and the corresponding XmlWriterSettings class, to see how they make it easier to create and user writers in version 2.0
of the .NET Framework.
