BizTalk Working With XPath – XPath 1.0 Function Library Quick Reference

Whether you are extracting a value in an Orchestration Expression shape or building a complex Custom XSLT map, XPath is the language of choice. However, remembering every function and its syntax can be challenging.

You can use XML Path Language (XPath) functions to refine XPath queries and enhance the programming power and flexibility of XPath.

This guide serves as your quick reference for the XPath 1.0 Function Library, the version supported by Microsoft BizTalk Server. The functions are divided into the following groups: Node Set, String, Boolean, and Number.

Node Set Functions

Node-set functions take a node-set argument. They return a node-set, or information about a particular node within a node-set. These functions are critical for identifying and counting elements within your XML messages.

Function: [number] last() – Returns a number equal to the context size of the expression evaluation context, that is, returns the index number of the last node in the set.

• Example: //book[last()] – Result: Selects the last book element
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256083(v=vs.100)

Function: [number] position() – Returns the position, or index number, of the node, relative to all the selected nodes in the node list.

• Example: //book[position()<=3] – Result: Selects the first three book elements
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256233(v=vs.100)

Function: [number] count(node-set) – Returns the number of nodes in the node-set argument, that is, returns the number of nodes in a set (perfect for loop counting).

• Example: <xsl:value-of select=”count(//book)”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256103(v=vs.100)

Function: [node-set] id(object) – Selects elements by their unique ID.

• Example: <xsl:value-of select=”id(‘0-672-32598-5’)”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256148(v=vs.100)

Function: [string] local-name(node-set?) – Returns the local part of the expanded name of the node in the node-set argument that is first in document order, that is, it returns the name of the node without the namespace prefix.

• Example: <xsl:value-of select=”local-name()”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256070(v=vs.100)

Function: [string] namespace-uri(node-set?) – Returns the namespace Uniform Resource Identifier (URI) of the expanded name of the node in the node-set argument that is first in document order.

• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256466(v=vs.100)

Function: [string] name(node-set?) – Returns a string containing a QName representing the expanded name of the node in the node-set argument that is first in document order.

• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256078(v=vs.100)

String Functions

String functions are used to evaluate, format, and manipulate string arguments, or to convert an object to a string. Since most EDI and XML data is string-based, these are your most frequent tools.

Function: [string] string(object?) – Converts an object to a string.

• Example: string(/book/artist/text())
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256133(v=vs.100)

Function: [string] concat(string, string, string*) – Returns the concatenation of the arguments.

• Example: concat(/book/title, ” – “, /book/category)
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256123(v=vs.100)

Function: [boolean] starts-with(string, string) – Returns true if the first argument string starts with the second argument string; otherwise returns false.

• Example: <xsl:if test=”starts-with(/book/title, ‘W’)”>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256174(v=vs.100)

Function: [boolean] contains(string, string) – Checks whether the first argument string contains the second argument string. Returns true if the first string contains the second.

• Example: <xsl:if test=”contains(/book/title, ‘BizTalk’)”>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256195(v=vs.100)

Function: [string] substring-before(string, string) – Returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string, or the empty string if the first argument string does not contain the second argument string.

• Example: <xsl:value-of select=”substring-before(/book/date, “/”)”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256071(v=vs.100)

Function: [string] substring-after(string, string) – Returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string, or the empty string if the first argument string does not contain the second argument string.

• Example: <xsl:value-of select=”substring-after(/book/date, “/”)”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256455(v=vs.100)

Function: [string] substring(string, number, number?) – Returns the substring of the first argument starting at the position specified in the second argument and the length specified in the third argument.

• Example: substring(“12345”, 2, 3) returns “234”
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256054(v=vs.100)

Function: [number] string-length(string?) – Returns the number of characters in the string.

• Example: string-length(“BizTalk”) returns 7
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256171(v=vs.100)

Function: [string] normalize-space(string?) – Returns the argument string with the leading, trailing, and repeating white spaces stripped.

• Example: normalize-space(” working with XPath “) returns “working with XPath”
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256063(v=vs.100)

Function: [string] translate(string, string, string) – Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string.

• Example: translate(’12:30′,’30’,’45’) Result: ’12:45′
• Example: translate(’12:30′,’03’,’54’) Result: ’12:45′
• Example: translate(’12:30′,’0123′,’abcd’) Result: ‘bc:da’
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256119(v=vs.100)

Boolean Functions

The XML Path Language (XPath) syntax supports Boolean functions that return strings or numbers, and can be used with comparison operators in filter patterns.

Function: [boolean] boolean(object) – Converts the argument to a Boolean.

• Example: boolean(NaN) Result false
• Example: boolean(‘hello’) Result true
• Example: boolean(”) Result false
• Example: boolean(//book) Result false
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256159(v=vs.100)

Function: [boolean] not(object) – Returns true if the argument is false; otherwise false.

• Example: <xsl:for-each select=”//book[not(price > 10)]”>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256458(v=vs.100)

Function: [boolean] true() – Returns true.

• Example: true() Result: true
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256486(v=vs.100)

Function: [boolean] false() – Returns false.

• Example: <xsl:value-of select=”false()”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256226(v=vs.100)

Function: [boolean] lang(string) – Returns true if the xml:lang attribute of the context node is the same as a sublanguage of the language specified by the argument string.

• Example: lang(“en”) is true for <p xml:lang=”en”>…</p>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256192(v=vs.100)

Number Functions

The XML Path Language (XPath) syntax supports Number functions that return strings or numbers and can be used with comparison operators in filter patterns.

Function: [number] number(object?) – Converts the argument to a number.

• Example: <xsl:value-of select=”number(/book/id)”/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256211(v=vs.100)

Function: [number] sum(node-set) – Returns the sum of all nodes in the node-set. Each node is first converted to a number value before summing.

• Example: <xsl:value-of select=’sum(//book/price)’/>
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256160(v=vs.100)

Function: [number] floor(number) – Returns the largest integer that is not greater than the argument.

• Example: <xsl:value-of select=’floor(3.5)’/> Result: 3
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256464(v=vs.100)

Function: [number] ceiling(number) – Returns the smallest integer that is not less than the argument.

• Example: <xsl:value-of select=’ceiling(3.5)’/> Result: 4
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256087(v=vs.100)

Function: [number] round(number) – Returns an integer closest in value to the argument.

• Example: <xsl:value-of select=’round(2.6)’/> Result 3
• Example: <xsl:value-of select=’round(2.4)’/> Result 2
• Ref: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms256213(v=vs.100)

Pro-Tip: Using XPath in Orchestrations

In a BizTalk Orchestration, you can use these functions like this:

CountVariable = xpath(MyMessage, "count(//*[local-name()='Item'])");

XPath 1.0 might be an older standard, but it remains the reliable foundation for data movement in BizTalk. Keep this library handy to avoid writing unnecessary C# helper classes for simple XML logic.

Hope you find this helpful! If you liked the content or found it useful and would like to support me in writing more, consider buying (or helping to buy) a Star Wars Lego set for my son. 

Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community. View all posts by Sandro Pereira