Using Pipeline Interfaces


A pipeline component is a .NET or COM component that implements a set of predefined interfaces for interaction with the BizTalk Messaging Engine. Depending on the functionality of the component, different interfaces must be implemented. This topic discusses these interfaces and some of their methods.

System_CAPS_ICON_warning.jpg Warning

If you are building a custom pipeline component using COM, you must configure your component to use the Multi-Threaded Apartment (MTA) model. If you do not, invocation of your component will fail with an E_NOINTERFACE error.

All pipeline components can use IPipelineContext methods to access all document processing-specific interfaces. The IPipelineContext interface provides the following functionalities:

  • Allows components to retrieve the ambient pipeline and stage settings.

  • Allows components to retrieve message and message factories. With these factories, components can create various objects required for the execution of the component.

  • Allows components to retrieve the document specifications. A document specification is an XSD schema plus additional annotations.

All pipeline components need to implement this interface to provide basic information about the component.

All pipeline components except assemblers and disassemblers implement this interface to get messages from the BizTalk Server engine for processing and to pass processed messages back to the engine.

Execute. Method called by the engine to pass the input message to the component and retrieve the processed message from the component.

Pipeline components need to implement IPersistPropertyBag to receive its configuration information. This interface and IPropertyBag are the standard interfaces. For more information about these interfaces, refer to the Microsoft .NET Framework Software Development Kit (SDK) documentation.

A disassembling component is a pipeline component that receives one message on input and produces zero or more messages on output. Disassembling components are used to split interchanges of messages into individual documents. A disassembler component must implement the methods of the IDisassemblerComponent interface to get messages from BizTalk Server for processing and to pass disassembled documents back to BizTalk Server.

DisassemblePerforms the disassembling of the incoming document pInMsg.
GetNextGets the next message from the message set that resulted from disassembler execution. Returns NULL if there are no more messages.

If you are writing a disassembler component that will support Recoverable Interchange Processing, you must do the following:

  1. Make the input streams seekable by wrapping them in a VirtualStream().

  2. In GetNext(), have logic to determine when a message is bad. If a message is bad, set BTS.MessageDestination = "SuspendQueue" and return the message in GetNext().

  3. If the message is good, set BTS.SuspendMessageOnRoutingFailure = True and return the message in GetNext().

An assembling component is a pipeline component that receives several messages on input and produces one message on output. Assembling components are used to collect individual documents into the message interchange batch.

System_CAPS_ICON_note.jpg Note

In this release of BizTalk Server, assembling functionality is not used, so BizTalk Server always passes one document to the component input.

An assembler component implements the IAssemblerComponent methods that are called by the BizTalk Server engine at run time.

AddDocumentAdds the document pInMsg to the list of messages that will be included in the interchange.
AssembleBuilds the interchange from the messages that were added by the previous method. Returns a pointer to the assembled message.

Any pipeline component (general, assembling, or disassembling) can implement IProbeMessage if it requires message probing functionality. A probing component is used in the pipeline stages that have FirstMatch execution mode. In such stages, BizTalk Server gives the message to the component, and the Probe method examines the beginning of the message to determine if the component recognizes the format of the message.

ProbeThis method takes pInMsg message, and returns True if the format is recognized or False otherwise.

This is a helper interface for accessing document schemas from managed and unmanaged code.

This is a helper interface for accessing document schemas from managed and unmanaged code.

Pipeline components can use methods of the IDocumentSpec interface to perform document-specific actions, such as moving content properties to context and back, accessing document schemas, and so on.

DocTypeReturns the type of the current document.
DocSpecNameReturns the specification name of the current document.
GetSchemaCollectionReturns the list of document schemas for the current document.
GetBodyPathReturns the XPath to the node in the document where the body part begins.
GetDistinguishedPropertyAnnotationEnumeratorReturns a dictionary enumerator of all distinguished field property annotations.
GetPropertyAnnotationEnumeratorReturns an enumerator of all property annotations.

Pipeline components must implement this interface to be used within the Pipeline Designer environment.

IconProvides the icon that is associated with this component.
ValidatePipeline Designer calls this method before pipeline compilation to verify that all the configuration properties are set correctly.

The Icon property returns an IntPtr. The following C# example shows how to return an IntPtr.

static   ResourceManager resManager = new ResourceManager("ResourceManager", Assembly.GetExecutingAssembly());  
public IntPtr Icon  
      return ((Bitmap)resManager.GetObject("MyIcon")).GetHicon();  

For more information about IComponentUI, see IComponentUI Interface (COM).

Developing Custom Pipeline Components
CustomComponent (BizTalk Server Sample)

Community Additions