BizTalk 2006 : Custom Components (part 2) - Key BizTalk API Objects

Key BizTalk API Objects

All pipeline components, regardless of what they do, will use the interfaces described in thefollowing 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.

IPipelineContext

IPipelineContext is the main interface that defines the operations and properties for thepipeline instance. The MSDN documentation from Microsoft provides good examples for how these interfaces are to be used. 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 withina pipeline component. Also note that you will need to call IPipelineContext. GetMessageFactory.CreateMessagePart to create the message part for the message. A 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.

IBaseMessage

IBaseMessage is the base interface that defines a BizTalk Server message. Tables 3 and Table 4 show the public properties and methods. The MSDN documentation from Microsoft provides good examples for how these interfaces are to be used. 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.

IBaseMessagePart

IBaseMessagePart is the interface that defines a BizTalk message part. Table 5 and Table 6 show its public properties and methods. The message part is assigned to an IBaseMessage through the AddPart method. Note the Data property. The MSDN documentation from Microsoft provides good examples for how th. 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, as 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.

IBaseMessageContext

IBaseMessageContext is the interface used to interact with and manipulate the object context accessible through the IBaseMessage.Context property. Table 7 and Table 8 show the public properties and methods. The MSDN documentation from Microsoft provides good examples for how these interfaces are to be used. 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. For 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.

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. The MSDN documentation from Microsoft provides good examples for how these interfaces are to be used.