Getting started with SaxonCS

SaxonCS is a new product for .NET Core, replacing the older Saxon/.NET product. The older product was built by compiling the Java source code to bytecode, and then converting this to run on .NET using the IKVM converter. IKVM has never supported .NET Core (which is the strategic version of .NET for the future), and development has been discontinued, so SaxonCS uses a different approach: Saxonica developed a source code transpiler that converts the Java source code of the product to equivalent C# code.

SaxonCS doesn't come with a graphical user interface: it's designed to be integrated into other tools and applications. You will therefore start by using it from the operating system command line.

SaxonCS is currently only available in the Enterprise Edition, which requires a license file that you can obtain from Saxonica.

  1. SaxonCS 11.0 to 11.4 are targeted at .NET 5 which you will need to install separately. Note that for SaxonCS 11.4, a version for .NET 6 was also published, while SaxonCS 11.5 is built for .NET 6 only (see the "SaxonCS for .NET 6" blog post for more information). For details, see https://dotnet.microsoft.com/download/dotnet/5.0. There's a bewildering variety of options. Choose the latest version of the SDK (for example, SDK 5.0.400) corresponding to your chosen operating system (Windows, MacOS, or Linux) and CPU architecture (for example Arm64, x64, or x86).

  2. Download the software from nuget. Search for the package name SaxonCS. Alternatively, add SaxonCS as a dependency to your Visual Studio or Rider project, and it will be downloaded and installed automatically by the IDE. No further installation is needed.

  3. You will need to obtain a file containing a licence key. The license key is interchangeable between the Java, .NET, and C/C++ platforms. You can apply for a free 30-day evaluation license key by going to www.saxonica.com and clicking on "Try Saxon for 30 days". The license key file will be sent by email within 24 hours. This file, called saxon-license.lic, should be placed in a suitable directory, and the environment variable SAXON_LICENSE_DIR must be set to the name of this directory.

  4. To run Saxon from the command line, invoke it via the dotnet command, for example:

    dotnet SaxonCS transform -s:source.xml -xsl:stylesheet.xsl

    See the dotnet documentation for further details.

    Note that the SaxonCS DLL has a single entry point (Main method). As well as specifying the DLL you want to execute (SaxonCS) you therefore need to specify which Saxon utility you want to run, for example transform, query, or validate.

  5. As a first-time user, you may want to install the sample application Example.cs. This is included in the file saxon-resources-11.zip, which can be downloaded from the Saxonica site. Unzip the contents of this file into the same directory as the SaxonCS software. The easiest (or most productive) way to run the sample application is to create a command-line application in your IDE (for example, Visual Studio), copy the Example.cs source code into the IDE as your entry module, and add a dependency on SaxonCS 11.

You can now use the command line to run one of the sample stylesheets or queries that comes with the saxon-resources download. Assuming you installed into c:\saxon, make this your current directory, and type:

for XSLT (all on one line):

dotnet SaxonCS transform -t -s:samples\data\books.xml -xsl:samples\styles\books.xsl -o:c:\temp.html

for XQuery (all on one line):

dotnet SaxonCS query -t -s:samples\data\books.xml -q:samples\query\books-to-html.xq -o:c:\temp.html

Now open c:\temp.html in your browser to check that it worked.

For more complete details on installing SaxonCS on the .NET platform, see Installing: .NET platform.