To illustrate the concept by
a concrete example, let's refer to the source code provided with the
Echo adapter. The point of our interest is the Execute method of the Microsoft.ServiceModel.Channels.Common.IOutboundHandler
interface. This interface is one of the core interfaces that all
ASDK-based adapters supporting outbound operations must implement. The
Execute is called by the ASDK runtime to perform an outbound operation.
Here is the implementation:
The code is self-explanatory and
as you can clearly see, is action-centric. If the action coming with
the SOAP header is recognized, the adapter performs the requested
operation, if not, then the adapter responds with "Invalid Operation"
exception. Since the Echo adapter exposes only one operation, using
actions may seem unnecessary, but imagine the situation when an adapter
exposes multiple operations? In such cases, using the SOAP actions is
quite a logical way to help the adapter to decide what operation to
perform.
There are two different ways to
associate a BizTalk message with the appropriate SOAP action (or to
attach the appropriate processing tag as you wish). One is to configure
physical send ports using so called Action Mappings. The other is to set
the actions dynamically at runtime.
Action Mappings
You will use the Action
Mappings in the majority of cases—this is the easiest way to configure
physical ports since the Consume Adapter Service Wizard does most of the
job. For each operation that you selected at the design time, the Consume Adapter Service Wizard will generate a corresponding Operation entry inside the BtsActionMapping
wrapper and place the mapping into the physical port binding file it
will generate. In the general form, the action mapping looks as follows:
To process the actions
mappings and attach the SOAP actions tags to incoming messages, the
WCF-Custom adapter uses the following algorithm:
When the outbound message leaves an orchestration, the orchestration instance sets the BTS.Operation
context property with the logical port operation name. Once the
subscription mechanism pulls the message from the message box and hands
it over to the physical port for processing, the WCF-Custom adapter
tries to look up the actions map for the Operation with the Name
matching the BTS.Operation property. If a match is found, then the
adapter attaches the corresponding Action value to the message and sends
it to the custom binding for execution. If a match was not found, then
the WCF-Custom adapter treats the entire BtsActionMapping as one big
action, so the custom binding will get the following action:<BtsActionMapping><Operation Name="Operation 1" Action =......</BtsActionMapping>
with quite a predictable consequence—"Invalid action" exception. So,
the rule is clear: for each orchestration outbound operation, there must
be an Operation entry in the corresponding physical port action
mappings with the Name attribute value matching the orchestration
operation name.
It is important to note that
for the content-based routing scenarios, where you don't use
orchestrations and rely solely on the functionality provided by the
messaging engine, you don't have to write a custom pipeline component to
set the BTS.Operation context property. Luckily, the WCF-custom adapter
supports an alternative single action format.
Essentially, this
means that all messages arriving to the send port configured for the
single action processing will be tagged with the same action regardless
of the BTS.Operation
context property. Since the Echo adapter supports only one operation,
the single action approach is an alternative solution perfectly
applicable to our sample application.
Setting SOAP actions dynamically
In the situations where
you want to postpone the decision on what operation has to be performed
until the runtime, you can use the WCF.Action context property. All you need to do is to add an Expression shape to your orchestration and configure the shape to execute the code similar to the presented below:
YourOutboundMessage(WCF.Action)="DesiredAction"
As you can see, the
WCF-Custom adapter offers enough flexibility to address virtually any
situation you may encounter. Once you understand the concept and
available options, all it takes is accuracy and no longer than a couple
of minutes to configure send ports.
