Saxon API for .NET

A new API has been developed providing access to XSLT, XQuery, XPath, and XML Schema processing on the .NET platform. This is available from any .NET-supported language, although the examples are all expressed in C# terms.

This section provides a brief introduction to the structure and concepts of the API. Full specifications are available in the .NET API.

A set of example C# programs illustrating various use cases for the API is available in the samples/cs directory, see Example applications for .NET for further information.

All the classes referred to below are in the namespace Saxon.Api, and can be loaded from the assembly saxonapi.dll.

The first thing the application needs to do is to create a Processor. The Processor holds configuration information for Saxon, and shared resources such as the name pool and schema pool. It is possible to run multiple processors concurrently if required, but it is usually more economical for all Saxon processes within a single application to use the same Processor.

XSLT, XQuery, and XPath processing all follow the same pattern:

The API includes a number of classes that reflect the XSLT/XQuery/XPath data model (XDM). These are as follows:

The Processor provides a method NewDocumentBuilder() which, as the name implies, returns a DocumentBuilder. This may be used to construct a document (specifically, an XdmNode) from a variety of sources. The input can come from raw lexical XML by specifying a Stream or a Uri, or it may come from a DOM document built using the Microsoft XML parser by specifying an XmlNode, or it may be supplied programmatically by nominating an XmlReader. Various processing options can be set as properties of the DocumentBuilder: these determine, for example, how whitespace is handled and whether schema validation is performed. The resulting document can be used as the input to a transformation, a query, or an XPath expression. It might also contain a stylesheet or a schema which can then be used as input to the XsltCompiler or the SchemaManager.

The SchemaManager exists only in the Saxon-EE product, and its job is to compile schema documents and to maintain a cache containing the compiled schemas. It thus contains methods to compile schemas from a variety of document sources. It also contains a factory method NewSchemaValidator(), which returns a SchemaValidator. The SchemaValidator, in turn, is used to validate a source document against the set of schema definitions held in the SchemaManager's cache.

Finally, the API offers a class XmlDestination to define the possible ways of handling a document constructed as the output of a transformation, query, or validation episode. Various subtypes of XdmDestination allow such results to be serialized as XML (using either the Saxon serializer or an XmlTextWriter), or to be materialized as a Saxon XdmNode or as a DOM XmlNode.

These classes are designed to be combined in arbitrary ways. For example, you might run an XQuery whose result is a sequence of newly-constructed document nodes. You could then iterate over these nodes, and for each one, apply an XSLT transformation whose result is then serialized.

There are several places where the classes in the Saxon.Api package provide an "escape hatch" into the underlying implementation classes. These are provided for the benefit of applications that for some reason need to mix use of the .NET API with the established Java API. The underlying implementation classes are documented in Java terms and use Java calling conventions, but this does not stop them being used from any .NET language: you may need to consult the IKVM documentation for details of the mappings. The places where such escape hatches are provided are shown below:

Interface class

Property

Implementation class

Saxon.Api.Processor

Implementation

net.sf.saxon.Configuration

Saxon.Api.XdmNode

Implementation

net.sf.saxon.om.NodeInfo

Saxon.Api.XsltTransformer

Implementation

net.sf.saxon.Controller

Saxon.Api.XQueryCompiler

Implementation

net.sf.saxon.query.StaticQueryContext