Basic and Advanced XMLPackage Debugging

How To: Basic and Advanced XMLPackage Debugging

Applies To:  AspDotNetStorefront versions 6.0 - current

What is an XML Package?

A lot of developers in the AspDotNetStorefront community have had exposure to XMLPackages.  Some have managed to use them very creatively, stretching the capabilities of the technology to achieve some pretty cool feats (Chris McKellar, former proprietor of Vibe Commerce was very good at using XML Packages in ways that would make us mere mortals scratch our heads).  To developers and designers new to the platform however, XML Packages can be pretty daunting if you are unfamiliar with XSLT.  Since there are a huge number of resources available for XSLT, I’ll not go into that here (but do recommend that you read up to give yourself some background information).  Instead I will focus on some of the unique debugging capabilities (and challenges) surrounding using XML packages.  Advanced debugging does require full source code for the AspDotNetStorefront application, so keep that in mind before reading too much further.

In simple terms, an XML Package is a proprietary, patent-pending AspDotNetStorefront technology that basically consists of an XSLT transform that can retrieve and generate its own XML data source and accept a variety of different input parameters.  Data can be retrieved from a SQL database, from a “system” XML document that is generally available at runtime whenever an xml package is invoked, and even a call to a webpage (useful for processing things like RSS feeds). 

XML Packages are used for a number of different operations within the AspDotNetStorefront application, but most notably they are used to generate and format the HTML that makes up entity (category, manufacturer, department, etc.) pages and product pages.  They are also used to generate the search page and format the display of the homepage in conjunction with the template.  XML Packages can be invoked programmatically, by using a custom user control in a web form, by using parser tokens in the skin or topics, and even by calling them using an extension function from another XML Package.

Why XML Packages?

XML Packages were developed as a means to allow web designers without C#/VB.NET/ASP.NET programming experience to modify some of the more important aspects of the website without having to call in the development staff.  They are based on XSLT, which has been around for a dozen or more years and is an accepted W3C recommendation.  Because it is similar to XHTML in appearance (and in fact often times consists largely of XHTML), the learning curve is not as steep as it would be to learn web application development in ASP.NET.  

Basic Debugging and Development

XMLPackages use XPath to access pieces of data.  Let’s say that your website serves both wholesale and retail customers, and you want to display a special message that is only visible to wholesale customers.  To do this, you want to find out if the customer level ID is greater than zero.  But how do you do that in an XMLPackage?  Well, you can use XPath to query the system XML document available to all XMLPackages to get the customer level ID like so:

        <xsl:param name="CustomerLevelID">

          <xsl:value-of select="/root/System/CustomerLevelID" />

        </xsl:param>


 But how exactly did I know that the proper XPath was /root/System/CustomerLevelID?  This is where debug mode really comes in handy.   To turn on debug mode:

  1. Make absolutely sure that your IIS Application Pool account has write/modify permissions to your site’s images directory.  Debug mode writes temporary files to this directory, so if permissions are not set properly all you will get is an exception.
  2. Open the xml package you are using in your favorite IDE.
  3. The second line of the XMLPackage will be the start of the package node, and it has an attribute called debug.  Simply set this attribute to ‘true’.

<package version="2.1" displayname="Variants In Right Bar" debug="true" includeentityhelper="true">

 

Now re-open the page using your xml package in your browser and scroll down.  You should see four very large text areas on the page.  If you don’t see them, then make sure you set debug=true in the right XMLPackage.

TIP: If you aren’t sure what XMLPackage a page is using, sometimes you can find out from the HTML source.  In your browser do a “view source”.  Then search for the phrase “xmlpackage”.  Product and entity pages write the package name out as an HTML comment.

The second text area will be titled {package name}_store.runtime.xml.  This is the xml document that the package runs against.  If you look under root/System you will see that there is a CustomerLevelID node.  You can use XPath to navigate anywhere in the document.   I find it helpful when doing development to run the package once in debug and then copy the contents of the runtime xml text area into an actual XML file in Visual Studio.  This allows me to easily reference the data I am working with without having to run the package (something you may not be able to even do depending on what kind of modification you are in the middle of).   

Debug mode is also a great source of information if you aren’t getting the results you expect from your SQL queries.  The data in the _store.runtime.sql text area will provide what SQL statements are being executed as well as any parameters being passed to those statements, allowing you to run them in SQL Management Studio for further debugging and analysis.

Advanced Debugging

In the majority of cases you can make do with the information output from package debug mode.  Sometimes however more drastic techniques are required.  An example of this might be when you get the very unhelpful “Error calling extension function…” error which advises you to reference a stack trace that isn’t available to you or doesn’t exist.

XSLT extension functions are managed code functions/methods that are registered for use by the transform.  AspDotNetStorefront has a rather large class containing a number of useful functions that perform everything from stripping HTML from text to outputting an AJAX shipping estimator.  All AspDotNetStorefront extension functions are contained in the AspDotNetStorefrontCore XSLTExtensionBase class (this class is located in AspDotNetStorefrontCommon in versions prior to 8.0.1.0).  Debugging is the same as debugging any other managed code.

  1. Open the solution in Visual Studio and either attach to an already-running process or hit F5 to start debugging.
  2. Locate the extension function you need to debug in your XMLPackage.
  3. Find the like-named method with the same signature within the XSLTExtensionBase class
  4. Set your breakpoint inside XSLTExtensionBase
  5. Run the page containing your XMLPackage and debug as normal.

It isn’t hard, but hopefully by pointing out that extension functions can be debugged just as easily as any other code saves you a bit of time.

But what do you do when your package is blowing up and you have no idea why?  This happens… not frequently, but when it does, the result can be hours of frustrating guesswork.  Fortunately, there is a way out.  With the proper setup you can actually debug directly into an xml package.  Here is how it works:

  1. Set your package to debug=true as specified earlier in this article
  2. Navigate to the page containing your problem XMLPackage
  3. Load up the full source code solution in Visual Studio and open the AspDotNetStorefrontCore XMLPackage2 class
  4. Hit F5 to start debugging, or attach to your already-running process
  5. Find this block of code inside of TransformString()

                try

                {

                    if (HasASPDNSFNameSpace)

                    {

                        m_Transform.Transform(m_DataDocument, m_TransformArgumentList, ms);

                        m_RequiresParser = true;

                    }

                    else

                    {

                        m_Transform.Transform(m_DataDocument, null, ms);

                    }

                }

  1. Set breakpoints on the m_transform.Transform(…) lines
  2. Reload your page in your browser
  3. When Visual Studio hits your breakpoint, go to File à Open
  4. Browse to the site’s web/images folder and open the {package name}_store.runtime.xsl file
  5. You’ll be notified that your file has changed outside of Visual Studio and you will be asked if you want to reload it.  Say no.
  6. In the XSL file, set breakpoints like you would in managed code.
  7. Now continue debugging.  You’ll hit the breakpoint inside the XSL file and stop.  You are now debugging your XML package.

Keep in mind that a single page in AspDotNetStorefront may call several XMLPackages.  It is normal for your m_transform.Transform(…) breakpoint to be hit multiple times.  You may even have to continue past it a few times before the _store.runtime.xsl file shows up in images.  That is to be expected.  If you check the folder each time your breakpoint is hit, eventually the XSL file will show up and you will be able to set your breakpoints.

Once you are debugging inside the XSL file, you can traverse it line-by-line to see exactly where the point of failure is occurring.  You can even use the F11 key to step into extension functions right from within the XSLT.   


Article ID: 22, Created On: 5/15/2012, Modified: 5/15/2012