1. Problem
You are building an integration
solution and receive multiple documents that together form a single
logical message in your back-end system. You must group these documents
into one message by using a multipart message in BizTalk Server.
2. Solution
Multipart messages are
created in BizTalk Server orchestrations, as opposed to being created as
schemas. Multipart messages are a collection of message parts, with
each part having a specific type. Message part types can be defined by
an XSD schema or a .NET class. This solution describes how to use XSD
schemas to define each of the message parts.
To create an orchestration and a multipart message, follow these steps:
Open
the project that contains the schemas. In this sample, we will use an
order header schema and an order line item schema to demonstrate the use
of multipart messages, as shown in Figure 1.
Right-click the project, and select Add→New Item.
In
the Add New Item dialog box, select Orchestration Files from the
Categories list and BizTalk Orchestration as the template, and give a
descriptive name to your new orchestration. In our example, the
orchestration is named MultiPartMessageOrchestration. Then, click Add.
In the Orchestration View window, expand the Types node of the tree view so that the Multi-part Message Types folder is visible, as shown in Figure 2. (If the Orchestration View window is not visible, select View => Other Windows→Orchestration View.)
Right-click the Multi-part Message Types
folder, and select New Multi-part Message Type, which creates a new
multipart message type. A default message part is automatically added to
all newly created multipart message types.
Click
the new multipart message type, and give it a descriptive name in the
Properties window. In our example, the multipart message is named Order.
Expand
the new multipart message type, click the default message part, and
give it a descriptive name in the Properties window. In our example, the
message part is named Header. Note that the Message Body Part property is set to True.
Click the Type property in the Properties window, and select the appropriate schema to associate with the message part, as shown in Figure 3. In our example, the schema is named OrderHeader.
Right-click the Order multipart message type, and select New Message Part, which creates a new message part.
Click the new message part, and give it a descriptive name in the Properties window. In our example, the message part is named LineItems. Note that the Message Body Part property is set to False.
Click the Type property in the Properties window, and select the appropriate schema to associate with the message part, as shown in Figure 4. In our example, the schema is named OrderLineItems.
In the Orchestration View window, expand the top node of the tree view so that the Messages folder is visible.
Right-click the Messages folder, and select New Message, which creates a message.
Click the new message, and give it a descriptive name in the Properties window. In our example, the message is named MultiPartOrderMessage.
Click the Message Type property in the Properties window, and select the appropriate type to associate with the message, as shown in Figure 5. In our example, we select the Order multipart message type.
3. How It Works
Multipart messages allow
for the grouping of multiple parts into a single message. In our
solution, we group an order header document and an order line item
document into a single order message.
All messages within
BizTalk Server are multipart messages, although most of them just have a
single part (the message body) and, therefore, are not created as a
multipart message within orchestrations. Messages with a single part are
treated slightly differently by BizTalk Server, as the single part is
not displayed when referring to the message and the message is referred
to directly.
The concept of messages
having multiple parts is easier to grasp after creating a multipart
message type within an orchestration, where you must explicitly create
the different parts of a message. Each message part has a number of
properties associated with it, as listed in Table 1.
Table 1. Message Part Properties
| Property | Part |
|---|
| Description | Summary of message part |
| Identifier | Name of the message part |
| Message Body Part | Flag
indicating whether the message part contains the message body (every
multipart message must have one and only one body part) |
| Report To Analyst | Flag indicating whether the message part should be exposed via the Visual Business Analyst Tool |
| Type | The type defining the message part's content |
The type of message part can be
either a .NET class or an XSD schema. If a .NET class is specified, the
class must be XML-serializable or support custom serialization. If an
XSD schema is used, the schema must be included in the same BizTalk
Server project as the multipart message type or in a referenced
assembly. By specifying the XmlDocument type, a message part can contain any valid XML document. The multipart message type has the properties listed in Table 2 associated with it.
Table 2. Multipart Message Type Properties
| Property | Part |
|---|
| Identifier | Name of the multipart message type |
| Report To Analyst | Flag indicating whether the multipart message type should be exposed via the Visual Business Analyst Tool |
| Type Modifier | The scope of the multipart message type; choices are Private (accessible within the orchestration), Public (accessible everywhere), or Internal (accessible within the same project) |
Once you have defined your
multipart message types, you can create and access message instances of
those types within the orchestration. Figure 6 illustrates how you can assign the Header and LineItems message parts of the Order message. In this example, the OrderHeaderMessage and OrderLineItemsMessage messages are instances of the Header and LineItems schemas.
Some common uses of
multipart messages in BizTalk Server are when you are consuming a
service or processing e-mail messages within orchestrations. When you
add a web service reference to an orchestration, a multipart message
type is generated automatically, with one part created for each message
part defined in the web service's WSDL file. For those scenarios where
e-mail messages are being processed, it is common to use multipart
message types to handle MIME multipart messages; the body message part
would contain the body of the e-mail, and subsequent parts could contain
e-mail document attachments.
