XSLT Debugger for Visual Studio Code

A powerful Visual Studio Code extension that enables debugging support for XSLT stylesheets. Set breakpoints, step through transformations, inspect variables, and evaluate XPath expressions in real-time using a .NET-based debug adapter.

Features

• Breakpoint Support: Set breakpoints in XSLT files and step through transformations
• Variable Inspection: Automatically materialises XSLT variables and context nodes inside VS Code’s VARIABLES pane
• XPath Evaluation: Evaluate XPath expressions in the current context
• Inline C# Scripting: Debug XSLT stylesheets with embedded C# code using Roslyn
• Multiple Engines: Support for compiled XSLT engine (XSLT 1.0 + inline C#) and Saxon engine (XSLT 1.0 without msxsl:script, plus XSLT 2.0/3.0)
• Cross-Platform: Works on Windows, macOS, and Linux
• Probe Tagging: Instrumented breakpoints and trace messages are tagged with dbg:probe="1" so repeated runs stay idempotent

XSLT Processing Engines

Engine Selection: Auto-detected based on XSLT version and inline script usage, or manually set with "engine": "compiled" or "engine": "saxonnet" in launch.json

⚠️ Current Limitations

• Debugging focuses on basic XSLT structures (templates, loops, expressions); complex dynamic calls are not instrumented
• Cannot step into inline C# scripts, though Roslyn instrumentation still logs entry parameters and return values to the console for visibility
• Variable inspection uses "falldown" approach: variables are auto-captured via instrumentation as execution progresses forward (cannot re-run or step back to previous lines)
• No support for: step back, goto targets, set variable, conditional breakpoints, or debug console autocomplete
• Variable capture limited to @select-based variables; complex variables with content children may not be fully captured
• Trace logging adds ~5-15% overhead in trace/traceall modes
• Cannot debug inside xsl:attribute elements - attributes are processed atomically; set breakpoints before/after attribute blocks instead
• Cannot debug closing tags (e.g., </xsl:template>, </message>) - they contain no executable code

Note: Step-into for xsl:call-template is fully supported (F11).

Quick Start

For Users

1. Install the extension from the VS Code marketplace:

   Platform-Specific Extensions:

   • macOS: Search for "XSLT Debugger Darwin" in VS Code Extensions
   • Windows: Search for "XSLT Debugger Windows" in VS Code Extensions

   Or install from .vsix file:

   # macOS
   code --install-extension xsltdebugger-darwin-darwin-arm64-1.0.0.vsix
   
   # Windows
   code --install-extension xsltdebugger-windows-win32-x64-1.0.0.vsix
   

2. Create a debug configuration in .vscode/launch.json

3. Start debugging by pressing F5 or selecting "Debug XSLT" from the debug menu

For Developers

1. Clone and build the extension:

   npm install
   npm run compile
   dotnet build ./XsltDebugger.DebugAdapter
   dotnet test ./XsltDebugger.Tests/XsltDebugger.Tests.csproj -v minimal
   

2. Run the Extension Development Host:

   • Press F5 in VS Code to launch the extension development host
   • Select the "XSLT: Launch" configuration to debug a stylesheet

3. Package and install locally:

   Build both platforms at once (recommended):

   ./package-all.sh
   code --install-extension xsltdebugger-darwin-darwin-arm64-1.0.0.vsix
   

   Platform-specific packaging (build individually):

   # For macOS only
   ./package-darwin.sh
   code --install-extension xsltdebugger-darwin-darwin-arm64-1.0.0.vsix
   
   # For Windows only
   ./package-win.sh
   code --install-extension xsltdebugger-windows-win32-x64-1.0.0.vsix
   

Usage

Setting Up a Debug Configuration

Create a .vscode/launch.json file in your project workspace:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "xslt",
      "request": "launch",
      "name": "Debug XSLT",
      "engine": "compiled",
      "stylesheet": "${workspaceFolder}/ShipmentConf.xslt",
      "xml": "${workspaceFolder}/ShipmentConf.xml",
      "stopOnEntry": false
    }
  ]
}

Configuration Parameters

Variable Substitutions

• ${file}: Currently open file in editor
• ${workspaceFolder}: Root of your workspace
• ${workspaceFolder}/relative/path.xslt: Specific file in workspace

Example Configurations

Basic debugging (auto engine selection):

{
  "type": "xslt",
  "request": "launch",
  "name": "Debug XSLT",
  "stylesheet": "${workspaceFolder}/transform.xslt",
  "xml": "${workspaceFolder}/data.xml"
}

XSLT 2.0/3.0 with Saxon engine:

{
  "type": "xslt",
  "request": "launch",
  "name": "Debug XSLT 2.0/3.0",
  "engine": "saxonnet",
  "stylesheet": "${file}",
  "xml": "${workspaceFolder}/data.xml"
}

Advanced debugging with detailed logging:

{
  "type": "xslt",
  "request": "launch",
  "name": "Debug with Trace",
  "stylesheet": "${workspaceFolder}/transform.xslt",
  "xml": "${workspaceFolder}/data.xml",
  "logLevel": "trace",
  "stopOnEntry": true
}

Debugging Features

Stepping Features

• F11 (Step Into): Steps into xsl:call-template calls, allowing you to debug named templates
• F10 (Step Over): Executes the current line without stepping into template calls
• Shift+F11 (Step Out): Continues execution until returning from the current template

Variable Inspection Notes

• Auto-Capture: Variables are automatically instrumented during stylesheet compilation - debug messages are injected after each variable declaration
• Falldown Approach: Variables appear in the Variables panel as execution flows forward past their declarations (not available before declaration)
• No Step Back: Since variables are captured via forward instrumentation, you cannot step backward to re-inspect previous values
• XSLT 2.0/3.0: Full support via Saxon engine with @select-based variable capture
• XSLT 1.0 (no inline C#): Saxon engine reuses 1.0-safe probes (value-of/message) for equivalent capture behaviour
• XSLT 1.0 + inline C#: Limited variable inspection via Compiled engine only

Log Levels

Inline C# Scripting

The debugger supports XSLT stylesheets with embedded C# code using msxsl:script elements:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:msxsl="urn:schemas-microsoft-com:xslt"
                xmlns:my="urn:my-scripts">
  <msxsl:script language="C#" implements-prefix="my">
    public string Hello(string name) {
      return "Hello, " + name;
    }
  </msxsl:script>

  <xsl:template match="/">
    <output>
      <xsl:value-of select="my:Hello(/root/name)"/>
    </output>
  </xsl:template>
</xsl:stylesheet>

Requirements

For Users

• Visual Studio Code 1.105.0 or higher
• No additional dependencies (the extension includes the .NET debug adapter)

For Developers

• Visual Studio Code 1.105.0 or higher
• .NET 8.0 SDK (for building the debug adapter)
• Node.js 18 or higher (for building the extension)

Architecture

VS Code Extension (TS) → DAP Protocol → .NET Debug Adapter → XSLT Engines

• Extension (src/extension.ts): Registers debug type, resolves paths
• Adapter (XsltDebugger.DebugAdapter/): DAP server, engine management, breakpoint/stepping logic
• Engines: XsltCompiledEngine (XSLT 1.0 + C#), SaxonEngine (XSLT 1.0 without msxsl:script, plus 2.0/3.0)
• Instrumentation:
  • Breakpoints: Both engines inject dbg:break() extension function calls at breakpoint lines
  • Variables: Saxon engine injects <xsl:message> elements after variable declarations to auto-capture values
  • Message Listener: SaxonMessageListener.cs parses [DBG] messages and populates the Variables panel

What's New in v0.6.0

• Reliable stepping: F10/F11/Shift+F11 work correctly with xsl:call-template for both engines
• Improved instrumentation: Template entry/exit tracking prevents "fall through" during nested calls
• Test coverage: 115+ integration tests covering step-in/over/out scenarios

See CHANGELOG.md for full version history.

Contributing

Contributions are welcome!

# Build and test
npm install && npm run compile
dotnet build ./XsltDebugger.DebugAdapter
dotnet test ./XsltDebugger.Tests

# Package locally
./package-all.sh  # macOS + Windows
code --install-extension xsltdebugger-darwin-darwin-arm64-0.6.0.vsix

Submit PRs with tests for new functionality.

License

MIT License - see LICENSE file.

Third-Party: SaxonHE10Net31Api uses Mozilla Public License 2.0 (Martin Honnen's community IKVM build).