Custom BizTalk Pipeline Assembler Component

• Download surce code - 128 KB

Introduction

As part of system integration, specially when dealing with non-XML communication (flat files), a conversion is needed. It is the pipelines that come into the picture and transform the data into something that BizTalk can understand – XML. Essentially, pipelines form a channel for the messages from the adapters to the message box where they are finally delivered.

Pipelines are divided into two parts:

1. Receive Pipeline: The receive pipeline is executed after the receive adapter. It takes up the chunk of raw data that comes from the external system, and works on it, performing tasks like validation of signatures, decryption, and transformation before disassembling it into zero or more BizTalk messages. The created messages are consumed individually by the BizTalk Server.

The receive pipeline consists of four stages – Decode, Disassemble, Validate, Resolve Party. These are executed in the same sequence as they appear below:

1. Decode: This stage would involve some pre-processing like verifying message signatures to ensure integrity, or decoding the S/MIME messages.
2. Disassembler: It is here that a message gets converted entirely into XML format so that the messaging engine can understand it. The input is, of course, a plain text or an XML stream that is passed from the Decode stage. It is processed into one or more messages that are always in XML format.
3. Validate: Typically, the validate component would check to see if the message is in the correct format or not.
4. Resolve Party: As MSDN explains it, "The Party Resolution pipeline component is used to map the user security ID and the certificate subject for the client to a BizTalk Server party".
2. Send Pipeline: It expects a complete well-formed XML message from the BizTalk engine, and then works on it to assemble it into a message that the external system can understand.

Complimenting the receive pipeline, this can again be a flat file. It can also be encrypted and digitally signed before sending it out on the wire.

The send pipeline consists of four stages:

1. Preassemble: As the message comes to the Send pipeline, this is the very first stage that gets executed. This is basically a place holder stage that can do any pre-processing of the message before it needs to be assembled. The stage can contain up to 255 components.
2. Assemble: Once the preassemble stage does its job, the assemble stage takes over to actually convert the message in a format that can be understood by the external system.
3. Encode: As the message is converted to the external format, it is time to do any additional processing required on the message so that the external system can decode it properly. The processing of this stage includes S/MIME encoding, custom encryption of the message, or digitally signing it to maintain its integrity, or any other processing that can be required to encode the message.

We will cover the implementation of a custom disassembler in this article.

Background

To start with this article, you should be familiar with the Microsoft BizTalk Server, the .NET Framework, and C#.

Using the code

Before we start, you have to get familiar with these three main interfaces:

• IBaseComponent: Defines the properties that provide the basic information about a component.
• IPersistPropertyBag: Works with IPropertyBag and IErrorlog to define an individual property-based persistence mechanism.
• IComponentUI: Defines methods that enable pipeline components to be used within the Pipeline Designer environment.
• IDisassemblerComponent: is responsible for providing the assembling functionality.

IBaseComponent: there are three properties that must be implemented, that will appear at design time in Visual Studio.

#region IBaseComponent Members

public string Description
{
    get { return "Testdisassembler"; }
}

public string Name
{
    get { return "Test disassembler"; }
}

public string Version
{
    get { return "1.0.0.0"; }
}

#endregion

IPersistPropertyBag: is responsible for getting the design time properties. If you need to have some properties be set during design time or during the deployment stage, you must add the loading and saving functionalities for those properties.

#region IPersistPropertyBag Members

public void GetClassID(out Guid classID)
{
    classID = new Guid("25984614-BCFD-4c47-82FC-4A2300B76438");
}

public void InitNew()
{
}

public void Load(IPropertyBag propertyBag, int errorLog)
{
    object val = ReadPropertyBag(propertyBag, "TextProperty");
    if (val != null)
        textProperty = (string)val;
}

public void Save(IPropertyBag propertyBag, bool clearDirty, 
                 bool saveAllProperties)
{
    object val = textProperty;
    propertyBag.Write("Namespace", ref val);
}

#endregion

IComponentUI: defines the methods that enable the pipeline components to be used within the Pipeline Designer environment.

#region IComponentUI Members

public IntPtr Icon
{
    get { return System.IntPtr.Zero; }
}

public System.Collections.IEnumerator Validate(object projectSystem)
{
    return null;
}

#endregion

Now, after understanding the three main interfaces, we can start implementing the components.

Assembler: you have to implement the IAssemblerComponent interface for this.

public void AddDocument(IPipelineContext pContext, IBaseMessage pInMsg)
{
    System.Diagnostics.Trace.WriteLine("Pipeline Assemble Stage Enter");

    msgPart = pInMsg.BodyPart;
    Stream originalStream = pInMsg.BodyPart.GetOriginalDataStream();
    try
    {
        if (msgPart != null)
        {
            if (originalStream != null)
            {
                string result = string.Empty;
    
                // Do Assembling and return a xml string
    
                byte[] arrByte = ConvertToByteArray(result);
                originalStream = (new MemoryStream(arrByte));
            }
        }
    }
    catch (Exception)
    {
        System.Diagnostics.Trace.WriteLine("Pipeline Assemble Stage Exception");
        throw;
    }
    
    originalStream.Seek(0, SeekOrigin.Begin);
    msgPart.Data = originalStream;
    
    IBaseMessage outMsg = pInMsg;
    outMsg.BodyPart.Data = originalStream;
    
    // promote MessageType and Schema SchemaStrongName
    // in order to the Biztalk to have a unique key
    // for evaluating subscription
    //As an example for Namespace#Root= http://TestCustomPipeline.Schema1#roottagName
    //As an example for SchemaAssembly full name=
    //TestCustomPipeline.Schema1, TestCustomPipeline, Version=1.0.0.0,
    //Culture=neutral, PublicKeyToken=f38e6d751bb874eb

    outMsg.Context.Promote("MessageType", 
      "http://schemas.microsoft.com/BizTalk/2003/system-properties",
      "Namespace#Root");
    outMsg.Context.Promote("SchemaStrongName", 
      "http://schemas.microsoft.com/BizTalk/2003/system-properties",
      "SchemaAssebly full name");

    qOutputMsgs.Enqueue(outMsg);
}

public IBaseMessage Assemble(IPipelineContext pContext)
{
    if (qOutputMsgs.Count > 0)
    {
        IBaseMessage msg = (IBaseMessage)qOutputMsgs.Dequeue();
        return msg;
    }
    else
        return null;
}

Usage in Visual Studio

Copy the DLL and paste it into (Windows installation directory):\Program Files\Microsoft BizTalk Server 2006\Pipeline Components. Insert the DLL into the GAC, open Visual Studio, right click on the Toolbox, click Select Items -> BizTalk Pipeline Components -> select your DLL -> OK. The assembler component will be added to the toolbox. Drag and drop it into the assemble stage and have fun!!

History

• Version 1.0.