Connecting to Windows Azure Service Bus from BizTalk Server 2010 R2 CTP

We recently announced the availability of BizTalk Server 2010 R2 CTP. BizTalk Server 2010 R2 comes with a lot of features to take advantage of the whole cloud push. In the last post, we have shown how you could leverage the power of the Azure IaaS cloud to get your BizTalk deployments up and running in no time. In this post, we will talk another feature which will help you take advantage of the cloud – the Service Bus Messaging adapter. The Service Bus Messaging adapter, in a nutshell, allows BizTalk Server to read and send messages to Azure Service Bus Queues and Topics/Subscriptions.

The presence of a messaging infrastructure on the cloud has many advantages – which is not the subject of this blog, but is well documented elsewhere. Let us take a simple scenario: Our customer is an insurance company and it deals with multiple partners who help in administering insurances to the end customers. An on-premise BizTalk Server would handle insurance claims coming from multiple partners. Each of the partners submits these claims to an incoming Service Bus queue. BizTalk Server picks up these claims from the incoming queue and processes them. Once it is done, BizTalk Server would publish the status of the claims to an outgoing topic. The partners could create a subscription on the topic to receive the claim status. Such a scenario that leverages Azure Service Bus can now be easily integrated with BizTalk Server with the new Service Bus Messaging adapter. Let us have a quick walk through of this adapter.

Getting Started

In order to get started, you will need two things: A Windows Azure Service Bus namespace and BizTalk Server 2010 R2 CTP. You can get both of these on Windows Azure – sign up for a free trial here if you do not have one. Now, as outlined in this article, you can create your queue/topic. And as outlined here you can quickly create an instance of BizTalk Server 2010 R2 CTP running in a Windows Azure Virtual Machine.

Receiving messages from a Queue or a Subscription

BizTalk Server 2010 R2 provides a receive adapter to fetch messages from a Windows Azure Service Bus queue or a subscription. The receive adapter is one-way and will work with messages that you post on the queue. The adapter is simple to set up and configure. You just need to provide the URL of the Service Bus queue or subscription from where you need to pick the messages from and the credentials for authenticating with Service Bus. To set up a receive adapter for Service Bus Queue:

(1) Create a one-way receive port in your BizTalk application.

(2) Create a new receive location and select “SB-Messaging” as the Transport Type as shown below.

(3) Click on “Configure…” to configure the properties of the receive location. In the transport properties General Tab, specify the URL for the queue or subscription from where BizTalk Server needs to fetch message from. You could also configure connection properties like open/close/receive timeout as well as the prefetch count. The Prefetch Count specifies the number of messages that BizTalk Server will fetch at a time. This can help increase the throughput of the adapter as well.

(4) On the Authentication Tab, you need to specify how BizTalk Server will fetch the required ACS Token for authenticating with Service Bus. You can read on how Service Bus uses Access Control Service for authentication here. In a nutshell, you will need to specify the Access Control Service URL for the service namespace. It is usually derived from the service bus namespace (suffixed with “-sb”) and you will only need to update the service namespace in the default template. You can find this in the Azure management portal as well. You also need to specify an issuer name and issuer key. You will need to ensure that the service identity has a Listen claim. If you are using the default service identity (“owner”), it will have the necessary claims.

(5) Click on “OK” or “Apply” to create the Receive Location.

You can then start your Receive Location and BizTalk Server will now start to fetch messages from the Queue or subscription. Easy!

Handling Brokered Message Properties in Receive Adapter

The SB-Messaging receive adapter understands BrokeredMessage properties. This means two things. First, BizTalk Sever 2010 R2 comes with a predefined property schema for all the standard properties of a BrokeredMessage. The adapter will also promote these properties automatically for you. Second, the adapter can write custom user-defined Brokered Message properties in the BizTalk message context. And, if you desire, you could also promote them. Promoting them will allow you to use them in your routing filters. For example, for our insurance claims applications, different applications could be routed based on who the type of insurance, the partner, the claim amount, etc. These properties could be defined as Brokered Message properties and passed on with the incoming message. These properties could be used to route the message to different backend systems or workflows/orchestrations in BizTalk Server. To promote the properties though, you need to create and add a property schema in your BizTalk application. Then, on the properties Tab of the adapter, you could specify the namespace for your schema and check the option to promote the property.

Sending messages to a Queue or a Topic

BizTalk Server 2010 R2 also provides a send side adapter for posting messages to a Service Bus Queue or Topic. This is a one-way send adapter. To set up a send port for posting messages to a Service Bus Queue or a Topic:

(1) Create a Send Port and select SB-Messaging as the Transport Type. Click Configure to configure the properties of the adapter.

(2) Click “Configure…” to configure the transport properties of the send adapter. You need to specify the URL of the Service Bus Queue or Topic where the message should be posted.

(3) On the Authentication Tab, you enter the credentials for authenticating with Service Bus. This is the same as you see on the receive adapter.

(4) Click on “OK” to save the transport properties of the adapter.

(5) Specify the other properties of your Send port like pipeline, handler, Filters, etc.

(6) Click “OK” to finish creating your Send port.

Now, you can enlist and start the send port. The adapter will now post outgoing BizTalk message to the Service Bus queue or topic.

Handling Brokered Message Properties in Send Adapter

As in the case of receive adapter, the send adapter is aware of Brokered Message properties. If the outgoing BizTalk message has any of the standard Brokered Message in its context, the adapter will automatically set them as Brokered Message property. In addition, you could also specify defaults as part of the Send port properties. For custom user defined Brokered Message, you could specify a namespace as part of the adapter configuration. The adapter will take any property in that namespace and set them as Brokered Message Properties.

Finally, a note on serialization

When you start using the adapter, you may find that the message you receive in BizTalk Server is garbled – especially if you are using the Service Bus .NET API. Let me explain why this happens and what the adapter expects.

The Service Bus messaging adapter just fetches the stream in the incoming message and submits it to BizTalk Server. While sending out a BizTalk message, it simply uses the content as a stream. We preserve the message format on the wire. So, if you write or read the stream directly in your code, say using the Service Bus REST API, you would see the same data in the payload as you would expect. However, if you are using the Service Bus .NET API, you may find that there is a serialization issue if you use the default serializer (DataContractSerializer with binary XmlDictionaryWriter). This is because the default serializer in the Brokered Message .NET API uses Binary encoding. To avoid this issue, you will need to use Text by explicitly provide your own serializer, instead of the default serializer.

For sending message:

// For sending message using DataContractSerializer with Text encoding

var message = new BrokeredMessage(data, new DataContractSerializer(typeof(MyDataType)));

While reading the message:

// For receiving message using a DataContractSerializer with Text encoding

var data = message.GetBody<MyDataType>(new DataContractSerializer(typeof(MyDataType)));

You could, of course, directly read the stream as well. For a detailed write-up on the content serialization of Service Bus messages, you can refer to this blog post.

Next Steps

This post provides an overview of the new Service Bus messaging adapter in BizTalk Server 2010 R2. This is one of the new features that we have enabled with BizTalk Server 2010 R2. With this adapter, BizTalk Server can seamlessly integrate with your applications that leverage the Windows Azure Service Bus Queues and Topics. We encourage you to try out this feature and provide your comments and feedback. You can use the BizTalk forum to post your questions/queries as well.

Thanks

BizTalk Server Team