Contents
What is nxslt?
nxslt is a free feature-rich command line utility that allows to perform XSL Transformations (XSLT) using .NET Framework's XSLT implementation - System.Xml.Xsl.XslTransform class. nxslt is backwards compatible with functionality and command line options provided by Microsoft's MSXSL.EXE Command Line Transformation Utility with a tiny difference: unlike msxsl.exe, nxslt does not support specifying start mode. In addition, nxslt has some distinct advanced features, like support for the XInclude 1.0, embedded stylesheets, custom URI resolving, multiple result documents, custom extension functions, built-in rich library of the EXSLT and the EXSLT.NET extenstion functions etc. See nxslt and msxl.exe comparison table for more info.
Requirements
nxslt is the .NET Framework application, written in C# language and requires .NET Framework version 1.0 or 1.1 to be installed.
nxslt has been tested on Microsoft Windows NT4, Windows 2000, Windows XP and Windows Server 2003 with Microsoft .NET Framework 1.0 and 1.1. Reports on testing on non-Windows platforms are greatly appreciated.
Usage
To see help on nxslt usage, run nxslt with -? option:
nxslt -?
You should see the following message: .NET XSLT command line utility, version 1.6 build 2004
(c) 2004 Oleg Tkachenko, http://www.xmllab.net
Running under .NET 1.1.4322.2032
Usage: nxslt source stylesheet [options] [param=value...] [xmlns:prefix=uri...]
Options:
-? Show this message
-o filename Write output to named file
-xw Strip non-significant whitespace from source and stylesheet
-xe Do not resolve external definitions during parse phase
-xi Do not process XInclude during parse phase
-v Validate documents during parse phase
-t Show load and transformation timings
-xs No source XML
-pp Pretty-print source document
-pi Get stylesheet URL from xml-stylesheet PI in source document
-r Use named URI resolver class
-ascii Forces ASCII output encoding
-af Assembly file name to look up URI resolver class
-an Assembly full or partial name to look up URI resolver class
-mo Allow multiple output documents
-ext Comma-separated list of extension object class names
-exslt Use specified EXSLT.NET assembly instead of built-in
implementation (#GAC to load the assembly from the GAC)
-xmlc creds Credentials in username:password@domain format to be
used in Web request authentications when loading source XML
-xslc creds Credentials in username:password@domain format to be
used in Web request authentications when loading XSLT
- Dash used as source argument loads XML from stdin
- Dash used as stylesheet argument loads XSL from stdinBasic usage example: to transform source.xml document using style.xsl stylesheet into result.html file, run the following command: nxslt source.xml style.xsl -o result.html
For more usage info see the following sections.
Along with using in command line, nxslt utility can be integrated into various XSL tools as an external XSLT processor: to use nxslt with XML Spy open Tools/Options menu item, in Options window click on XSL tab, turn "External XSL transformation program" radiobox on and enter the following command into the input field: "{path-to-nxslt}\nxslt.exe %1 %3 -o %2". Intergartion with Xselerator: open Options/Environment Options, click on Transformation tab, click on Add button to add nxslt as another transformation engine, fill into the fields: Menu name: nxslt, Executable: (browse to nxslt.exe), Parameters: %xml% %xsl% -o %out% Click Ok, turn nxslt radiobutton on, click OK, well done.
Note: Individual options may be entered anywhere in the command, but source and stylesheet (they can be filenames or URLs) must follow in this order. Some arguments are mutually exclusive, for instance stylesheet and -pi.
nxslt works under both .NET 1.0 and .NET 1.1. A version supporting new XSLT processor in the .NET 2.0 is being developed. Choose appropriate precompiled version in the download archive.
Specifying Inputs
Location of the source XML document and the XSLT stylesheet may be specified either as a filename/URL or using single dash "-" option, which means that the appropriate document should be read from the standard input stream. Here are examples:
nxslt source.xml style.xsl
nxslt C:\docs\links.xml C:\docs\style.xsl
nxslt http://www.foo.com/index.xml C:\docs\style.xsl
nxslt - style.xsl
nxslt C:\docs\links.xml -
Source XML document can be omitted using -xs option. This may be useful when running XSLT stylesheets that don't require source XML or load XML documents to process explicitly. In such cases instead of providing dummy XML document, just specify -xs option anywhere in the command line: nxslt style.xsl -xs
XSLT stylesheet can be omitted too. Then nxslt performs an identity transformation by copying source XML to an output as is. The rest processing is done as usual. This can be useful to perform various manipulations with source XML, such as resolving XML Inclusions (XInclude), validation, stripping insignificant whitespace or converting to ASCII encoding:
nxslt source.xml
nxslt source.xml -v -o valid.xml
nxslt source.xml -xw -o nowhitespace.xml
nxslt source.xml -ascii -o plain-ascii.xml
In addition, location of the XSLT stylesheet may be specified using -pi option, which means that the stylesheet document should be loaded from the URL, specified in the top-level "xml-stylesheet" processing instruction of the source XML document. This processing instruction must adhere to the format, defined in the W3C Recommendation "Associating Style Sheets with XML documents":
<?xml-stylesheet type="text/xsl" href="style.xsl"?>
If -pi option is specified and the source XML document contains an "xml-stylesheet" processing instruction, its "href" pseudo-attribute value will be used as a stylesheet URL. Relative locations are resolved with respect to the base URI of the source XML document. For example, consider links.xml document in the c:\docs directory: <?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="style.xsl"?>
<links>
<link url="http://www.google.com"/>
</links>Then the following commandnxslt c:\docs\links.xml -pi
will load style.xsl stylesheet from the c:\docs directory.
XSL stylesheet may also be embedded into the source XML document, see W3C XSLT 1.0 Recommendation, 2.7 Embedding Stylesheets. nxslt supports such mechanism by allowing fragment identifier as a stylesheet URL in an "xml-stylesheet" processing instruction. Consider the following sample XML document with an embedded stylesheet:
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="#style"?>
<links>
<link url="http://www.google.com"/>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" id="style">
<xsl:template match="/">
...
</xsl:template>
</xsl:stylesheet>
</links>Then the same command nxslt c:\docs\links.xml -pi
will apply embedded stylesheet to the document.
Note: In order to be located, embedded <xsl:stylesheet> element must have either an attribute named "id", or any other attribute, defined in the DTD as being an ID typed.
Specifying Output
-o option allows to redirect XSLT output to a named file. -o option must be followed by a filename:
nxslt source.xml style.xsl -o result.html
If -o option is not specified, the output is sent to the standard output stream. Note, that stdout may be redirected using usual mechanisms and together with single dash - option it allows to chain XSL transformations without creating any temporary files. For example, output from one transformation may be pipelined into a second transformation: nxslt links.xml style.xsl | nxslt - style2.xsl -o result.html
Error messages and timing information are always sent to the standard error stream.
Other Options
Whitespace Stripping (-xw)
By default nxslt preserves whitespace-only text nodes in the source XML tree as the W3C XSLT 1.0 Recommendation requires. Using -xw option you can enforce nxslt to strip those nodes from the source tree.
Externals resolution (-xe)
By default nxslt resolves external definitions such as DTD external subsets or external entity references when parsing source XML document and stylesheet document. Using -xe option you can disable this behaviour. (Note, that specifying -xe option may affect also validation process.
Validation (-v)
By default nxslt doesn't validate source XML document and the stylesheet. Using -v option you can turn validation of both documents on.
Timings (-t)
nxslt allows to measure approximate transformation time using -t option. Measurands are as follows:
- Time to load, parse and build the source XML document
- Time to load, parse and build the stylesheet document
- Time to compile the stylesheet document
- Time to execute the stylesheet
Credentials (-xmlc and -xslc)
nxslt allows to specify user credentials to be used when loading XML source (-xmlc option) and XSLT stylesheet (-xslc option) documents. The credentials should be provided in the "username:password@domain" format (all parts are optional):
nxslt http://www.example.com/secure/source.xml \
http://www.example.com/secure/style.xsl -xmlc name:psw -xslc name:psw
Pretty printing (-pp)
nxslt can be used to pretty print XML documents. When specifying -pp option (XSLT stylesheet must be omitted then), source XML is outputted in a nicely formatted indented way. -pp option can also be combined with others:
nxslt source.xml -pp
nxslt source.xml -pp -o pretty.xml
nxslt source.xml -xi -pp
Forcing ASCII encoded output (-ascii)
There is a known problem with .NET 1.X XSLT processor (System.Xml.Xsl.XslTransform class) - it doesn't support escaping of characters as XML character references when they cannot be represented in the output encoding. That means that when you output a character that cannot be represented in output encoding, it will be outputted as '?'. Usually this happens when output encoding is set to ASCII.
nxslt allows to workaround the problem. When specifying -ascii option, the output is forced to be ASCII encoded and all non-ASCII characters get escaped as XML character references (&#nnnn; form):
nxslt source.xml style.xsl -ascii -o result.xml
nxslt source.xml -pp -ascii
Passing Parameters To the Transformation
nxslt allows to pass string parameters to the stylesheet. Parameters may be specified after source and stylesheet arguments using name=value syntax. Parameter values that contain whitespace must be enclosed in quotes or apostrophes:
nxslt source.xml style.xsl param1=value1 param2="value 2"
According to the W3C XSLT Recommendation, parameter name is a QName, which consists of an optional prefix and a local part delimited by a colon character. When prefix is specified, it must be bound to a namespace URI by a namespace declaration. Namespace declaration may be defined using xmlns:prefix=namespaceURI or xmlns=namespaceURI (for default namespace) syntax. Here are examples (note that both are equivalent): nxslt source.xml -pi foo:param="value" xmlns:foo="http://foo.com"
nxslt source.xml -pi param="value" xmlns="http://foo.com"
Note: Parameter name cannot be "xmlns" or start with "xmlns:", because this identifies a namespace declaration. Namespace declarations and parameters may be entrered in any order, when the same namespace declaration or parameter occur more than once, the last definition takes precedence.
XML Inclusions (XInclude) (-xi)
nxslt supports XML Inclusions (XInclude) 1.0 via embedded XInclude.NET library. By default XInclude support is enabled for both source XML and stylesheet. It can be disabled using -xi option.
Custom URI Resolving (-r)
nxslt allows to specify a custom URI resolver class to resolve URI references in xsl:import/xsl:include instructions (during XSLT stylesheet loading phase) and in document() function (during XSL transformation phase). By default, nxslt uses standard XmlUrlResolver class to resolve resources referenced by "file://" and "http://" protocols, however, using -r, -af and -an options you can specify your custom XmlResolver to be used too. This allows to use such customized constructs as
<xsl:include href="cache://style2.xsl"/>
or <xsl:apply-templates select="document('cache://source2.xml')/*"/>
The semantics of the aforementioned options is as follows:
-r option specifies partially or fully qualified URI resolver class name, e.g. Acme.Resolvers.CacheResolver. Such name requires additional assembly specification using -af or -an options, but fully qualified class name (which always includes an assembly specifier) is all-sufficient. See MSDN for more info about fully qualified class names.
-af option specifies a file name of the assembly, where the specified resolver class can be found.
-an option specifies partially or fully qualified name of the assembly in the global assembly cache (GAC), where the specified resolver class can be found. See MSDN for more info about partial assembly names.
Basically there are three ways to specify a custom URI resolver class:
- By specifying both a resolver class name and an assembly filename. Consider a custom URI resolver Acme.Resolvers.CacheResolver, bundled into the CacheResolver.dll assembly. Then the command line might look like
nxslt source.xml style.xsl -r Acme.Resolvers.CacheResolver \
-af d:\acme\CacheResolver.dllnxslt then will load d:\acme\CacheResolver.dll assembly and instantiate Acme.Resolvers.CacheResolver class to use its instance as a resolver.
- By specifying both a resolver class name and an assembly partial or full name. So when a custom URI resolver Acme.Resolvers.CacheResolver is installed into the GAC within CacheResolver assembly, the command line might look like
nxslt source.xml style.xsl -r Acme.Resolvers.CacheResolver \
-an CacheResolvernxslt then will load CacheResolver assembly from the GAC and instantiate Acme.Resolvers.CacheResolver class to use its instance as a resolver.
- By specifying fully quilified resolver class name. When a custom URI resolver Acme.Resolvers.CacheResolver is installed into the GAC within CacheResolver assembly, the command line might look like
nxslt source.xml style.xsl \
-r "Acme.Resolvers.CacheResolver,CacheResolver, Version=1.0.1173.28087, \
culture=neutral, PublicKeyToken=49f505af2b7accbc"
nxslt utility then will instantiate Acme.Resolvers.CacheResolver class by its fully qualified name to use its instance as a resolver.
Note: -r, -af and -an options must be followed by their respective values, they can be specified in any order, -af and -an options cannot be used simultaneously.
Multiple Result Documents (-mo)
nxslt allows to create multiple result documents using exsl:document extension element, developed by the EXSLT community initiative.
XslTransform class, which implements XSL Transformations in the .NET Framework, doesn't support neither multiple outputs nor custom extension elements, so nxslt implements support for multiple result documents by postprocessing XSL Transformation result tree using customized XmlWriter (see "Producing Multiple Outputs from an XSL Transformation" article at MSDN for more details). Granting this nxslt supports only a subset of the exsl:document element attributes:
<exsl:document
href = { uri-reference }
method = { "xml" | "text" }
encoding = { string }
omit-xml-declaration = { "yes" | "no" }
standalone = { "yes" | "no" }
doctype-public = { string }
doctype-system = { string }
indent = { "yes" | "no" }
<-- Content: template -->
</exsl:document>
By default support for mutiple result documents turned off and can be turned on using -mo option:
nxslt source.xml style.xsl -o result.html -mo
For more info about multiple result documents creation using exsl:document extension element see the EXSLT formal description.
Note: It's good idea to put "exsl" namespace prefix into the "exclude-result-prefixes" attribute of the xsl:stylesheet element to avoid "exsl" namespace propagation into the transformation result documents.
Custom extension functions (-ext)
nxslt allows to specify extension object classes, whose public methods then can be used as extension functions in an XSLT stylesheet. -ext option must be followed by a comma-separated list of namespace-qualified extension object class names. Each class name must be bound to a namespace URI using prefixes as when providing XSLT parameters. -an and -af options can be used to specify an assembly to load classes from in the same manner it's described in the Custom URI Resolving section. Here are some samples of using custom extension functions
nxslt source.xml style.xsl -ext Acme.Extensions xmlns="http://acme.com"
nxslt source.xml style.xsl -ext a:Acme.Extensions xmlns:a="http://acme.com"
nxslt source.xml style.xsl -ext a:Acme.Extensions,b:Acme.Ext2 \
xmlns:a="http://acme.com" xmlns:b="http://acme2.com"
nxslt source.xml style.xsl -ext a:Acme.Extensions xmlns:a="http://acme.com" \
-af d:\acme\Extensions.dll
EXSLT extenstion functions
nxslt supports rich library of the EXSLT and EXSLT.NET extension functions via embedded or plugged in EXSLT.NET library. EXSLT support is enabled by default and cannot be disabled in this version (do we need the ability to turn it off?). Find full list of supported EXSLT extension functions plus additional EXSLT.NET proprietary extension functions in the EXSLT.NET documentation.
It's also possible to make nxslt to use an external EXSLT.NET implementation instead of a built-in one using -exslt option. This option must be followed by a filepath to a compiled EXSLT.NET assembly or a #GAC keyword. When #GAC is specified, nxslt is trying to load GotDotNet.Exslt assembly from the Global Assembly Cache (GAC), otherwise it loads EXSLT.NET assembly from the specified file path:
nxslt source.xml style.xsl -exslt d:\EXSLT.NET\GotDotNet.Exslt.dll
nxslt source.xml style.xsl -exslt #GAC
nxslt and msxsl.exe
nxslt was inspired by the msxsl.exe utility and has adopted many ideas from it, so all credits are due to Microsoft, Andrew Kimball and other msxsl.exe developers.
Differences from msxsl.exe
- Specifying a start mode (-m option) is not supported
- Specifying MSXML version (-u option) is not supported as irrelevant
- XInclude 1.0 is supported
- Embedded stylesheets are supported
- Multiple output documents are supported
- Custom URI resolving is supported
- Custom extension functions are supported
- EXSLT function library is supported
- Credentials to access XML source and XSLT stylesheet are supported
Download and License
nxslt is a free open source tool, it is subject to the BSD license and is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. You can use it for any commercial or noncommercial purposes, including distributing derivative works.
nxslt is freely available for download in precompiled Windows executable form and in source code (complete Microsoft Visual Studio .NET 2003 C# solution) at the Downloads page.
nxslt is free and any donations are greatly appreciated 
What next?
To be done list (unsorted):
- .NET 2.0 version
- NAnt task
- XSLT profiler
- XSLT trace
- XSLT analizer
- Test with Mono
- Visual Studio add-in
- Add your suggestion
Feedback and Discussion
This utility was created just to be convenient tool for everybody interested in command line XSL Transformations using .NET Framework. So enjoy. Any comments, suggestions, help and contributions are greatly appreciated! Feel free to post any comments to the nxslt Discussion forum.