<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="dotnet" page="dotnetapi" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Saxon API for .NET</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: Saxon API for .NET"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Saxon API for .NET</h1>
<p>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.</p>
<p>This section provides a brief introduction to the structure and concepts of the API. Full specifications are
available <a href="../dotnetdoc/index.html" class="bodylink">here</a>.</p>
<p>A set of example C# programs illustrating various use cases for the API is available in the <code>samples/cs</code>
directory.</p>
<p>All the classes referred to below are in the namespace <code>Saxon.Api</code>, and can be loaded from the
assembly <code>saxonapi.dll</code>.</p>
<p>The first thing the application needs to do is to create a <code>Processor</code>. The <code>Processor</code>
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 <code>Processor</code>.</p>
<p>XSLT, XQuery, and XPath processing all follow the same pattern:</p>
<ul>
<li content="para">
<p>From the <code>Processor</code>, create a Compiler for the appropriate language, using one of the
methods <code>NewXsltCompiler</code>, <code>NewXQueryCompiler</code>, or <code>NewXPathCompiler</code>.</p>
</li>
<li content="para">
<p>Set any required properties or configuration options on the resulting Compiler object (these establish
the static evaluation context), and then
call its <code>Compile</code> method to create an Executable. The <code>Compile</code> methods are overloaded
to accept input from a variety of sources.</p>
</li>
<li content="para">
<p>The Executable object represents the compiled stylesheet, query, or XPath expression. It can be evaluated
as often as required, in the same thread or in different threads. The first stage in this evaluation is to call
the <code>Load</code> method on the Executable. The resulting loaded object is an <code>XsltTransformer</code>,
<code>XQueryEvaluator</code>, or <code>XPathSelector</code> depending on the language in use.</p>
</li>
<li content="para">
<p>Properties and configuration methods can then be set on the loaded object to establish the dynamic
evaluation context, and the real processing is then finally invoked using another method: this may be <code>Run</code> in the
case of XSLT or XQuery where the output is a newly constructed XML document, or
<code>Evaluate</code>, <code>EvaluateSingle</code>, or <code>GetEnumerator</code>
in the case of XQuery and XPath where the output is an arbitrary sequence.</p>
</li>
</ul>
<p>The API includes a number of classes that reflect the XSLT/XQuery/XPath data model (XDM). These are as follows:</p>
<ol>
<li content="para">
<p>
<code>XdmValue</code>: an XPath value. This is in general a sequence, whose items are nodes or atomic values.
You can supply an <code>XdmValue</code> as the value of a stylesheet or query parameter, and receive an <code>XdmValue</code>
as the result of evaluating a query or XPath expression.</p>
</li>
<li content="para">
<p>
<code>XdmItem</code>: an XPath item. This is a subtype of <code>XdmValue</code>, since any item can be treated
as a sequence of length one. You can call <code>GetEnumeration</code> on an <code>XdmValue</code> object to iterate
over the items in the sequence.</p>
</li>
<li content="para">
<p>
<code>XdmNode</code>: a node. This object provides access to most of the properties of nodes defined in the
XDM model: the node kind, the string value, the name, the typed value, the base URI. It also provides a method <code>EnumerateAxis</code>
which allows you to find related nodes using any of the 13 XPath axes. For convenience, the <code>OuterXml</code>
property provides a simple way to serialize the node.</p>
</li>
<li content="para">
<p>
<code>XdmAtomicValue</code>: an atomic value, as defined in the XDM model. You can construct an atomic value directly
from common objects such as an integer, a string, a double, or a Uri; or you can construct one by specifying a string
containing the lexical representation, and a QName identifying the required type.</p>
</li>
</ol>
<p>The <code>Processor</code> provides a method <code>NewDocumentBuilder</code> which, as the name implies, returns
a <code>DocumentBuilder</code>. This may be used to construct a document (specifically, an <code>XdmNode</code>)
from a variety of sources. The input can come from raw lexical XML by specifying a <code>Stream</code> or a <code>Uri</code>,
or it may come from a DOM document built using the Microsoft XML parser by specifying an <code>XmlNode</code>,
or it may be supplied programmatically by nominating an <code>XmlReader</code>. Various processing options
can be set as properties of the <code>DocumentBuilder</code>: 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 <code>XsltCompiler</code> or the <code>SchemaManager</code>.</p>
<p>The <code>SchemaManager</code> exists only in the <code>Saxon-EE</code> product, and its job is to compile schema documents
and to maintain a cache containing the compiled schemas. It thus contains method to compile schemas from a variety
of document sources. It also contains a factory method <code>NewSchemaValidator</code>, which returns a
<code>SchemaValidator</code>. The <code>SchemaValidator</code>, in turn, is used to validate a source document
against the set of schema definitions held in the <code>SchemaManager</code>'s cache.</p>
<p>Finally, the API offers a class <code>XmlDestination</code> to define the possible ways of handling a document
constructed as the output of a transformation, query, or validation episode. Various subtypes of <code>XdmDestination</code>
allow such results to be serialized as XML (using either the Saxon serializer or an <code>XmlTextWriter</code>),
or to be materialized as a Saxon <code>XdmNode</code> or as a DOM <code>XmlNode</code>.</p>
<p>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.</p>
<p>There are several places where the classes in the <code>Saxon.Api</code> 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 <a href="http://www.ikvm.net" class="bodylink">IKVM</a> documentation for details of the mappings.
The places where such escape hatches are provided are shown below:</p>
<table>
<thead>
<tr>
<td content="para">
<p>Interface class</p>
</td>
<td content="para">
<p>Property</p>
</td>
<td content="para">
<p>Implementation class</p>
</td>
</tr>
</thead>
<tbody>
<tr>
<td content="para">
<p>Saxon.Api.Processor</p>
</td>
<td content="para">
<p>Implementation</p>
</td>
<td content="para">
<p>net.sf.saxon.Configuration</p>
</td>
</tr>
<tr>
<td content="para">
<p>Saxon.Api.XdmNode</p>
</td>
<td content="para">
<p>Implementation</p>
</td>
<td content="para">
<p>net.sf.saxon.om.NodeInfo</p>
</td>
</tr>
<tr>
<td content="para">
<p>Saxon.Api.XsltTransformer</p>
</td>
<td content="para">
<p>Implementation</p>
</td>
<td content="para">
<p>net.sf.saxon.Controller</p>
</td>
</tr>
<tr>
<td content="para">
<p>Saxon.Api.XQueryCompiler</p>
</td>
<td content="para">
<p>Implementation</p>
</td>
<td content="para">
<p>net.sf.saxon.query.StaticQueryContext</p>
</td>
</tr>
</tbody>
</table>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="xmlparsing.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
