Project

Profile

Help

How to connect?
Download (15.6 KB) Statistics
| Branch: | Revision:

he / src / userdoc / dotnet.xml @ 7728ae0b

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="dotnet" title="Saxon on .NET">
3
   <h1>Saxon on .NET</h1>
4
      
5

    
6
      <p>Saxon is available on both the Java and .NET platforms. This section of
7
the documentation describes aspects of Saxon that are specific to the .NET platform.</p>
8

    
9
      <p>The Saxon source code is written in Java. It has been ported to the .NET platform by cross-compiling
10
the bytecode produced by the Java compiler into the IL code used on .NET, and adding various components
11
designed to integrate Saxon fully into the .NET environment. These additions include:</p>
12
      <ol>
13
         <li>
14
         <p>Addition of command-line interfaces <code>Transform</code>, <code>Query</code>, and <code>Validate</code>.</p>
15
      </li>
16
         <li>
17
         <p>Addition of a front-end API suitable for calling Saxon from .NET languages such as C#, VB.NET, or ASP.NET.</p>
18
      </li>
19
         <li>
20
         <p>Internal changes within Saxon to take advantage of services offered by the .NET Common Language Runtime,
21
for example collation support, URI handling, and XML parsing.</p>
22
      </li>
23
      </ol>
24

    
25
   <p>The different Saxon packages, Saxon-HE (Home Edition), Saxon-PE (Professional Edition) and Saxon-EE (Enterprise Edition), 
26
      are all available on .NET, with the same functionality as the Java versions.</p>
27
         
28
         <aside>When Saxon-EE is used on .NET, queries and stylesheets are selectively compiled to IL code for faster execution. Internally,
29
         the Saxon compiler generates Java bytecode; the IKVM runtime automatically translates this to IL code when it is loaded.
30
         Code generation typically improves the performance of queries by around 25%. The code is transient (in memory): it
31
         cannot be saved as a persistent executable.</aside>
32

    
33
      <p>Installation of Saxon on the .NET platform is described at <a class="bodylink" href="/about/installationdotnet">Installation (.NET)</a>.</p>
34

    
35
      <p>The commands <code>Transform</code>, <code>Query</code>, and <code>Validate</code> have the same format
36
as their Java counterparts. They are described in the following places:</p>
37
      <ul>
38
         <li>
39
         <p>
40
            <a class="bodylink" href="/using-xsl/commandline">Running XSLT from the Command Line</a>
41
         </p>
42
      </li>
43
         <li>
44
         <p>
45
            <a class="bodylink" href="/using-xquery/commandline">Running XQuery from the Command Line</a>
46
         </p>
47
      </li>
48
         <li>
49
         <p>
50
            <a class="bodylink" href="/schema-processing/commandline">Running Validate from the Command Line</a>
51
         </p>
52
      </li>
53
      </ul>
54

    
55
      <p>An introduction to the API for Saxon on .NET is provided at <a class="bodylink" href="/dotnet/dotnetapi">Saxon API for .NET</a>;
56
full specifications are available in the <a href="/dotnetdoc" class="apilink">.NET API</a>.</p>
57

    
58
      <p>For information about writing extension functions using .NET languages, see
59
<a class="bodylink" href="/extensibility/dotnetextensions">Writing extension functions for .NET</a>.</p>
60
         
61
      <aside>Saxon has been successfully run under the Mono environment (Mono is a .NET emulation for non-Microsoft platforms).
62
      However, it has not been comprehensively validated under Mono and there may be undiscovered restrictions.</aside>   
63
   <section id="dotnetapi" title="Saxon API for .NET">
64
      <h1>Saxon API for .NET</h1>
65
      
66

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

    
70
      <p>This section provides a brief introduction to the structure and concepts of the API. Full specifications are
71
available in the <a href="/dotnetdoc" class="apilink">.NET API</a>.</p>
72

    
73
      <p>A set of example C# programs illustrating various use cases for the API is available in the <code>samples/cs</code>
74
          directory, see <a class="bodylink" href="/samples/dotnetsamples">Example applications for
75
              .NET</a> for further information.</p>
76

    
77
      <p>All the classes referred to below are in the namespace <code>Saxon.Api</code>, and can be loaded from the
78
assembly <code>saxonapi.dll</code>.</p>
79

    
80
      <p>The first thing the application needs to do is to create a <a class="javalink" href="Saxon.Api.Processor">Processor</a>. The <code>Processor</code>
81
holds configuration information for Saxon, and shared resources such as the name pool and schema pool. It is possible
82
to run multiple processors concurrently if required, but it is usually more economical for all Saxon processes within
83
a single application to use the same <code>Processor</code>.</p>
84

    
85
      <p>XSLT, XQuery, and XPath processing all follow the same pattern:</p>
86
      <ul>
87
         <li>
88
            <p>From the <a class="javalink" href="Saxon.Api.Processor">Processor</a>, create a <code>Compiler</code> for the appropriate language, using one of the
89
methods <code>NewXsltCompiler()</code>, <code>NewXQueryCompiler()</code>, or <code>NewXPathCompiler()</code>.</p>
90
         </li>
91
         <li>
92
            <p>Set any required properties or configuration options on the resulting <code>Compiler</code> object (these establish
93
the static evaluation context), and then
94
call its <code>Compile()</code> method to create a corresponding <code>Executable</code>. The <code>Compile()</code> methods are overloaded
95
to accept input from a variety of sources.</p>
96
         </li>
97
         <li>
98
            <p>The <code>Executable</code> object represents the compiled stylesheet, query, or XPath expression. It can be evaluated
99
as often as required, in the same thread or in different threads. The first stage in this evaluation is to call
100
the <code>Load()</code> method on the <code>Executable</code>. The resulting loaded object is an <a class="javalink" href="Saxon.Api.XsltTransformer">XsltTransformer</a>,
101
<a class="javalink" href="Saxon.Api.XQueryEvaluator">XQueryEvaluator</a>, or <a class="javalink" href="Saxon.Api.XPathSelector">XPathSelector</a> depending on the language in use.</p>
102
         </li>
103
         <li>
104
            <p>Properties and configuration methods can then be set on the loaded object to establish the dynamic
105
evaluation context, and the real processing is then finally invoked using another method: this may be <code>Run()</code> in the
106
case of XSLT or XQuery where the output is a newly constructed XML document; or 
107
<code>Evaluate()</code>, <code>EvaluateSingle()</code>, or <code>GetEnumerator()</code> 
108
in the case of XQuery and XPath where the output is an arbitrary sequence.</p>
109
         </li>
110
      </ul>
111

    
112
      <p>The API includes a number of classes that reflect the XSLT/XQuery/XPath data model (XDM). These are as follows:</p>
113
      <ul>
114
         <li>
115
            <p>
116
            <a class="javalink" href="Saxon.Api.XdmValue">XdmValue</a>: an XPath value. This is in general a sequence, whose items are nodes or atomic values.
117
You can supply an <code>XdmValue</code> as the value of a stylesheet or query parameter, and receive an <code>XdmValue</code>
118
as the result of evaluating a query or XPath expression.</p>
119
         </li>
120
         <li>
121
            <p>
122
            <a class="javalink" href="Saxon.Api.XdmItem">XdmItem</a>: an XPath item. This is a subtype of <code>XdmValue</code>, since any item can be treated
123
as a sequence of length one. You can call <code>GetEnumeration</code> on an <code>XdmValue</code> object to iterate
124
over the items in the sequence.</p>
125
         </li>
126
         <li>
127
            <p>
128
            <a class="javalink" href="Saxon.Api.XdmNode">XdmNode</a>: a node. This object provides access to most of the properties of nodes defined in the
129
XDM model: the node kind, the string value, the name, the typed value, the base URI. It also provides a method <code>EnumerateAxis()</code>
130
which allows you to find related nodes using any of the 13 XPath axes. For convenience, the <code>OuterXml</code>
131
property provides a simple way to serialize the node.</p>
132
         </li>
133
         <li>
134
            <p>
135
               <a class="javalink" href="Saxon.Api.XdmAtomicValue">XdmAtomicValue</a>: an atomic value, as defined in the XDM model. You can construct an atomic value directly
136
from common objects such as an integer, a string, a double, or a URI; or you can construct one by specifying a string
137
containing the lexical representation, and a QName identifying the required type.</p>
138
         </li>
139
      </ul>
140

    
141
      <p>The <a class="javalink" href="Saxon.Api.Processor">Processor</a> provides a method <code>NewDocumentBuilder()</code> which, as the name implies, returns
142
a <a class="javalink" href="Saxon.Api.DocumentBuilder">DocumentBuilder</a>. This may be used to construct a document (specifically, an <code>XdmNode</code>)
143
from a variety of sources. The input can come from raw lexical XML by specifying a <code>Stream</code> or a <code>Uri</code>,
144
or it may come from a DOM document built using the Microsoft XML parser by specifying an <code>XmlNode</code>,
145
or it may be supplied programmatically by nominating an <code>XmlReader</code>. Various processing options
146
can be set as properties of the <code>DocumentBuilder</code>: these determine, for example, how whitespace is handled 
147
and whether schema validation is performed. The resulting document can be
148
used as the input to a transformation, a query, or an XPath expression. It might also contain a stylesheet or a schema
149
which can then be used as input to the <a class="javalink" href="Saxon.Api.XsltCompiler">XsltCompiler</a> or the <a class="javalink" href="Saxon.Api.SchemaManager">SchemaManager</a>.</p>
150

    
151
      <p>The <a class="javalink" href="Saxon.Api.SchemaManager">SchemaManager</a> exists only in the Saxon-EE product, and its job is to compile schema documents
152
and to maintain a cache containing the compiled schemas. It thus contains methods to compile schemas from a variety
153
of document sources. It also contains a factory method <code>NewSchemaValidator()</code>, which returns a 
154
<a class="javalink" href="Saxon.Api.SchemaValidator">SchemaValidator</a>. The <code>SchemaValidator</code>, in turn, is used to validate a source document
155
against the set of schema definitions held in the <code>SchemaManager</code>'s cache.</p>
156

    
157
      <p>Finally, the API offers a class <a class="javalink" href="Saxon.Api.XmlDestination">XmlDestination</a> to define the possible ways of handling a document
158
constructed as the output of a transformation, query, or validation episode. Various subtypes of <code>XdmDestination</code>
159
 allow such results to be serialized as XML (using either the Saxon serializer or an <code>XmlTextWriter</code>),
160
 or to be materialized as a Saxon <code>XdmNode</code> or as a DOM <code>XmlNode</code>.</p>
161

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

    
166
      <p>There are several places where the classes in the <code>Saxon.Api</code> package provide an "escape hatch" into
167
the underlying implementation classes. These are provided for the benefit of applications that for some reason 
168
need to mix use of the .NET API with the established Java API. The underlying implementation classes are documented
169
in Java terms and use Java calling conventions, but this does not stop them being used from any .NET language:
170
you may need to consult the <a href="http://www.ikvm.net" class="bodylink">IKVM</a> documentation for details of the mappings.
171
The places where such escape hatches are provided are shown below:</p>
172
      <table>
173
         <thead>
174
            <tr>
175
               <td>
176
                  <p>Interface class</p>
177
               </td>
178
               <td>
179
                  <p>Property</p>
180
               </td>
181
               <td>
182
                  <p>Implementation class</p>
183
               </td>
184
            </tr>
185
         </thead>
186
         <tbody>
187
            <tr>
188
               <td>
189
                  <p><a class="javalink" href="Saxon.Api.Processor">Saxon.Api.Processor</a></p>
190
               </td>
191
               <td>
192
                  <p>Implementation</p>
193
               </td>
194
               <td>
195
                  <p><a class="javalink" href="net.sf.saxon.Configuration">net.sf.saxon.Configuration</a></p>
196
               </td>
197
            </tr>
198
            <tr>
199
               <td>
200
                  <p><a class="javalink" href="Saxon.Api.XdmNode">Saxon.Api.XdmNode</a></p>
201
               </td>
202
               <td>
203
                  <p>Implementation</p>
204
               </td>
205
               <td>
206
                  <p><a class="javalink" href="net.sf.saxon.om.NodeInfo">net.sf.saxon.om.NodeInfo</a></p>
207
               </td>
208
            </tr>
209
            <tr>
210
               <td>
211
                  <p><a class="javalink" href="Saxon.Api.XsltTransformer">Saxon.Api.XsltTransformer</a></p>
212
               </td>
213
               <td>
214
                  <p>Implementation</p>
215
               </td>
216
               <td>
217
                  <p><a class="javalink" href="net.sf.saxon.Controller">net.sf.saxon.Controller</a></p>
218
               </td>
219
            </tr>
220
            <tr>
221
               <td>
222
                  <p><a class="javalink" href="Saxon.Api.XQueryCompiler">Saxon.Api.XQueryCompiler</a></p>
223
               </td>
224
               <td>
225
                  <p>Implementation</p>
226
               </td>
227
               <td>
228
                  <p><a class="javalink" href="net.sf.saxon.query.StaticQueryContext">net.sf.saxon.query.StaticQueryContext</a></p>
229
               </td>
230
            </tr>
231
         </tbody>
232
      </table>
233
   </section>
234
   <section id="xmlparsing" title="XML Parsing in .NET">
235
      <h1>XML Parsing in .NET</h1>
236
      
237

    
238
      <p>When you run Saxon on the .NET platform, there are two XML parsers available: the <code>System.Xml</code> parser
239
supplied with the .NET platform, and the Xerces Apache parser, which is supplied
240
as part of the Saxon product.</p>
241

    
242
      <p>Saxon generally uses the Xerces parser by preference. However, you can force Saxon
243
to use the OpenJDK parser by calling <code>processor.SetProperty("http://saxon.sf.net/feature/preferJaxpParser", "false")</code>.
244
Or from the command line, set the option <code>--preferJaxpParser:off</code>.</p>
245

    
246
      <p>Note that the Microsoft parser does not notify ID or IDREF values from the DTD, or expand attributes with
247
fixed or default values, unless DTD validation is requested. This can be requested using the <code>-v</code> option on the
248
command line, or via the API. (See the <code>DtdValidation</code> property of the <a class="javalink" href="Saxon.Api.DocumentBuilder">DocumentBuilder</a>
249
class.)</p>
250

    
251
      <p>Unparsed entities are not notified to Saxon by the Microsoft parser. 
252
The XSLT functions <a class="bodylink code" href="/functions/fn/unparsed-entity-uri">unparsed-entity-uri()</a>
253
         and <a class="bodylink code" href="/functions/fn/unparsed-entity-public-id">unparsed-entity-public-id()</a> will therefore not work.</p>
254
         
255
      <p>Support for OASIS catalogs is provided at the command line level by means of the command line option
256
      <code>-catalog:filename</code>. To enable this to work, the Apache catalog resolver is integrated in the Saxon DLL.
257
            This works only with the JAXP (Xerces) parser.
258
      To use catalogs when running an application using the Saxon API, the interface is not quite so convenient. 
259
      Call the static method <a class="javalink" href="net.sf.saxon.trans.XmlCatalogResolver#setCatalog">net.sf.saxon.trans.XmlCatalogResolver.setCatalog()</a> (found in <code>saxon-he-10.0.dll</code>)
260
            with three arguments: the filename of the catalog file, the Saxon Configuration object,
261
            and a boolean indicating whether tracing is required.</p>
262
   </section>
263
</article>
(9-9/21)