This article provides a roadmap to introduce the .NET Framework namespaces and classes that you can use to programmatically execute ExtensibleStylesheets 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:
HOW TO: Apply an XSL Transformation to an XML Document by Using Visual C# .NET
300929back to the top The System.Xml.Xsl Namespace
HOW TO: Apply an XSL Transformation from an XML Document to an XML Document by Using Visual Basic .NET
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
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:
Advanced XSLT Features
- 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.
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:
320847back to the top Parameterized XSLT Transformations
HOW TO: Pipeline XSLT Transformations in .NET Applications
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.
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:
321704back to the top Inline Script Blocks
HOW TO: Execute Parameterized XSL Transformations in .NET Applications
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:
PRB: Cannot Unload Assemblies That You Create and Load by Using Script in XSLT
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
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
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:
321702back to the top General Guidelines for Using the .NET Framework Classes to Execute XSLT Transformations
HOW TO: Use Extension Objects When You Execute XSL Transformations in Visual Basic .NET Applications
back to the top Performance of XSLT Transformations in the .NET Framework
- 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.
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:
325689back to the top Troubleshooting
INFO: Performance of XSLT Transformations in the .NET Framework
If you experience problems or if you have questions, you can refer to theMSDN 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