BizTalk 2009 : Custom Components - Key BizTalk API Objects

Before starting a new project, the most important thing is to understand what type of component you need to build. This will depend on the following:

• Whether the component is executed in a receive pipeline, a send pipeline, or both

• What type of work needs to be done

Too often developers simply "default" to writing what they know instead of what they should. Having a thorough understanding of how pipeline components work, along with a proper design for what work should take place at which pipeline stage, will help you build more reusable and reliable pipeline components.

1. Component Categories

As you will soon see, the pipeline component development API is quite heavily based on COM Interop. Most of the specifics of how components are defined are based on what COM category they are tagged with along with what interfaces they implement. Component categories, listed here, exist for each of the different types of pipeline components:

CATID_Any
CATID_AssemblingSerializer
CATID_Decoder
CATID_DisassemblingParser
CATID_Encoder
CATID_Parser
CATID_PartyResolver
CATID_PipelineComponent[]
CATID_Receiver
CATID_Serializer
CATID_Streamer
CATID_Transmitter
CATID_Validate

These are defined by tagged attributes on the pipeline component's class, as shown in the following code:

Imports System
Imports System.ComponentModel
Imports Microsoft.BizTalk.Message.Interop
Imports Microsoft.BizTalk.Component.Interop
Imports Microsoft.BizTalk.Component
Imports Microsoft.BizTalk.Messaging

Namespace ABC.BizTalk.FullFillment.PipelineComponents

    <ComponentCategory(CategoryTypes.CATID_PipelineComponent), _
     System.Runtime.InteropServices.Guid("4f1c7d50-e66f-451b-8e94-2f8d599cd013"), _
     ComponentCategory(CategoryTypes.CATID_Encoder)> _
   Public Class MyFirstEncodingComponent

					  

^[] Types including interfaces, classes, and assemblies get a unique GUID even if you don't assign one explicitly. However, they can change between builds/assembly versions, so in this case it's best to explicitly assign them so you don't break binary compatibility between builds/versions.

2. Component Interfaces

The specific interfaces a pipeline component implements are what differentiate that pipeline component from another. BizTalk Server ships with a number of assemblies that define application interfaces for custom components to implement. Once a component has an interface implementation, it can be called by the BizTalk runtime. The basic interfaces are defined in the following list. All components and component categories live in the Microsoft.BizTalk.Component.Interop namespace.

• IBaseComponent: Defines properties that provide basic information about the component.

  Public properties:

  • Description: Gets the component description

  • Name: Gets the component name

  • Version: Gets the component version

• IComponent: Defines the methods used by all pipeline components except Assemblers and Disassemblers.

  Public method:

  • Execute: Executes a pipeline component to process the input message and get the resulting messages

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

  Public property:

  • Icon: Gets the icon that is associated with this component

  Public method:

  • Validate: Verifies that all of the configuration properties are set correctly

3. Key BizTalk API Objects

All pipeline components, regardless of what they do, will use the interfaces described in the following subsections. Likewise, most of the pipeline component interfaces defined previously accept these interfaces as arguments. That being said, it is important to understand these interfaces first before proceeding. The following is based on material from the BizTalk Server documentation on MSDN.

1. IPipelineContext^[]

^[] http://msdn.microsoft.com/en-us/library/microsoft.biztalk.component.interop.ipipelinecontext_members.aspx

IPipelineContext is the main interface that defines the operations and properties for the pipeline instance. Tables 1 and 2 show the interface's public properties and methods. The key method here is the GetMessageFactory method. This method will return a message factory for the pipeline that can be used to create new messages using the CreateMessage method.

The GetMessageFactory method is the main way to create new messages from within a pipeline component. Also note that you will need to call IPipelineContext. GetMessageFactory.CreateMessagePart to create the message part for the messageA message is simply a construct that contains zero to many message parts. Once you create the message part, you can assign it to the IBaseMessage object through the AddPart method.

3.2. IBaseMessage^[]

^[] http://msdn.microsoft.com/en-us/library/microsoft.biztalk.message.interop.ibasemessage_members.aspx

IBaseMessage is the base interface that defines a BizTalk Server message. Tables 3 and 4 show the public properties and methods. Note that messages, created using the IPipelineContext.GetMessageFactory.CreateMessage method, will implement this interface. This will still need an IBaseMessagePart to be assigned through the AddPart method for any data to be included with the message.

3.3. IBaseMessagePart^[]

^[] http://msdn.microsoft.com/en-us/library/microsoft.biztalk.message.interop.ibasemessagepart_members.aspx

IBaseMessagePart is the interface that defines a BizTalk message part. Tables 5 and 6 show its public properties and methods. The message part is assigned to an IBaseMessage through the AddPart method. Note the Data property. This is the property used to assign a value to the message part. The Data property accepts and returns only streams. This is incredibly useful, because it allows any stream to be assigned to the message part. This includes XMLReader streams, MemoryStreams, and raw BinaryStreams.

Another rarely used item is the PartProperties property. This is essentially a property bag that can be used to store information and metadata about the part. In reality, the PartID, Charset, and ContentType are actually contained in the PartProperties IBasePropertyBag object.

3.4. IBaseMessageContext^[]

^[] http://msdn.microsoft.com/en-us/library/microsoft.biztalk.message.interop.ibasemessagecontext_members.aspx

IBaseMessageContext is the interface used to interact with and manipulate the object context accessible through the IBaseMessage.Context property. Tables 7 and 8 show the public properties and methods. The main items of interest here are the Promote, Read, and Write methods. Properties that exist in the context can never have a Null value. A Null value means that the property does not exist. Here's an example:

• Attempting to set (or promote) a property value to Null deletes the property and returns the COM result S_OK.

• Attempting to read a nonexistent property returns Null.

3.5. PipelineUtil

PipelineUtil is a helper class that exposes the three methods shown in Table 9. These methods are invaluable when you need to create a new message.