1. Problem
You have messages that conform
to several different schema types. You wish to create a single
orchestration to consume the messages and process them in a generic
fashion.
2. Solution
BizTalk orchestrations
deal with messages that are strongly typed. A strongly typed message
conforms to a selected BizTalk schema or .NET class, and the message
inherits its properties from this schema or class. An untyped message is
configured to use System.Xml.XmlDocument as the message type and is not tied to a specific schema.
For example, a large
business may receive purchase orders from several different systems, and
each message must follow the same processing steps. Although the
messages are similar, they differ in minor details and are strongly
typed to different schemas. In order to process the messages from these
disparate systems using the same process, you may wish to define a
process with an untyped message to receive the different purchase order
schemas into the same receive port.
NOTE
It is important that you have a basic understanding of receiving messages prior to implementing untyped messages.
To create an untyped message and use it within an orchestration, take the following steps:
In
the Orchestration View window, expand the top node of the tree view
(this node will have the same type name as the orchestration) 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 this example, the message is named incomingOrder.
Click the Message Type property in the Properties window, and select the .NET type System.Xml.XmlDocument.
From
the toolbox, drag a Receive shape onto the orchestration directly
beneath the green circle at the top of the design surface.
With the Receive shape selected, specify the shape's Name, Message, and Activate properties. In our example, we use ReceiveOrder, incomingOrder (created in step 3), and True, respectively.
NOTE
All message types will
be received by an untyped port. Therefore, if you directly bind your
port to the MessageBox, you will receive every message received into the
MessageBox. This could create unintended behavior down the road.
Right-click one of the Port Surface areas, and select New Configured Port. This will open the Port Configuration Wizard.
Step through the Port Configuration Wizard, specifying the following items (accept all other default values):
Port name: ReceiveOrderPort
New port type name: ReceiveOrderPortType
Port binding: Specify Later
Configure the Request: Connect the orchestration port's Request operation to the Receive shape.
3. How It Works
Untyped messages are a
deceptively complex and powerful BizTalk feature. Untyped messages are
powerful, because they allow for abstracted processes. For instance,
rather than create three processes for three different purchase orders
that your company receives from trading partners, you could create a
single process that handles the different messages in the same process.
Although the single process may increase in complexity, it reduces the
amount of maintainable code.
When implementing untyped messages, pay attention to the following areas:
Direct binding:
Creating an untyped message that is directly bound to the MessageBox is
not recommended. All schema-based messages within BizTalk have a base
type of System.Xml.XmlDocument. The implication of this fact is that using a message variable that is typed as System.Xml.XmlDocument
will set up a receive subscription for all messages that are received
into the MessageBox through the directly bound port. Since, in almost
every case, this is not the desired functionality, take caution when
implementing this type of scenario.
Casting:
Creating an untyped message will negate many of the common operations
available for that schema type. For instance, accessing common promoted
properties (MessageDataBaseProperties)
and using Transform shapes are not supported with untyped messages. It
is possible, though, to cast between an untyped message and a typed
message. To cast a message, create an instance of the typed message in a
Construct/Assignment shape, and assign the untyped message to the typed
message. You now have the ability to use the typed message with all
associated orchestration functionality.
Promoted properties: Although it is not possible to access common promoted properties (MessageDataBaseProperties) for an untyped message, it is possible to create and access a type of promoted property known as a MessageContextPropertyBase
property for an untyped message. Refer to the BizTalk help file for
more information about how to create this type of context property
within your property schema. Setting the MessageContextPropertyBase property is done in the same manner as setting other promoted properties.
NOTE
MessageContextPropertyBase
properties of untyped messages may be set within the orchestration, but
the context property cannot be filtered on within other services unless
a correlation set containing the MessageContextPropertyBase property is first initialized. In addition, it is not possible to map on a send port, because the MessageType property, which is required to match a message to a map, is not promoted for untyped messages.
By considering direct
binding, casting, and promoted properties, you can safeguard your
solution from complex bugs that are difficult to identify and triage.
