DEV Community

Daniel Jonathan
Daniel Jonathan

Posted on

Understanding xsl:message in XSLT

#xsl #logicapps #azure #azuredatamapper

Understanding xsl:message in XSLT

xsl:message is XSLT's built-in instruction for outputting diagnostic messages during transformation. It's the closest thing XSLT has to console.log() or print() statements in other languages.

What It Does

xsl:message sends text to the processor's message stream without affecting your transformation output. This makes it perfect for debugging, logging, and error reporting.

Basic Syntax 

<xsl:message>Hello from XSLT</xsl:message>
Enter fullscreen mode Exit fullscreen mode

With Dynamic Content (XSLT 2.0+) 

<xsl:message select="concat('Processing item: ', @id)" />
Enter fullscreen mode Exit fullscreen mode

With Termination

Stop the transformation immediately:

<xsl:message terminate="yes">Critical error encountered</xsl:message>
Enter fullscreen mode Exit fullscreen mode

Common Use Cases

1. Debug Logging 

<xsl:template match="book">
  <xsl:message select="'[DEBUG] Processing book: ' || title" />
  <!-- transformation logic -->
</xsl:template>
Enter fullscreen mode Exit fullscreen mode

2. Variable Inspection 

<xsl:variable name="total" select="sum(//price)" />
<xsl:message select="'Total price: ' || $total" />
Enter fullscreen mode Exit fullscreen mode

3. Conditional Warnings 

<xsl:if test="not(title)">
  <xsl:message>WARNING: Book missing title</xsl:message>
</xsl:if>
Enter fullscreen mode Exit fullscreen mode

4. Error Handling 

<xsl:choose>
  <xsl:when test="//item">
    <!-- process items -->
  </xsl:when>
  <xsl:otherwise>
    <xsl:message terminate="yes">ERROR: No items found</xsl:message>
  </xsl:otherwise>
</xsl:choose>
Enter fullscreen mode Exit fullscreen mode

Key Attributes

select (XSLT 2.0+)

Dynamically construct messages using XPath expressions:

<xsl:message select="'Found ' || count(//book) || ' books'" />
Enter fullscreen mode Exit fullscreen mode

Note: XSLT 1.0 doesn't support select, so use text content:

<xsl:message>
  <xsl:text>Found </xsl:text>
  <xsl:value-of select="count(//book)" />
  <xsl:text> books</xsl:text>
</xsl:message>
Enter fullscreen mode Exit fullscreen mode

terminate

Controls whether transformation should stop:

  • terminate="no" (default) — Continue transformation
  • terminate="yes" — Stop immediately and raise error 
<xsl:message terminate="yes">Fatal error: Invalid input</xsl:message>
Enter fullscreen mode Exit fullscreen mode

Where Messages Go

It depends on your XSLT processor:

.NET (XslCompiledTransform)

Messages trigger events that you must handle in code:

transform.XsltMessageEncountered += (sender, e) => {
    Console.WriteLine(e.Message);
};
Enter fullscreen mode Exit fullscreen mode

Without an event handler, messages are silently discarded.

Saxon

Messages output to stderr by default, or you can capture them:

transformer.setMessageListener((content, terminate, location) -> {
    System.err.println(content);
});
Enter fullscreen mode Exit fullscreen mode

Command-line Processors

Messages typically appear in the console/terminal output.

Best Practices

Use clear prefixes for different message types:

<xsl:message>[INFO] Starting transformation</xsl:message>
<xsl:message>[DEBUG] Current node: <xsl:value-of select="name()"/></xsl:message>
<xsl:message>[WARN] Missing optional field</xsl:message>
<xsl:message terminate="yes">[ERROR] Required field not found</xsl:message>
Enter fullscreen mode Exit fullscreen mode

Keep messages concise — They're for debugging, not documentation

Remove or comment out verbose debug messages before production

Use terminate="yes" for truly fatal errors only

Example: Complete Template with Logging 

<xsl:template match="order">
  <xsl:message select="'[INFO] Processing order ' || @id" />

  <xsl:variable name="itemCount" select="count(item)" />
  <xsl:message select="'[DEBUG] Order contains ' || $itemCount || ' items'" />

  <xsl:if test="$itemCount = 0">
    <xsl:message>[WARN] Order has no items</xsl:message>
  </xsl:if>

  <xsl:if test="not(@id)">
    <xsl:message terminate="yes">[ERROR] Order missing required ID</xsl:message>
  </xsl:if>

  <!-- transformation logic -->
  <order-summary>
    <xsl:copy-of select="@*" />
    <item-count><xsl:value-of select="$itemCount" /></item-count>
  </order-summary>
</xsl:template>
Enter fullscreen mode Exit fullscreen mode

Limitations

  • Manual instrumentation — Must add messages explicitly to your stylesheet
  • Text-only — Can't easily inspect complex node structures
  • Processor-specific handling — Different behavior across XSLT processors
  • No execution control — Can't pause or step through transformations
  • Limited context — Messages don't include automatic location/stack information

Despite these limitations, xsl:message remains the most portable way to add diagnostic output to XSLT transformations.

Learn More

Top comments (1)

Collapse
 
roshan_sharma_7deae5e0742 profile image
roshan sharma •

Clear and super useful explainer, this nails what xsl:message actually does and when to use it. Loved how you compared it to console.log() and broke down real use cases. Perfect quick reference for anyone debugging XSLT.