Building a BizTalk Pipeline Component

This article describes how a BizTalk Pipeline Component is built...

BizTalk pipelines are used to translate messages to a form, so that BizTalk can work with. This is in the most cases XML. So when for example a flatfile is received by BizTalk, the pipeline?s task is to transform the flatfile to a XML message (with the same structure like the incoming file, but at least valid XML). Inside a pipeline there are several stages which accomplish different tasks to transform a message. In these stages there are pipeline components, which are the basic building blocks for a pipeline. They contain the functionality for decoding and encoding messaged, parsing flatfiles and building XML out of it, validating XML messages and so on.

In most of the cases the default pipeline components do a great job and the BizTalk developer just needs to arrange the default stuff in his pipeline designer, but there are some messages where pre- or postprocessing is needed ? like removing invalid characters for example. This is when a BizTalk developer should consider to create an own pipeline component.

As sample component for this demo a pipeline component is created which removes carriage return and line feed characters (CRLF)  from an incoming file.

To be able to create own BizTalk pipeline components, one has to install the Pipeline Component Wizard, which is available at http://www.codeplex.com/btsplcw. Ok, to be honest, it is not necessary to have that tool, but it extremely simplifies development. This is a Visual Studio Addin, which creates automatically all the framework-code for the component.

When a new ?BizTalk Server Pipeline Component? project is opened in Visual Studio, the ?Pipeline Component Wizard? shows up, which guides one through the creation of the framework code.

 

The first Stepp is to set a classname and a namespace  fort he component. Furthermore it has to know, if a receive or send pipeline component is created and in which stage the component should be used.

 

The sample component uses the following settings:

Pipeline component classname: EdiRemoveCRLFDecoder
Component namespace: MyNamespace
Pipeline type: Receive
Component type: Decoder
Language: C#

The next step is to specify the component?s name, description and version number. This information will be visible to the BizTalk developer in the Visual Studio pipeline designer.

 

The sample component will be called EdiRemoveCRLFDecoder and has the version number 1.0.

Pipeline components can have properties which can either be set in Visual Studio while building the BizTalk pipeline or in the BizTalk Administration console during the configuration of a Receive Location or a Send Port.

So the next step in the wizard is to specify the component?s properties (name and data type).

 

The sample component requires a regular expression (as string). The matches of the regular expression will be replaced by an empty string. So one property called CrLfRegEx (string) is added.

Then the wizard can be finished and one gets the automatically generated template for the pipeline component project.

Like every other assembly which is used in BizTalk, the new pipeline component should be strong named, so that it can be registered in the GAC. The strong name can be set in the projects properties on the Signing tab.

 

Now that the project was correctly built by the wizard and the assembly was signed, the only task which remains is to create the logic of the component. The wizard created an empty Execute() method, and main task of writing the pipeline component is to implement this method.

 

This is the code for the Execute() method:

Stream inStream = inmsg.BodyPart.Data;
MemoryStream outStream = new MemoryStream();
StreamReader reader = new StreamReader(inmsg.BodyPart.Data);
string messageBody = reader.ReadToEnd();
Regex crlf = new Regex(_CrLfRegEx);
//Regex crlf = new Regex(@"\r\n");
messageBody = crlf.Replace(messageBody, "");
byte[] firstString = System.Text.Encoding.UTF8.GetBytes(messageBody);
outStream.Write(firstString, 0, firstString.Length);
outStream.Seek(0, SeekOrigin.Begin);
inmsg.BodyPart.Data = outStream;
pc.ResourceTracker.AddResource(outStream);
return inmsg;

The incoming data which was recieved by BizTalk is passed to the Execute() method as Stream in inmsg.BodyPart.Data. A StreamReader reads the bytes to a string where the Regular Expressions can deal with and replace all matches agains empty strings.

Then the string is converted back to a byte array using UTF8 encoding. This byte array is written to the outStream object and the current position in the outStream is set back to 0 (this is quite important!). The outStream object is set as inmsg.BodyPart.Data. The inmsg is then returned by Execute().