Background

Frequently BizTalk developers are faced with a requirement to perform some manipulation with the content of a message using the native XlangMessage. Developers have a number of alternative approaches available.

Overview

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 invocationAn 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 returned from a method and assigned to a message variable in an orchestration.[Source: MSDN article Messages Represented as XLANGMessage]

XLangMessage Class

Namespace: Microsoft.XLANGs.BaseTypes

Platforms:  Windows, Windows XP Professional, Windows Server

Assembly: Microsoft XLANG/s Base Types (in Microsoft.XLANGs.BaseTypes.dll)

For the examples below additional assemblies will need to be added from the BizTalk installation directory:

  • Microsoft.XLANGs.Engine.dll
  • Microsoft.XLANGs.BizTalk.Engine.dll

Common XLangMessage Functions inside Orchestration

Access The Context properties of an Incoming message inside a .Net Helper Class

Message Context Properties are system properties, which are being written on message by BizTalk Messaging Engine. These properties are used internally by BizTalk and its components for routing or other purposes. In general, changing these values set is not recommended, since it may affect the execution logic of the engine. However, there are a number of properties that you can change, see MSDN Message Context Properties.

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.XLANGs.BaseTypes;
using System.Xml;
using System.Web;
using Microsoft.XLANGs.Core;
using Microsoft.BizTalk.GlobalAssemblyCache;
namespace BizTalkXLangMessage
{
    [Serializable]
    public class BizTalkXLangMessage
    {
        public object GetContextPropoerty(XLANGMessage msg,Type property)
        {
            object obj;
            if (msg == null)
            {
                throw new ArgumentNullException("message");
            }
 
            obj = msg.GetPropertyValue(property);
            return obj;
         
        }

     }

}

Convert XMLDocument to XlangMessage

XlangMessage can be constructed with a .Net Helper class . In case you require to construct XlangMessage for an Orchestration with a XML document or type string. It can be very useful for dynamically constructing Multipart message  Inside BizTalk workflow. Sample Code is listed below:

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.XLANGs.BaseTypes;
using System.Xml;
using System.Web;
using Microsoft.XLANGs.Core;
using Microsoft.BizTalk.GlobalAssemblyCache;
 
namespace BizTalkXLangMessage
{
    [Serializable]
    public class BizTalkXLangMessage
    {
public XLANGMessage XmldocumentToXlangMsg(XmlDocument xmldoc)
        {
             
            xmldoc.LoadXml(@"<ns0:XlangRequestMsg xmlns:ns0='http://xlangorchestration.testschema/'><Name></Name><Type></Type><Value></Value></ns0:XlangRequestMsg>");
            Stream stream = new System.IO.MemoryStream();
            xmldoc.Save(stream);
            stream.Flush();//Adjust this if you want read your data
            stream.Position = 0;
 
            var customBTXMessage = new CustomBTXMessage("tempInput", Service.RootService.XlangStore.OwningContext);
            customBTXMessage.AddPart(string.Empty, "Body");
            customBTXMessage[0].LoadFrom(stream);
            var responseMessage = customBTXMessage.GetMessageWrapperForUserCode();
            return responseMessage;
        }

     }

}

This sample needs a context class being populated like below:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.XLANGs.Core;
using Microsoft.XLANGs.BaseTypes;
using Microsoft.BizTalk.XLANGs.BTXEngine;
 
namespace BizTalkXLangMessage
{
    [Serializable]
    public sealed class CustomBTXMessage : BTXMessage
    {
        public CustomBTXMessage(string messageName, Context context)
            : base(messageName, context)
        {
            context.RefMessage(this);
        }
    }
      
}

Add Message Part to Multipart Message and Get Message Part from Multipart Message

Multipart messages are created in BizTalk orchestrations, as opposed to being created as schemas. Multipart messages are a collection of message parts, with each part having a specific type. Message part types can be defined by an XSD schema or a .NET class. It can be used in various scenarios such as Aggregation patterns were we will be adding a part to an existing message dynamically.

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.XLANGs.BaseTypes;
using System.Xml;
using System.Web;
using Microsoft.XLANGs.Core;
using Microsoft.BizTalk.GlobalAssemblyCache;
 
 
namespace BizTalkXLangMessage
{
    [Serializable]
    public class BizTalkXLangMessage
    {
 
    public static void AddPart(XLANGMessage message, string name, object part)
    {
        message.AddPart(part, name);
    }
 
 
public static object GetPart(XLANGMessage message, string name, Type type)
 
    {
        XLANGPart part = message[name];
        return part.RetrieveAs(type);
    }
}

Examples for using Addpart and Getpart of MultiPartMessage in BizTalk:

BizTalkXLangMessage.Addpart(RequestMsg,"Requestpart","Addpartmessage");
 
OrchvarString = (System.String)BizTalkXLangMessage.GetPart(RequestMsg,"Requestpart",typeof(System.String));

XLangMessage To String conversion

This method has come in handy so much more than we ever thought it would. Its sole purpose is to take a BizTalk message and convert it to a string. One example of where we use it is when logging information from within an orchestration.

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.XLANGs.BaseTypes;
using System.Xml;
using System.Web;
using Microsoft.XLANGs.Core;
using Microsoft.BizTalk.GlobalAssemblyCache;
 
namespace BizTalkXLangMessage
{
    [Serializable]
    public class BizTalkXLangMessage
    {
 
        public string XlangMessageToString(XLANGMessage requestMessge )
        {
            XmlDocument xmlDoc = (XmlDocument)requestMessge[0].RetrieveAs(typeof(XmlDocument));
            return xmlDoc.OuterXml;
        }
}

Converting XlangMessage Part to XML document

Below code can be used to convert Part of Multipart message into XML Document

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.XLANGs.BaseTypes;
using System.Xml;
using System.Web;
using Microsoft.XLANGs.Core;
using Microsoft.BizTalk.GlobalAssemblyCache;
  
namespace BizTalkXLangMessage
{
    [Serializable]
    public class BizTalkXLangMessage
    {
    public static XDocument GetXmlDocumentfrmXLangPart(XLANGPart messagPart)
    {
        return XDocument.Load((Stream)messagPart.RetrieveAs(typeof(Stream)));
    }
}

See Also

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