Edit

Share via

Migrating From the XslTransform Class

  • Article

The XSLT architecture was redesigned in the Visual Studio 2005 release. The XslTransform class was replaced by the XslCompiledTransform class.

The following sections describe some of the main differences between the XslCompiledTransform and the XslTransform classes.

Performance

The XslCompiledTransform class includes many performance improvements. The new XSLT processor compiles the XSLT style sheet down to a common intermediate format, similar to what the common language runtime (CLR) does for other programming languages. Once the style sheet is compiled, it can be cached and reused.

The XslCompiledTransform class also includes other optimizations that make it much faster than the XslTransform class.

Note

Although the overall performance of the XslCompiledTransform class is better than the XslTransform class, the Load method of the XslCompiledTransform class might perform more slowly than the Load method of the XslTransform class the first time it is called on a transformation. This is because the XSLT file must be compiled before it is loaded. For more information, see the following blog post: XslCompiledTransform Slower than XslTransform?

Security

By default, the XslCompiledTransform class disables support for the XSLT document() function and embedded scripting. These features can be enabled by creating an XsltSettings object that has the features enabled and passing it to the Load method. The following example shows how to enable scripting and perform an XSLT transformation.

Note

Script blocks are supported only in .NET Framework. They are not supported on .NET Core or .NET 5 or later.

// Create the XsltSettings object with script enabled.
XsltSettings settings = new XsltSettings(false,true);

// Execute the transform.
XslCompiledTransform xslt = new XslCompiledTransform();
xslt.Load("calc.xsl", settings, new XmlUrlResolver());
xslt.Transform("books.xml", "books.html");

' Create the XsltSettings object with script enabled.
Dim settings As New XsltSettings(False, True)

' Execute the transform.
Dim xslt As New XslCompiledTransform()
xslt.Load("calc.xsl", settings, New XmlUrlResolver())
xslt.Transform("books.xml", "books.html")

For more information, see XSLT Security Considerations.

New Features

Temporary Files

Temporary files are sometimes generated during XSLT processing. If a style sheet contains script blocks, or if it is compiled with the debug setting set to true, temporary files may be created in the %TEMP% folder. There may be instances when some temporary files are not deleted due to timing issues. For example, if the files are in use by the current AppDomain or by the debugger, the finalizer of the TempFileCollection object will not be able to remove them.

The TemporaryFiles property can be used for additional cleanup to make sure that all temporary files are removed from the client.

Support for the xsl:output Element and XmlWriter

The XslTransform class ignored xsl:output settings when the transform output was sent to an XmlWriter object. The XslCompiledTransform class has an OutputSettings property that returns an XmlWriterSettings object containing the output information derived from the xsl:output element of the style sheet. The XmlWriterSettings object is used to create an XmlWriter object with the correct settings that can be passed to the Transform method. The following C# code illustrates this behavior:

// Create the XslTransform object and load the style sheet.
XslCompiledTransform xslt = new XslCompiledTransform();
xslt.Load(stylesheet);

// Load the file to transform.
XPathDocument doc = new XPathDocument(filename);

// Create the writer.
XmlWriter writer = XmlWriter.Create(Console.Out, xslt.OutputSettings);

// Transform the file and send the output to the console.
xslt.Transform(doc, writer);
writer.Close();

Debug Option

The XslCompiledTransform class can generate debug information, which enables you to debug the style sheet with the Microsoft Visual Studio Debugger. See XslCompiledTransform(Boolean) for more information.

Behavioral Differences

Transforming to an XmlReader

The XslTransform class has several Transform overloads that return transformation results as an XmlReader object. These overloads can be used to load the transformation results into an in-memory representation (such as XmlDocument or XPathDocument) without incurring the overhead of serialization and deserialization of the resulting XML tree. The following C# code shows how to load the transformation results into an XmlDocument object.

// Load the style sheet
XslTransform xslt = new XslTransform();
xslt.Load("MyStylesheet.xsl");

// Transform input document to XmlDocument for additional processing
XmlDocument doc = new XmlDocument();
doc.Load(xslt.Transform(input, (XsltArgumentList)null));

The XslCompiledTransform class does not support transforming to an XmlReader object. However, you can do something similar by using the CreateNavigator method to load the resulting XML tree directly from an XmlWriter. The following C# code shows how to accomplish the same task using XslCompiledTransform.

// Transform input document to XmlDocument for additional processing
XmlDocument doc = new XmlDocument();
using (XmlWriter writer = doc.CreateNavigator().AppendChild()) {
    xslt.Transform(input, (XsltArgumentList)null, writer);
}

Discretionary Behavior

The W3C XSL Transformations (XSLT) Version 1.0 Recommendation includes areas in which the implementation provider may decide how to handle a situation. These areas are considered to be discretionary behavior. There are several areas where the XslCompiledTransform behaves differently than the XslTransform class. For more information, see Recoverable XSLT Errors.

Extension Objects and Script Functions

XslCompiledTransform introduces two new restrictions on the use of script functions:

  • Only public methods may be called from XPath expressions.

  • Overloads are distinguishable from each other based on the number of arguments. If more than one overload has the same number of arguments, an exception will be raised.

In XslCompiledTransform, a binding (method name lookup) to script functions occurs at compile time, and style sheets that worked with XslTransform may cause an exception when they are loaded with XslCompiledTransform.

XslCompiledTransform supports having msxsl:using and msxsl:assembly child elements within the msxsl:script element. The msxsl:using and msxsl:assembly elements are used to declare additional namespaces and assemblies for use in the script block. See Script Blocks Using msxsl:script for more information.

XslCompiledTransform prohibits extension objects that have multiple overloads with the same number of arguments.

MSXML Functions

Support for additional MSXML functions have been added to the XslCompiledTransform class. The following list describes new or improved functionality:

See also