IT tutorials
Applications Server

BizTalk 2009 : Custom Components - Key BizTalk API Objects

10/4/2011 4:49:30 PM
- How To Install Windows Server 2012 On VirtualBox
- How To Bypass Torrent Connection Blocking By Your ISP
- How To Install Actual Facebook App On Kindle Fire
It is critical to understand that each of the different types of pipeline components is designed to do a specific task. Most custom pipelines that we have seen generally include only one custom pipeline component inside a custom pipeline and try to perform all tasks within that one class. Often this becomes problematic and leads to an overly complex class. When starting development, the goal should be to write many small generic components instead of a small number of specialized ones. Pipeline components should be designed to be reused. Additionally, if it makes sense, the components should also accept multiple schema types and allow the user to choose the inbound/outbound schemas. Too often developers will hard-code the schema into the component and assume that the inbound messages will always be of a certain type. The component should, first, be flexible enough to probe the incoming schema and determine that it can handle the document and should, second, provide a user interface for selecting the desired schema in the Pipeline Designer.

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:


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

Note that it is possible for a component to have more than one category type if it has the proper interface implementation. Also note that the component explicitly defines a GUID for COM Interop.[] This can be done by generating a new GUID—using, for example, the VS .NET GUID Generation tool—and adding it here as an attribute of the class.

[] 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[]


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.

Table 1. IPipelineContext Public Properties
ComponentIndexGets the index of the current component in the stage.
PipelineIDGets the ID of the pipeline with which this pipeline context associates.
PipelineNameGets the name of the pipeline.
ResourceTrackerGets the IResourceTracker object associated with the pipeline context. This object can be used to track and dispose non-CLR resources.
StageIDGets the ID of the current stage in the pipeline.
StageIndexGets the index of the pipeline stage where the current component is located.

Table 2. IPipelineContext Public Methods
GetDocumentSpecByNameGets an IDocumentSpec object for the specified document name
GetDocumentSpecByTypeGets an IDocumentSpec object for the specified document type
GetGroupSigningCertificateGets the signing certificate for the group
GetMessageFactoryGet access to the helper interface to work with BizTalk Server message objects

3.2. IBaseMessage[]


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.

Table 3. IBaseMessage Public Properties
BodyPartGets the body part, or main part, of the message
BodyPartNameGets the name of the body part, or main part, of the message
ContextGets or sets the message context
IsMutableGets a value indicating whether the message can be changed by components during processing
MessageIDGets the unique message ID for the message
PartCountGets the total number of parts in the message

Table 4. IBaseMessage Public Methods
AddPartAdds a part to the message.
GetErrorInfoGets the exception that caused the error.
GetPartAccesses the message part. This is indexed by PartName.
GetPartByIndexRetrieves a part and its name by supplying the part index.
GetSizeGets the size of the message.
RemovePartRemoves a part from the message.
SetErrorInfoSets the error information.

3.3. IBaseMessagePart[]


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.

Table 5. IBaseMessagePart Public Properties
CharsetGets or sets the character set property for the part
ContentTypeGets or sets the content type property for the part
DataGets or sets the part data
PartIDGets the part with a unique ID
PartPropertiesGets or sets one or more properties that describe the part data or contain custom information about the part

Table 6. IBaseMessagePart Public Methods
GetOriginalDataStreamRetrieves the original uncloned version of the part data stream
GetSizeRetrieves the size of the part

3.4. IBaseMessageContext[]


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.

Table 7. IBaseMessageContext Public Property
CountPropertiesGets the number of properties in the message context

Table 8. IBaseMessageContext Public Methods
AddPredicateAdds a message predicate to the message
GetPropertyTypeGets the type of the property
IsMutableIndicates whether the message context can be changed by components during processing
IsPromotedEnables the component to determine whether a property has already been promoted in the message context
PromotePromotes a property into the message context
ReadGets a property value from the message context by the name-namespace pair
ReadAtGets a property from the message context by index
WriteWrites a property into the message context

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.

Table 9. PipelineUtil Public Methods
CloneMessageContextCreates a clone of the message context for a given message. This is useful for copying the message context of one message to another.
CopyPropertyBagCreates a clone of the property bag for a given message. This is useful for copying the property bag of one message to another.
ValidatePropertyValueChecks that the object is a valid property value.

This class is unsupported and is part of the BizTalk product infrastructure. If you run into trouble using it, Microsoft Product Support may not support you. However, it is common knowledge that it exists and makes pipeline component development much easier.

- Using BizTalk Framework 2.0 Reliable Messaging
- Performing a typical Exchange Server 2010 install
- Installing the Exchange Server 2010 prerequisites
- System Center Configuration Manager 2007 : Configuration Manager Technology and Terminology (part 4)
- System Center Configuration Manager 2007 : Configuration Manager Technology and Terminology (part 3)
- System Center Configuration Manager 2007 : Configuration Manager Technology and Terminology (part 2) - Inventory & Configuration Manager Console
- System Center Configuration Manager 2007 : Configuration Manager Technology and Terminology (part 1)
- System Center Configuration Manager 2007 : The History of Configuration Manager
- Upgrading and Configuring SharePoint 2010 : Upgrading MOSS 2007 to SharePoint 2010
- Upgrading and Configuring SharePoint 2010 : Checking current installation upgradeability
Top 10
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 2) - Wireframes,Legends
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 1) - Swimlanes
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Formatting and sizing lists
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Adding shapes to lists
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Sizing containers
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 3) - The Other Properties of a Control
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 2) - The Data Properties of a Control
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 1) - The Format Properties of a Control
- Microsoft Access 2010 : Form Properties and Why Should You Use Them - Working with the Properties Window
- Microsoft Visio 2013 : Using the Organization Chart Wizard with new data
programming4us programming4us
Popular tags
Video Tutorail Microsoft Access Microsoft Excel Microsoft OneNote Microsoft PowerPoint Microsoft Project Microsoft Visio Microsoft Word Active Directory Biztalk Exchange Server Microsoft LynC Server Microsoft Dynamic Sharepoint Sql Server Windows Server 2008 Windows Server 2012 Windows 7 Windows 8 Adobe Indesign Adobe Flash Professional Dreamweaver Adobe Illustrator Adobe After Effects Adobe Photoshop Adobe Fireworks Adobe Flash Catalyst Corel Painter X CorelDRAW X5 CorelDraw 10 QuarkXPress 8 windows Phone 7 windows Phone 8 BlackBerry Android Ipad Iphone iOS