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.

SaxonCS is targeted at .NET 6, which you will need to install separately. For details, see https://dotnet.microsoft.com/en-us/download/dotnet/6.0. There's a bewildering variety of options. Choose the latest version of the SDK (for example, SDK 6.0.403) corresponding to your chosen operating system (Windows, MacOS, or Linux) and CPU architecture (for example AArch64, x64, or x86).

At the time of writing, SaxonCS has not been tested on .NET 7. You're welcome to try it; please share your experiences. We'll try to fix any problems you report.
SaxonCS can be downloaded and installed in two different ways:
- If you're planning to invoke SaxonCS from your own C# code, you can add it as a dependency to your Visual Studio or Rider project, and it will be automatically downloaded from Nuget. No further installation is needed.
- If you're planning to run SaxonCS from the command line, it's best to download an executable built for the platform you are using: there are versions available for Windows, Linux, and MacOS, from www.saxonica.com/download/dotnet.xml. For Windows and Linux, the software comes as a zip file: unzip it into a suitable directory, for example c:\saxon. For MacOS, the software is distributed as a signed, notarized "DMG" file: download the DMG file, open it up, and drag the "SaxonCS" application into the Applications folder; you can then run the executable /Applications/SaxonCS.app/Contents/MacOS/SaxonCS (for convenience, you may want to create an alias or link the application into another directory). For further installation details see Installation: .NET.
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.
To run SaxonCS from the command line, if you downloaded from Nuget then invoke it via the dotnet command, for example:
dotnet SaxonCS transform -s:source.xml -xsl:stylesheet.xsl
(See the dotnet documentation for further details.)

If you downloaded an executable, then you can call it directly, for example:
SaxonCS transform -s:source.xml -xsl:stylesheet.xsl
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.
As a first-time user, you may want to install the sample application Example.cs. This is included in the file saxon-resources-12.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 12.

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 from Nuget, 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 Installation: .NET platform.