Permalink
Fetching contributors…
Cannot retrieve contributors at this time
127 lines (91 sloc) 10 KB
title ms.custom ms.date ms.prod ms.reviewer ms.suite ms.technology ms.tgt_pltfrm ms.topic dev_langs ms.assetid caps.latest.revision author ms.author manager
Migrating From the XslTransform Class
03/30/2017
.net
dotnet-standard
article
VB
CSharp
C++
jsharp
9404d758-679f-4ffb-995d-3d07d817659e
3
mairaw
mairaw
wpickett

Migrating From the XslTransform Class

The XSLT architecture was redesigned in the [!INCLUDEvsprvslong] release. The xref:System.Xml.Xsl.XslTransform class has been replaced by the xref:System.Xml.Xsl.XslCompiledTransform class.

The following sections describe some of the main differences between the xref:System.Xml.Xsl.XslCompiledTransform and the xref:System.Xml.Xsl.XslTransform classes.

Performance

The xref:System.Xml.Xsl.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 xref:System.Xml.Xsl.XslCompiledTransform class also includes other optimizations that make it much faster than the xref:System.Xml.Xsl.XslTransform class.

[!NOTE] Although the overall performance of the xref:System.Xml.Xsl.XslCompiledTransform class is better than the xref:System.Xml.Xsl.XslTransform class, the xref:System.Xml.Xsl.XslCompiledTransform.Load%2A method of the xref:System.Xml.Xsl.XslCompiledTransform class might perform more slowly than the xref:System.Xml.Xsl.XslTransform.Load%2A method of the xref:System.Xml.Xsl.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 xref:System.Xml.Xsl.XslCompiledTransform class disables support for the XSLT document() function and embedded scripting. These features can be enabled by creating an xref:System.Xml.Xsl.XsltSettings object that has the features enabled and passing it to the xref:System.Xml.Xsl.XslCompiledTransform.Load%2A method. The following example shows how to enable scripting and perform an XSLT transformation.

[!code-csharpXML_Migration#16] [!code-vbXML_Migration#16]

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 xref:System.CodeDom.Compiler.TempFileCollection object will not be able to remove them.

The xref:System.Xml.Xsl.XslCompiledTransform.TemporaryFiles%2A 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 xref:System.Xml.Xsl.XslTransform class ignored xsl:output settings when the transform output was sent to an xref:System.Xml.XmlWriter object. The xref:System.Xml.Xsl.XslCompiledTransform class has an xref:System.Xml.Xsl.XslCompiledTransform.OutputSettings%2A property that returns an xref:System.Xml.XmlWriterSettings object containing the output information derived from the xsl:output element of the style sheet. The xref:System.Xml.XmlWriterSettings object is used to create an xref:System.Xml.XmlWriter object with the correct settings that can be passed to the xref:System.Xml.Xsl.XslCompiledTransform.Transform%2A 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 xref:System.Xml.Xsl.XslCompiledTransform class can generate debug information, which enables you to debug the style sheet with the Microsoft [!INCLUDEvsprvs] Debugger. See xref:System.Xml.Xsl.XslCompiledTransform.%23ctor%28System.Boolean%29 for more information.

Behavioral Differences

Transforming to an XmlReader

The xref:System.Xml.Xsl.XslTransform class has several Transform overloads that return transformation results as an xref:System.Xml.XmlReader object. These overloads can be used to load the transformation results into an in-memory representation (such as xref:System.Xml.XmlDocument or xref:System.Xml.XPath.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 xref:System.Xml.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 xref:System.Xml.Xsl.XslCompiledTransform class does not support transforming to an xref:System.Xml.XmlReader object. However, you can do something similar by using the xref:System.Xml.XPath.XPathNavigator.CreateNavigator%2A method to load the resulting XML tree directly from an xref:System.Xml.XmlWriter. The following C# code shows how to accomplish the same task using xref:System.Xml.Xsl.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 xref:System.Xml.Xsl.XslCompiledTransform behaves differently than the xref:System.Xml.Xsl.XslTransform class. For more information, see Recoverable XSLT Errors.

Extension Objects and Script Functions

xref:System.Xml.Xsl.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 xref:System.Xml.Xsl.XslCompiledTransform, a binding (method name lookup) to script functions occurs at compile time, and style sheets that worked with XslTranform may cause an exception when they are loaded with xref:System.Xml.Xsl.XslCompiledTransform.

xref:System.Xml.Xsl.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.

xref:System.Xml.Xsl.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 xref:System.Xml.Xsl.XslCompiledTransform class. The following list describes new or improved functionality:

See Also

XSLT Transformations
Using the XslCompiledTransform Class