INFO: Roadmap for Executing XSLT Transformations in .NET Applications (313997)

SUMMARY

This article provides a roadmap to introduce the .NET Framework namespaces and classes that you can use to programmatically execute Extensible Stylesheets Language Transformation (XSLT) transformations in .NET applications. Roadmap articles provide links to useful information, including online documentation, Microsoft Knowledge Base articles, and Microsoft white papers, to help you learn about a Microsoft product or technology.

This article is not an XSLT tutorial. This article assumes that you are familiar with the World Wide Web Consortium (W3C) XSLT standard and have experience with writing XSLT style sheets to transform XML data.

back to the top

Overview

XSLT is a World Wide Web Consortium (W3C) standard for transforming XML data. XSLT is typically used to write style sheets to transform XML data to other formats such as HTML, fixed length text, comma-separated text, or a different XML format.

From the developer perspective, XSLT is a programming language with a rich, XML-based syntax that implements elements that correspond to programming constructs and elements to address common transformation requirements.

XSLT style sheets frequently use XML Path Language (XPath) queries to locate nodes in the source XML document and to apply XSLT templates to transform these nodes. The efficiency of the XPath queries in an XSLT style sheet frequently influence and affect the performance of transformations that use it.

From a high-level stand point, an XSLT processor is a software component that applies a specified style sheet to a specified source XML document to execute an XSLT transformation and to generate the required output.

The final output that the XSLT transformations generate are typically result documents that present the original XML data in the specified target format.

back to the top

Writing Code in a .NET Application to Execute XSLT Transformation

The following QuickStart tutorial and Microsoft Knowledge Base articles demonstrate how to write code in a .NET application to apply an XSLT style sheet to an XML document to execute a basic transformation: back to the top

The System.Xml.Xsl Namespace

The XslTransform class in the System.Xml.Xsl namespace implements the .NET Framework XSLT processor. Object instances of this class are created and used to execute XSLT transformations in .NET applications. The implementation of the XSLT processor in the .NET Framework is compliant with version 1.0 of the W3C XSLT Recommendation.

The System.Xml.Xsl namespace also implements the following classes to support XSLT exception handling and advanced options that are related to the execution of XSLT transformations and XPath queries:

• XsltArgumentList. You can use object instances of this class to supply extension object instances and values for XSLT parameters that XSLT style sheets define and reference.
• XsltCompileException. This class generates the .NET Framework exception when an error occurs while you are compiling an XSLT style sheet. An XSLT style sheet is compiled when the Load method of an XslTransform object is executed.
• XsltException. This class generates the .NET Framework exception when a run-time error occurs while you are executing an XSLT transformation.
• XsltContext, IXsltContextFunction, and IXsltContextVariable. These advanced components are used to implement a custom XPath query execution context when there is a requirement to implement and reference user-defined functions and variables in XPath queries that are executed in .NET applications by using the XPathNavigator class and Document Object Model (DOM) classes.
  
  To more easily implement user-defined functions and variables in XPath query expressions that are included in an XSLT style sheet, you can use inline script blocks, extension objects, and XSLT variables or parameters.For additional information about how to use these components, click the article number below to view the article in the Microsoft Knowledge Base:

  324899 HOW TO: Implement and Use Custom Extension Functions When You Execute XPath Queries in Visual Basic .NET

back to the top

Advanced XSLT Features

This section describes several advanced XSLT features.

back to the top

Pipelining XSLT Transformations

Pipelining refers to the process of transforming a source XML document by incrementally applying two or more XSLT style sheets. The output that each intermediate phase generates is supplied as the input to the next phase all the way through to the final phase, which then generates the appropriate output.

This method is useful when you must persist the output that the intermediate phases generate for additional processing that is not directly tied into the transformation process. For additional information about this topic and for a code sample that illustrates its usage, click the article number below to view the article in the Microsoft Knowledge Base: back to the top

Parameterized XSLT Transformations

It is a common XSLT practice to define and to use parameters in style sheets. Parameterized XSLT style sheets use the <xsl:param> element to define parameters that are referenced in XPath query expressions to selectively locate and transform nodes in the source XML data. The values for the defined parameters can be hard-coded in the style sheet or supplied at run time. The latter practice of dynamically supplying input parameter values to control the transformation process is the most common usage of this feature.

In .NET applications, an XsltArgumentList object is used to supply values for XSLT parameters at execution time. The AddParam method is used to add a name-value pair that represents a parameter that is defined in the style sheet and its value to an XsltArgumentList object. The XsltArgumentList object is then supplied as a parameter when executing the Transform method of the XslTransform object that is used to execute the transformation.

The GetParam and the RemoveParam methods are used to access and to remove individual parameters that are added to an XsltArgumentList object. For additional information about how to execute parameterized XSLT transformation in .NET applications, click the article number below to view the article in the Microsoft Knowledge Base: back to the top

Inline Script Blocks

Inline script functions are one of the options that you can use to implement user-defined functions and sub procedures that are referenced in XPath query expressions that are used in an XSLT style sheet. The ability to include inline script blocks in XSLT style sheets is a W3C extension.

In the .NET Framework, custom inline functions and subroutines are coded in <msxsl:script> blocks in the XSLT style sheet. You can use a Microsoft Visual Studio .NET programming language such as Microsoft Visual Basic .NET or Microsoft Visual C# .NET to implement these routines.

One of the drawbacks that is associated with using inline script blocks is that they make the XSLT style sheets non-portable. The technology, the tags, and the semantics that are used to implement inline script blocks are vendor-specific extensions that the W3C XSLT specifications do not standardize.

You can only use an XSLT style sheet that defines and uses inline script blocks successfully in transformations that are executed by using an XSLT processor that can interpret the related semantics and integrate with the technology that has to execute the code.

In the .NET Framework, managed assemblies are generated and loaded implicitly to execute the code that is contained in inline <msxsl:script> script blocks. There is currently a known problem in the .NET Framework that prevents these assemblies from being correctly unloaded when the transformation process completes. This anomaly can lead to an increase in memory usage if the affected style sheet is repeatedly loaded to execute XSLT transformations. The unreleased memory is released only when the host process is recycled. For additional information about this problem in the .NET Framework, click the article number below to view the article in the Microsoft Knowledge Base: To work around this problem in Microsoft ASP.NET applications, you can load the affected style sheets only one time during the life of the application, cache the affected style sheets (in the ASP.NET cache), and then reuse the cached versions for transformations after that.

In Windows Forms and Console applications, you can use global XslTransform object instances to load the affected style sheets when the application starts and to execute later transformations. These workarounds do not apply when XSLT transformations have to be executed in stateless environments (for example, with middle-tier Enterprise Services components).

Microsoft recommends that you use XSLT extension objects to implement custom XPath extension functions to work around this problem.

back to the top

XSLT Extension Objects

Microsoft recommends that you use Extension objects to implement custom subroutines and functions that are referenced in XPath query expressions that are used in an XSLT style sheet.

You can create .NET Framework DLLs to implement and to use Extension objects when you execute transformations in .NET applications. The custom subroutines and functions are implemented in a DLL, and an object instance of the DLL component is provided as a run-time parameter by using an XsltArgumentList object when you execute the Transform method of an XslTransform object.

The AddExtensionObject method of the XsltArgumentList class is used to add an Extension object instance to an XsltArgumentList object. You can use the Get and the Remove methods of the Extension object to access and to remove an Extension object instance that is added to an XsltArgumentList object.

The W3C XSLT specification addresses the concept and the use of Extension elements and functions without any heed or reference to the base technology that you must use to implement them. You must define and use standards-based XML namespace prefixes in style sheets to reference functions and subroutines that are implemented in Extension objects. Vendors can select a technology that is best suited to their platform to address the implementation aspects of the Extension objects. For additional information about the concept and the use of XSLT Extension objects in the .NET Framework and for steps to create an end-to-end application that demonstrates how to use Extension objects when you execute XSLT transformations in .NET applications, click the article number below to view the article in the Microsoft Knowledge Base: back to the top

General Guidelines for Using the .NET Framework Classes to Execute XSLT Transformations

• The XPathDocument class is highly optimized for XSLT and XPath processing. For optimal performance, always use an XPathDocument object to supply the source XML while you are executing an XSLT transformation.
• You can cache and reuse XslTransform objects that are used to load XSLT style sheets that are frequently used to execute later transformations.
• The XSLT processor does not automatically cache Extension object instances that are used in XSLT transformations. You can cache and reuse XsltArgumentList objects that are used to supply Extension object instances for frequently used XSLT style sheets when you execute later transformations. This is the method to cache Extension objects that are used in XSLT transformations in the .NET Framework.
• An XSLT style sheet that implements inline script blocks should only be loaded one time and cached. You should reuse the cached XslTransform object for later transformations. You can use this practice to overcome the memory management problem that is described in the Microsoft Knowledge Base article Q316775 when you must use inline script functions in a style sheet.
• Microsoft recommends that you use Extension objects to implement custom functions that are referenced in XPath query expressions that are used in XSLT style sheets. Implement custom XsltContext, IXsltContextFunction, and IXsltContextVariable classes only when you have to implement and to reference custom extension functions in XPath query expressions that are executed in .NET applications by using the XPathNavigator and the DOM classes.
• Implement exception handling code to handle the XsltCompileException, the XsltException, and the XmlException .NET Framework exception classes when you write code to execute XSLT transformations. These exception classes provide information about any XSLT-specific or XML-specific problems that occur when you try to execute an XSLT transformation. Additionally, Microsoft recommends that you implement code to handle other specific .NET Framework exceptions and that you implement the generic System.Exception class, based on other, non-XSLT-related functionality that is implemented in the code block that executes the XSLT transformation.

back to the top

Performance of XSLT Transformations in the .NET Framework

For additional information about the causes and the solutions for the known performance problems when you execute XSLT transformations in .NET applications, click the article number below to view the article in the Microsoft Knowledge Base: back to the top

Troubleshooting

If you experience problems or if you have questions, you can refer to the MSDN newsgroups where you can share your experiences with your peers. You can also use the Microsoft Knowledge Base where you can search for articles about specific issues or contact Microsoft Product Support Services. back to the top