How to integrate BizTalk Server 2010 / 2013 with Service Bus for Windows Server
Author: Paolo Salvatori
Reviewers: Mandi Ohlinger
Download Sample: How to integrate BizTalk Server 2010 / 2013 with Service Bus for Windows Server
Microsoft BizTalk Server enables organizations to connect and extend heterogeneous systems across the enterprise and with trading partners. The Service Bus provides connectivity, queuing, and routing capabilities to cloud and on-premises applications. In the cloud, Service Bus is available in the Microsoft Azure Virtual Machine platform. On-premise, Service Bus for Windows Server is available as a set of installable components and services.
This topic includes a sample that evolved from How to integrate a BizTalk Server 2010 application with Service Bus Queues and Topics. This sample demonstrates how to use WCF with NetMessagingBinding to integrate a BizTalk Server 2010/2013 application with Service Bus for Windows Server.
The solution uses the following components to integrate BizTalk Server and Service Bus for Windows Server:
A set of custom endpoint behaviors:
ServiceBusMessageInspector
ListenUriEndpointBehavior
SessionChannelEndpointBehavior
TokenProviderEndpointBehavior
This article shows how to use these components in a BizTalk application and how to configure a WCF client application to implement the following:
Send messages to a BizTalk Server 2010/2013 application using a Service Bus queue.
Send messages to a BizTalk Server 2010/2013 application using a Service Bus topic.
Receive messages from a BizTalk Server 2010/2013 application using a Service Bus queue.
Receive messages from a BizTalk Server 2010/2013 application using a Service Bus subscription.
To send messages to the BizTalk application, you can use the Service Bus Explorer tool or use the client application included in this sample. This client application uses Microsoft.ServiceBus.dll to exchange messages with the BizTalk application using WCF.
There are two scenarios:
Scenario 1: The application uses static send ports.
Scenario 2: The client application specifies the URL of the response queue or topic.
Scenario 1
The Windows Forms client application simulates an on-premise line-of-business (LOB) system. The LOB system exchanges messages with a BizTalk Server application that uses queues, topics, and subscriptions provided by Service Bus for Windows Server. In this scenario, the BizTalk Server 2010/2013 application uses static send ports and the same queue or topic to send the response back to the caller.
.jpg "Static Orchestration")
Message Flow
The Windows Forms client application uses a WCF proxy to send a request message to the requestqueue or to the requesttopic.
The BizTalk Server application uses a one-way receive port to receive request messages from the Service Bus. Specifically, a WCF-Custom receive location (ServiceBusForWindowsServer.WCF-Custom.NetMessagingBinding.Queue.ReceiveLocation) reads request messages from the requestqueue. A second WCF-Custom receive location (ServiceBusForWindowsServer.WCF-Custom.NetMessagingBinding.Subscription.ReceiveLocation) receives request messages from the italyMilan subscription of the requesttopic. Both receive locations use the following components:
The NetMessagingBinding receives messages from a queue or subscription.
At runtime, a custom WCF Message Inspector (ServiceBusMessageInspector) reads the BrokeredMessageProperty from the Properties collection of the inbound WCF Message. The WCF Message Inspector (ServiceBusMessageInspector) transforms its standard properties (such as MessageId and ReplyTo) and application-specific properties (the key/value pairs in the Properties collection of the BrokeredMessageProperty) into context properties in the BizTalk message.
The ListenUriEndpointBehavior is used by the WCF-Custom receive location that retrieves messages from the ItalyMilan subscription defined on the requesttopic. This custom component sets the ListenUri property value of the service endpoint. The ListenUriEndpointBehavior is described later in this article.
If an application retrieves messages from a sessionful queue or subscription, the SessionChannelEndpointBehavior must be added to the configuration of the WCF-Custom receive location. This custom component confirms that at runtime, the WCF-Custom adapter creates an IInputSessionChannel in place of an IInputChannel. Adding a SessionChannelEndpointBehavior is a mandatory requirement to receive messages from a sessionful messaging entity.
The TokenProviderEndpointBehavior allows the receive location to authenticate against the local STS used by the Service Bus namespace by using the WindowsTokenProvider or OAuthTokenProvider. When using the WindowsTokenProvider, you can use the host instance service account running the receive location to authenticate against the local STS or you can specify alternative credentials. When using the OAuthTokenProvider, always specify credentials in the form of username, password, or domain. LocalMachine\LocalUser or Domain\DomainUser is used to access the Service Bus namespace. The user account used by the receive location must be authorized to access the Service Bus namespace that hosts the queue or subscription. To authorize the user account to access the namespace, you can use the New-SBNamespace Windows PowerShell cmdlet when you create the namespace or the Set-SBNamespace cmdlet to add the user account to the group of the namespace managers.
The Message Agent submits the request message to the MessageBox (BizTalkMsgBoxDb).
The inbound request starts a new instance of the StaticSendPortOrchestration. The StaticSendPortOrchestration uses a Direct Port to receive request messages that satisfy the following filter expression:
Microsoft.WindowsAzure.CAT.Samples.ServiceBusForWindowsServer.Schemas.Method == Static
The orchestration invokes a method exposed by the RequestManager helper component to calculate the response message. It copies the request message context properties to the response message and assigns the MessageId context property value of the request message to the CorrelationId property of the response message. Finally, it checks the string value contained in the ReplyTo context property. If the string value contains the word "queue", the orchestration returns the response message through a logical port bound to a WCF-Custom send port configured to send messages to the responsequeue. Otherwise, it publishes the response to the MessageBox using a logical send port bound to a WCF-Custom send port configured to send messages to the responsetopic.
The Message Agent submits the request message to the MessageBox (BizTalkMsgBoxDb).
One of the following WCF-Custom send ports consumes the response message:
ServiceBusForWindowsServer.WCF-Custom.NetMessagingBinding.Queue.SendPort: Writes the response message to the responsequeue.
ServiceBusForWindowsServer.WCF-Custom.NetMessagingBinding.Topic.SendPort: Writes the response message to the responsetopic.
The selected send port writes the response message to the responsequeue or responsetopic. Both send ports are configured to use the following components:
The NetMessagingBinding sends messages to the Service Bus.
The ServiceBusMessageInspector transforms the message context properties into BrokeredMessage properties.
The TokenProviderEndpointBehavior allows the send port to authenticate against the local STS used by the Service Bus namespace by using the WindowsTokenProvider or OAuthTokenProvider. The same considerations when using this component in a receive location also apply to send ports.
The client application uses a WCF service with two endpoints to retrieve the reply message from the responsequeue or responsetopic. In an environment with multiple client applications, each endpoint should use a separate queue or subscription to receive response messages from BizTalk Server.
Scenario 2
The Windows Forms client application also simulates a line-of-business (LOB) system. The LOB system exchanges messages with a BizTalk Server application that uses queues, topics, and subscriptions provided by Service Bus for Windows Server. In this scenario, the client application specifies the URL of the response queue or topic in the ReplyTo property. Specifying the URL allows different client applications to send requests through the same queue or topic, but uses different queues and topics to receive responses. This architecture allows the BizTalk application to use a single dynamic send port to transmit responses to client applications.
.jpg "Dynamic Orchestration")
Message Flow
The Windows Forms client application uses a WCF proxy to send a request message to the requestqueue or to the requesttopic.
The BizTalk Server application uses a one-way receive port to receive request messages from the Service Bus. Specifically, a WCF-Custom receive location (ServiceBusForWindowsServer.WCF-Custom.NetMessagingBinding.Queue.ReceiveLocation) reads request messages from the requestqueue. A second WCF-Custom receive location (ServiceBusForWindowsServer.WCF-Custom.NetMessagingBinding.Subscription.ReceiveLocation) receives request messages from the italyMilan subscription of the requesttopic. Both receive locations are configured to use the following components:
The NetMessagingBinding receive messages from a queue or subscription.
At runtime, a custom WCF Message Inspector (ServiceBusMessageInspector) reads the BrokeredMessageProperty from the Properties collection of the inbound WCF Message. The WCF Message Inspector (ServiceBusMessageInspector) transforms its standard properties (such as MessageId and ReplyTo) and application-specific properties (the key/value pairs contained in the Properties collection of the BrokeredMessageProperty) into context properties of the BizTalk message.
The ListenUriEndpointBehavior is used by the WCF-Custom receive location that retrieves messages from the ItalyMilan subscription defined on the requesttopic. This custom component sets the ListenUri property value of the service endpoint. The ListenUriEndpointBehavior is described later in this white paper at ListenUriEndpointBehavior.
If an application retrieves messages from a sessionful queue or subscription, the SessionChannelEndpointBehavior must be added to the configuration of the WCF-Custom receive location. SessionChannelEndpointBehavior confirms that at runtime the WCF-Custom adapter creates an IInputSessionChannel in place of an IInputChannel. Adding the SessionChannelEndpointBehavior is a mandatory requirement to receive messages from a sessionful messaging entity.
The TokenProviderEndpointBehavior allows the receive location to authenticate against the local STS used by the Service Bus namespace by using the WindowsTokenProvider or OAuthTokenProvider. When using the WindowsTokenProvider, you can use the host service account running the receive location to authenticate against the local STS or you can specify alternative credentials. When using the OAuthTokenProvider, always specify credentials in the form of username, password, or domain. LocalMachine\LocalUser or Domain\DomainUser is used to access the Service Bus namespace. The user account used by the receive location must be authorized to access the Service Bus namespace that hosts the queue or subscription. To authorize the user account to access the namespace, you can use the New-SBNamespace Windows PowerShell cmdlet when you create the namespace or the Set-SBNamespace cmdlet to add the user account to the group of the namespace managers.
The Message Agent submits the request message to the MessageBox (BizTalkMsgBoxDb).
The inbound request starts a new instance of the DynamicSendPortOrchestration. The DynamicSendPortOrchestration uses a Direct Port to receive request messages that satisfies the following filter expression:
Microsoft.WindowsAzure.CAT.Samples.ServiceBusForWindowsServer.Schemas.Method == Dynamic
The orchestration invokes a method exposed by the RequestManager helper component to calculate the response message. It copies the request message context properties to the response message and then assigns the request message MessageId context property value to the response message CorrelationId property. Next, it reads the address of the messaging entity (queue or topic) to which to send the response from the ReplyTo context property. Finally, the orchestration configures the context properties of the response message and the properties of the dynamic send port to use the following components:
The NetMessagingBinding sends messages to the Service Bus.
The ServiceBusMessageInspector transforms the message context properties into BrokeredMessage properties.
The TokenProviderEndpointBehavior allows the receive location to authenticate against the local STS used by the Service Bus namespace by using the WindowsTokenProvider or OAuthTokenProvider.
The Message Agent submits the request message to the MessageBox (BizTalkMsgBoxDb).
The ServiceBusForWindowsServer.Dynamic.SendPort dynamic one-way send port consumes the response message.
The dynamic send port uses the WCF-Custom adapter and NetMessagingBinding as specified by the orchestration to send back the response to the messaging entity (in this sample, responsequeue or responsetopic) whose address is specified in the client application in the ReplyTo property of the BrokeredMessageProperty.
The client application uses a WCF service with two endpoints to retrieve the reply message from the responsequeue or responsetopic. In an environment with multiple client applications, each endpoint should use a separate queue or subscription to receive response messages from BizTalk Server.
In this Sample
This sample consists of the following steps: