A common BizTalk requirement is to manipulate message content. Amongst the candidates for message manipulation are:

  • Distinguished fields
  • Property promotion 
  • Xpath expression

This is not an exhaustive list.
In this article we are going to discussusing the Xpathreader class found in the Microsoft.BizTalk.XPathReader.dll assembly.


Message manipulation can be done inside a pipeline, transformation or orchestration. With an orchestration a message is represented as an XLANGMessage object. According to MSDN:

"An XLANGMessage object represents a message instance declared with an XLANG service. This object is obtained by passing a reference to a message as a parameter in a method invocation. An orchestration message variable may be passed to a user component and received as an XLANGMessage object. The XLANGMessage object allows accessing the parts and accessing message properties.The user may "hold on" to an XLANGMessage and thereby extend its lifetime beyond the declared scope. Subsequently, an XLANGMessage may be retuned from a method and assigned to a message variable in an orchestration." [MSDN]

XLangMessage Class

Namespace: Microsoft.XLANGs.BaseTypes
Platforms:  Windows, Windows XP Professional, Windows Server
Assembly: Microsoft XLANG/s Base Types (in Microsoft.XLANGs.BaseTypes.dll)

Using XPathReader and XPathCollection to extract a value from an XLANGMessage

We can use an instance of the XPathReader class provided by the Microsoft.BizTalk.XPathReader.dll assembly to extract the message. Below is the illustration of how to use the same :

using System;
using Microsoft.XLANGs.BaseTypes;
using System.IO;
using Microsoft.BizTalk.XPath;
using System.Xml;
namespace XlangHelper
    public class XlangHelperMethods
        public static string SelectSingleNode(XLANGMessage message, string xPath)
                if (message == null || string.IsNullOrEmpty(xPath))
                    return string.Empty;
                using (XmlReader reader = (XmlReader)message[0].RetrieveAs(typeof(XmlReader)))
                    XPathCollection xPathCollection = new XPathCollection();
                    XPathReader xPathReader = new XPathReader(reader, xPathCollection);
                    while (xPathReader.ReadUntilMatch())
                        if (xPathReader.Match(0))
                            return xPathReader.ReadString();
            catch (Exception ex)
                throw (ex);
            return string.Empty;

We need to add this dll to the GAC and reference it in our BizTalk solution to use it.

Calling in BizTalk Orchestration

Below code snippet shows how we can read the content of message using the Expression shape by passing the message and namespace as arguments to the helper class :

ReadValue = XlangHelper.XlangHelperMethods.SelectSingleNode(mSg_In,"/*[local-name()='Company' and namespace-uri()='http://SampProj1.Input']/*[local-name()='Name' and namespace-uri()='']");

Where ReadValue is of type System.String.

Advantages over other alternatives

  • "If you do need to promote properties, promote only those properties that are used for message routing, filters, and message correlation. The promotion of each property requires the disassembler component (XML, Flat, custom) to recognize the document type and to retrieve data from the message using the XPath expression from the relative annotation contained in the XSD that defines the document type. In addition, each property promotion causes a separate call of the bts_InsertProperty stored procedure when the Message Agent publishes the message to the MessageBox database." [MSDN]
  • "The XPath Expressions can be very long, especially when the element in question is very deep in the document schema. So, the more distinguished fields, the larger the context size. This in turn adversely affects the overall performance." [MSDN]
  • "Eliminate unnecessary distinguished fields. The distinguished fields are written context properties and they can easily occupy significant space as their name is equal to the XPath expression that is used to retrieve data." [MSDN]


See Also

Another important place to find  an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.