Dynamic Direct Bound Ports

A dynamic port allows you to set the address of the logical port to a URI so that at runtime the message can be routed to the correct service to handle the request and the service can then send to the indicated endpoint.  In BizTalk Server 2006 the same can be done for direct bound ports. 

Setting the address of a port is done by assigning a URI to the Microsoft.XLANGs.BaseTypes.Address property of the port:

Port_1(Microsoft.XLANGs.BaseTypes.Address) = “http://contoso.com/myService”;

The general format of a port address is:

<adapterAlias><endpointAddress>

A port address is made up of the adapter alias that ultimately maps to a transport, and the actual endpoint as is meaningful to the adapter.  So an adapter alias of HTTP:// will have a URL and a FILE:// will have a URN or a reference to a local file on disk.

This of course begs the question of, “what does a direct bound port URI look like?” 

Direct bound port address’ have the following format:

msgbox:<PartnerService>#DirectPortFlavor#<port-type>

So for a direct bound port the transport, what would typically be the adapter alias, is the literal msgbox:. The rest is the endpoint address which, for direct bound ports, is a partner service and a port. The #DirectPortFlavor# indicates how the partner service will be interpreted.  Let’s look at the address of each flavor of a direct bound port.

Message Box Direct Bound Port Address

There is no address for a message box direct bound port as it doesn’t make sense since it is a pure publish or subscribe into the message bus (i.e. message box).

Partner Direct Bound Port Address

A partner direct bound port has the following format:

msgbox:<orchestration>#DirectPort#<port-type>

In this case the partner service is the orchestration the port is bound to.  The <orchestration> part is the strong name of the orchestration and has the format:

namespace.orchestrationTypeName, assemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9876543210abcdef

and <port-type> is the strong name of the port type and has the format:

namespace.portType, assemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9876543210abcdef.

The direct port flavor is the literal #DirectPort# and indicates that the partner service is an orchestration.

Here’s an example of what an address would look like:

msgbox:MyTests.TestOrchestration, MyTests.dll, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9876543210abcdef#DirectPort#MyTests.SomeDirectBoundPortType, MyTests.dll, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9876543210abcdef

Self-Correlating Direct Bound Port Address

A self-correlating direct bound port has the following format:

msgbox:<portServiceId>#selfCorrelated#<port-type>

In this case the partner service is the <portServiceId> which is the unique identifier, GUID, given to the port when the orchestration was instantiated and <port-type> is again the strong name of the port-type for this port and has the format:

namespace.portType, assemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9876543210abcdef.

The direct port flavor is the literal #selfCorrelated# and indicates that the partner service is a service instance identifier.

Here’s an example of what an address would look like:

msgbox:aabbccdd-0011223344-eeff-5566778899aa #selfCorrelated#MyTests.SomeSelfCorrelatingPortType, MyTests.dll, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9876543210abcdef

Scenario for using a self-correlated dynamic direct bound port

When doing asynchronous inter-orchestration communication, the typical way of correlating a message to a particular instance of an orchestration is by creating a correlation-set, initializing it with particular property values received or sent in a message, then following that correlation-set on a receive shape.  This can make your orchestration more complex if the values of the properties that you need to correlate on are not in the message when it is originally received forcing you to construct a new message with the correlation properties properly set and sending that message somewhere (it has to be sent to be able to initialize the correlation-set but the destination can be some null orchestration (i.e. an orchestration with just a receive shape)[1]).  Another pattern for inter-orchestration communication correlation is when you have a send and receive on separate one-way ports in a loop and you are using the send port to initialize the correlation set and the receive port to follow.  In this case you must unwind the loop (the first send must be outside of the loop) because you cannot initialize a correlation-set inside of a loop (a correlation-set can only be initialized once) thus making your orchestration even more complex[2].  To get around this extra correlation complexity you can use a self-correlating port that under the covers will manage the responsibility of correlating a message back to the current instance of the orchestration.

In the past the only way we would be able to use a self-correlated direct bound port was by passing the port as a parameter to a ‘started’ orchestration so that it can asynchronously send a message back to the instance of the orchestration that started it. 

Today in an expression shape you can save the port address of the self-correlated direct bound port in a message,

Msg1.ReturnAddress = SendPort1(Microsoft.XLANGs.BaseTypes.Address);

 send it to a partner orchestration and when the partner needs to communicate back to the instance of the orchestration that sent the original request it can set the address of a direct bound port to the port address that was saved in the message. 

ResponsePort1(Microsoft.XLANGs.BaseTypes.Address) = Msg1.ReturnAddress;

This really simplifies the design of the orchestration that is expecting asynchronous responses from its partner orchestrations.

When you create the send side port it doesn’t matter what type of direct bound port you create as you will be overriding its address.  I would recommend keeping each side as consistent direct bound flavors to make it easier to review the design.

Now that I have lifted the covers of how the dynamic direct bound ports work you can imagine many different scenarios and design patterns.  A few examples include, versioning, dynamic orchestration calling, and, of course, simplified correlation.

Partner Direct Bound Ports

Partner direct bound ports provide the capability of having inter-orchestration communication via ports. 

To configure a partner direct bound port you must choose the orchestration and port for the ‘Partner Orchestration Port’ property.  When configuring the two partner ports you must have one side select the orchestration.port it will communicate with and the other side will select its own orchestration.port.  This is a little non-intuitive but will be explained in the sections below.  Also the port types for both ports must be the same, which implies that the message-types must also be the same.  This is one of the places where the Type Modifier property on the port-type matters.  To be able to direct bind to a partner port the port-type type modifier must either be internal for orchestrations within the same assembly or public to allow an orchestration from another assembly to bind to it.  Finally, the polarities of the ports must be opposite.  In other words, if one side is a send port then the other side must be a receive port.

There are two communication patterns that can be created; forward partner direct binding and inverse partner direct binding.  These two patterns provide explicit inter-orchestration communication.  By explicit I mean that there is an intended recipient orchestration (forward partner direct binding) or an intended sender (inverse partner direct binding).  You can design implicit partner direct binding by having either the receiver be message box direct bound and create a filter that will accept messages from a particular sending orchestration or have the sender be message box direct bound and promote properties that will match a subscription on the receiving orchestration.

Forward Partner Direct Binding

This is the typical communication pattern that is used for partner direct binding.  Orchestration A has a partner direct bound send port that will send a message to Orchestration B on its partner direct bound receive port.  To configure this forward partner direct binding you must have orchestrationA.sendPort1, which is of type portType1, select orchestrationB.receivePort1, which is also of type portType1, as its Partner Orchestration Port.  orchestrationB.receivePort1 will select itself, orchestrationB.receivePort1, as its Partner Orchestration Port. 

Figure 6 Forward Partner Direct Binding Configuration

On the sender’s side what this says is, “I will send messages to orchestrationB.receivePort1” and on the receiver’s side it says, “I will receive any messages sent directly to my receivePort1”. 

Under the covers when messages are sent out of sendPort1 the orchestration engine will set the following properties:

BTS.Operation to the operation on the port being used.

BTS.PartnerPort to the name of the partner direct bound port configured in the Partner Orchestration Port property

BTS.PartnerService to the strong name of the orchestration referenced in the Partner Orchestration Port property

Note: the strong name of the partner service will usually look something like:

OrchNamespace.OrchTypeName, AssemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=fedcba9876543210

On the receive side the subscription will be (for brevity I will use the BTS namespace instead of http://schemas.microsoft.com/BizTalk/2003/system-properties as you would see in the actual subscription)

BTS.Operation == operation1 And

BTS.PartnerPort == receivePort1 And

BTS.PartnerService == MyTest.OrchestrationB, MyTest, Version=1.0.0.0, Culture=neutral, PublicKeyToken=fedcba9876543210 And

BTS.MessageType == http://MyNamespace#MyRootNodeTypeName

Something to note here is that there is a strong binding from the sender orchestration to the receiver orchestration.  By strong binding I mean that the sender orchestration is referencing the receiver’s strong name as its partner service.  What this means is that if you want to change the receiver’s side or if you change the version of the receiver’s side you must update the design time configuration of the sender’s port.  But the receiver has no explicit knowledge of the sender so the senders’ orchestrations can be updated without affecting the receiver.

This type of forward binding allows you to have multiple senders bound to the same recipient. 

Figure 7 N:1 communication

Here orchestrationD would be doing some common asynchronous work needed by many different orchestrations.

Inverse Partner Direct Binding

This is not the typical communication pattern that is used for partner direct binding as the direction of binding is inverse of its direction of communication.  Orchestration A has a partner direct bound send port will send a message to Orchestration B on its partner direct bound receive port.  To configure this inverse partner direct binding you must have orchestrationB.receivePort1, which is of type portType1, select orchestrationA.sendPort1, which is also of type portType1, as its Partner Orchestration Port.  orchestrationA.sendPort1 will select itself, orchestrationA.sendPort1, as its Partner Orchestration Port. 

Figure 8 Inverse Direct Binding Configuration

On the sender’s side what this says is, “I will send a message to anyone who is listening for messages from my send port” and on the receiver’s side it says, “I will receive messages sent from orchestrationA.sendPort1”.

Under the covers when messages are sent out of sendPort1 the logic for setting properties is still the same as it was for the forward case.  The orchestration engine will still set the following properties:

BTS.Operation to the operation on the port being used.

BTS.PartnerPort to the name of the partner direct bound port configured in the Partner Orchestration Port property

BTS.PartnerService to the strong name of the orchestration referenced in the Partner Orchestration Port property

On the receive side the subscription will

BTS.Operation == operation1 And

BTS.PartnerPort == sendPort1 And

BTS.PartnerService == MyTest.OrchestrationA, MyTest, Version=1.0.0.0, Culture=neutral, PublicKeyToken=fedcba9876543210 And

BTS.MessageType == http://MyNamespace#MyRootNodeTypeName

In this case the receiver is strongly bound to the sender implying that if you want to change the receiver’s orchestration or update the version then you must update the sender’s port configuration.  The sender has no explicit knowledge of the receiver so the receivers’ orchestrations can be updated without affect the sender.

This type of inverse binding allows you to have a single sender communicate with multiple receivers.

Figure 9 1:N communication

Inverse direct bound ports allows for a recipient list pattern.  The recipient list is determined by which receive ports are bound to a particular send port and is maintained as part of the orchestration design.  Here either all of the recipient orchestrations can consume any message coming from the send port or they can each have a filter to determine which messages each of the recipients should consume from the sender. 

One thing to be careful about is that if you are using a two-way port type with inverse partner direct binding then you must setup your filters to ensure that only one of the recipients will consume (i.e. subscription will match) the message.  This is because a solicit-response port is expecting a single response and if multiple recipients get the message, then it will accept the first response and all subsequent responses would be suspended non-resumable.  The engine won’t let that happen and it will instead throw an exception when you try to send the message indicating that there would be multiple recipients for a solicit-response request.

Direct Bound Ports

In BizTalk Server 2004/2006 orchestrations can have direct bound ports. 

Direct bound ports are logical one-way or two-way ports in your orchestration that are not explicitly bound to physical ports that allow you to have different communication patterns amongst your services.  To create a direct bound port select the binding of the logical port to be direct then choose as the ‘Partner Orchestration Port’ what this port will be bound to.

There are three types of direct bound ports that you can choose as the Partner Orchestration Port; message box, partner, and self-correlating.

Message box direct bound ports allows for publish-subscribe design patterns.  Messages sent on a message box direct bound port are published to the message box without any explicit intent of the message recipients.  Logical receive ports configured as message box direct bound ports get messages directly from the message box whose subscriptions are based only on message type and filter expression (for activating receive shapes) or correlation set (for non-activating receive shapes).

Figure 1 Message Box Direct Bound Ports

Partner direct bound ports provide for inter-orchestration communication.  Messages sent on a direct bound port can be sent to an intended recipient orchestration and messages received on a partner direct bound port can be received from an intended sender orchestration.

Figure 2 Partner Direct Bound Ports

Self-correlating direct bound ports assists you in designing asynchronous inter-orchestration communication.  Messages sent to a self-correlating direct bound port are routed to the instance of the orchestration that created the receiving end of the self-correlated direct bound port.

Figure 3 Self-Correlating Direct Bound Ports

A commonly misunderstood aspect of direct bound ports is its interaction with the message box with some incorrectly thinking that there is direct communication with another instance of an orchestration without traversing the message box.  This is not the case; any message sent through any type of logical port always travels through the message box. 

Figure 4 All logical ports communicate through the message box

Direct bound ports are only logical ports and therefore only a design time configuration feature.  An administrator cannot bind a direct bound port to a physical port nor change the partner it is currently configured for.

To see each of these different types of ports in action and in context you can look at the Business Process Management (BPM) scenario that ships as part of the SDK in BizTalk Server 2006.

I will have a separate posting and go into more detail on each type of direct bound port.

HttpOutCompleteSize

This setting controls the size of the batch of messages that is returned from the HTTP send adapter.  The default value for this is 5.  If the buffer is not full and there are outstanding responses then the adapter will wait for 1 second until it commits the batch.  For low-latency scenarios this should be set to 1 which will allow the adapter to send response messages immediately to the message box for processing.  This will have the greatest effect during times of low-throughput activity with varied response times from backend systems.

Actually this setting controls the number of messages being returned to BizTalk (EPM) from the HTTP adapter regardless of whether the port is one-way or two-way.  A message that is returned in the batch includes a request to DeleteMessage, MoveToNextTransport, MoveToSuspendedQ, and, most interestingly, SubmitResponseMessage.  Although this setting will improve response times in low-latency scenarios it does increase the amount of chattiness between the adapter and the message box.

It is the send side equivalent to the HttpBatchSize on an HTTP receive adapter.  In low-latency scenarios this is typically set to 1 to ensure that the messages are getting processed as quickly as they are received.

To set this value you need to add HttpOutCompleteSize as a DWORD value to the registry under:

HKLM\SYSTEM\CurrentControlSet\Services\BTSSvc{guid}\

where GUID is the ID of the host for HTTP send handler.

This information is specific to BizTalk Server 2004 and there is no guarantee that this setting will behave the same way in the next release of BizTalk Server.

Disclaimer: This is an undocumented setting and was not formally tested since it was not considered to be publicly available.  You must do your own testing to ensure that the behavior and performance of your system are as expected.

I suppose I should give a little background on myself before I start blogging to give my posts some context.  Before Microsoft I was designing and developing parts of foreign exchange transaction systems for Reuters.  I started at Microsoft about 7 years ago as a software design engineer on Windows working on the index server.  I spent much of my time porting the code to 64-bit.  As the year 2000 approached Microsoft was pushing harder into the Enterprise market with the 2000 series of products (Windows, SQL, BizTalk, Host Integration Server, and Commerce Server) on the horizon.  I was fortunate enough to get a position as an Enterprise Solutions Architect working closely with customers designing systems built on pre-released bits of Microsoft platforms and applications helping make them successful on Microsoft products and getting feedback of our findings back into the product teams.  I have been able to work closely with financial, telecommunication, retail and many other types of companies architecting solutions to work with our latest applications.  

Now I am part of the Business Process and Integration division still working closely with customers on design wins and architectures but now mostly with projects using BizTalk Server 2004.  While working in this position I have been able to experience both sides of our products; getting the customers’ perspectives and understanding the product group’s inner workings.  

In this blog I am planning on sharing some of these experiences and findings.  We sometimes discover that users don't understand parts of the system, or didn't know that they had to architect their system in a particular way (for example, many users don't realize that the master secret server must be clustered for a high availability build out).  I will use this blog to share some of that information as well.

There are some folks from the BizTalk team who are already blogging:

Scott Woodgate

Kevin Smith

Lee (the dude) Graber (BizTalk Core Engine)
Eldar Musayev

They already have some excellent posts and I would recommend looking at them as well.

Enjoy,

Kevin