Custom BizTalk Pipeline Decoding Component

• Download Custom Libraries - 130.78 KB

Introduction

As part of system integration, especially 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.

Pipeline is 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 the signatures, decryption, 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 the message gets converted entirely into the 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

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 the following stages:

1. Preassemble Stage: 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 Decoder.

Background

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

Using the Code

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

• IBaseComponent: Defines properties that provide basic information about the 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.

IComponent is responsible for providing any execution functionality.

IBaseComponent

Three properties must be implemented that will appear in the design time in Visual Studio.

#region IBaseComponent Members
  public string Description
 {
     get { return "TestDecoder"; }
 }
  public string Name
 {
    get { return "Test Decoder"; }
 }
  public string Version
 {
    get { return "1.0.0.0"; }
 }
#endregion

IPersistPropertyBag

This is responsible for getting the design time properties. If you need to have some properties to be set during the design time or during the deployment stage, you must add the loading and saving 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

This defines methods that enable 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 main three interfaces, we can start implementing the components.

Decoder

You have to implement IComponent interface:

 public IBaseMessage Execute(IPipelineContext pContext, IBaseMessage pInMsg)
 {
     msgPart = pInMsg.BodyPart;
     Stream originalStream = pInMsg.BodyPart.GetOriginalDataStream();
     try
     {
         if (msgPart != null)
         {
            if (originalStream != null)
            {
                byte[] input = new byte[originalStream.Length];
                originalStream.Read(input, 0, (Int32)originalStream.Length);
                  // do Decoding
                 string result = string.Empty;
                  byte[] arrByte = ConvertToByteArray(result);
                 originalStream = (new MemoryStream(arrByte));
             }
         }
    }
    catch (Exception)
    {
        throw;
    }
    originalStream.Seek(0, SeekOrigin.Begin);
    msgPart.Data = originalStream;
     IBaseMessage outMsg = pInMsg;
    outMsg.BodyPart.Data = originalStream;
     return outMsg;
}

Usage in Visual Studio

Copy the DLL and paste 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 decoding component will be added to the toolbox drag and drop in the Decoding stage. HAVE FUN !!

History

• 6^th April, 2009: Version 1.0