Mvp.Xml Project: XInclude.NET module

The XInclude.NET module provides an implementation of the W3C XML Inclusions (XInclude)1.0 Recommendation and the XPointer Framework Recommendation written in C# for the .NET platform. XInclude.NET supports XPointer element() Scheme, XPointer xmlns() Scheme, XPointer xpath1() Scheme and XPointer xpointer() Scheme (XPath subset only). XInclude.NET currently supports only streamable subset of the XInclude, implemented as fast, non-caching, forward-only XIncludingReader class found in the Mvp.Xml.XInclude namespace.

XInclude.NET has been thoroughly tested against XML Inclusions (XInclude) Version 1.0, W3C Conformance Test Suite (2004-11-03) under Microsoft .NET 1.0, 1.1 and 2.0 on Windows 2000, Windows XP and Windows Server 2003.

Contents:

  1. Requirements
  2. Download
  3. Installation and Documentation
  4. History
  5. Usage
  6. Custom XmlResolver
  7. XPointer
  8. Conformance Issues
  9. License
  10. Support

1. Requirements

XInclude.NET module as well as a whole Mvp.Xml library is .NET Framework application and requires .NET Framework version 1.X or 2.0 to be installed.

2. Download

Go to the Downloads page. XInclude.NET module is a part of the Mvp.Xml library release.

3. Installation and Documentation

Find precompiled Mvp.Xml.dll  assembly in the "bin" directiory. The "src" directory contains XInclude.NET sources in Visual Studio .NET 2003 (XInclude/src/v1) and Visual Studio 2005 (XInclude/src/v2) solution form. The documentation can be found in the "doc" directory (online version). Test cases can be found in the "test" directory.
In addition to the API documentation, refer to the "Combining XML Documents with XInclude" article at the MSDN, which introduces XInclude itself and provides details on usage and internal implementation of the XIncludingReader class. Additionally don't forget the normative specs:

4. History

Done in 2.0 release:

Done since 1.2 release:
Done since 1.1 release:
Done since 1.0 release:
Done since 1.0beta release:
Done since 1.0alpha release:

5. Usage

XIncludingReader class, found in the Mvp.Xml.XInclude namespace, is the key class. It's customized  XmlReader, which implements streamable subset of the XInclude and XPointer in a fast, non-caching, forward-only fashion. It can be set on top of another XmlReader, e.g. XmlNodeReader, XmlTextReader or XmlValidatingReader. Such design allows to perform XML Inclusions in many different situations, e.g. before or after validation, before or after building XmlDocument or XPathDocument. Here are some obvious usage scenarios:

XML inclusion during XML reading:

XmlReader reader = new XIncludingReader("source.xml");
while (reader.Read()) {
...

XML inclusion while building XmlDocument:

XmlReader reader = new XIncludingReader(XmlReader.Create("source.xml"));
XmlDocument doc = new XmlDocument();
doc.Load(reader);
...

XML inclusion before an XSL Transformation:

XslTransform xslt = new XslTransform();
xslt.Load("stylesheet.xsl");
XmlReader reader = new XIncludingReader("source.xml");
XPathDocument xdoc = new XPathDocument(reader);
xslt.Transform(xdoc, null, new StreamWriter("result.xml"));
...

Find more examples and test cases in the "test" directory.

Note: When using XInclude with XSLT, take a look at the nxslt.exe - feature-rich .NET XSLT command line utility, which supports XInclude via the XInclude.NET module.

6. Custom XmlResolver

XIncludingReader supports custom URI resolving. This way one can include XML documents from a variety of sources, such as RDBMS or even generated on-the-fly. Find a sample of inlcuding XML data from SQL Server here.
Just set your XmlResolver object to the XmlResolver property of the XIncludingReader. XIncludingReader will call ResolveUri() and GetEntity() methods of your resolver when fetching a resource by URI referenced in "href" attribute of an xi:include element. A custom XmlResolver must return either System.IO.Stream or  System.IO.TextReader or System.Xml.XmlReader from the GetEntity() method.

7. XPointer

XInclude.NET includes XPointer.NET module, which implements XPointer Framework, XPointer element() Scheme, XPointer xmlns() Scheme, The XPointer xpath1() Scheme and XPointer xpointer() Scheme (XPath subset only).

XPointerReader class, found in the Mvp.Xml.XPointer namespace represents XPointer-aware XmlReader and can be used as such outside of XInclude context too.
Find more info at the XPointer.NET module homepage.

8. Conformance Issues

  1. XIncludingReader class implements the streamable subset of XInclude - intra-document references are not supported. That means XIncludingReader treats an absence of an "href" attribute on an xi:include element as an XInclude resource error.
  2. Syntactically incorrect URI references are treated as an XInclude resource error.
  3. Only XPath subset of the xpointer() XPointer Scheme is supported.

9. License

XInclude.NET as part of the Mvp.Xml project is subject to the GPL License - OSI approved free open-source license.

10. Support

You can get support on using XInclude.NET module using the following options:


The project is hosted at SourceForge. Find more at the Mvp.Xml project page at SourceForge.
SourceForge logo
$Id: index.html,v 1.8 2005/11/02 13:21:27 helgy Exp $