Using the SB-Messaging Adapter & ESB Toolkit to send messages to the Windows Azure Service Bus

BizTalk Server 2013 Beta introduces the new SB-Messaging adapter to send and receive message from the Windows Azure Service Bus entities like Queues, Topics, and Relays. The topics on MSDN provide instructions on how to configure an SB-Messaging receive location and a send port to receive and send messages from the Service Bus but there is no information provided on how to do it with the ESB Toolkit.
I really like the ESB Toolkit concept but it’s not quite finished so if you want to sent a message to a Service Bus Queue in Windows Azure it will not work out of the box.

Modifying and Extending the BizTalk ESB Toolkit

There is no SB-Messaging Adapter Provider in the ESB Toolkit so to make it work you will have to create a Custom SB-Messaging Adapter Provider. Furthermore is also a Custom Routing Service needed. The Routing Service of the ESB Toolkit set’s all the necessary properties on the Dynamic Send Port but the Authentication Properties and the Brokered Message Properties from the SB-Messaging adapter have to be set on the message as context properties.

To create a custom SB-Messaging Adapter Provider x

1. Create an assembly that derives from the BaseAdapterProvider base class and contains a SetEndPoint method that sets the endpoint context properties of the message.

2. Register the adapter provider by adding it to the Esb.config configuration file using an <adapterProvider> element.

<adapterProvider name="SB-Messaging" type="itHero.ESB.Adapter.SBMessaging.AdapterProvider, itHero.ESB.Adapter.SBMessaging, Version=1.0.0.0, Culture=neutral, PublicKeyToken=cdb4e8bc8e6104aa" moniker="SBMessaging" />

3. Create a Manifest File for Custom Adapter Properties

When creating a custom adapter provider, you must also provide designer support for the adapter provider to those resolver extenders that display an endpoint configuration property. To enable designer support, it is necessary to create an adapter provider manifest file. The manifest file should be placed in the same folder as the Itinerary Designer binaries: C:\Users\MyUser\AppData\Local\Microsoft\VisualStudio\11.0\Extensions\ncg5g43x.y5w

<?xml version="1.0" encoding="utf-8" ?> <adapterPropertyManifest adapterName="SB-Messaging"> <aliases> <alias name="globalPropertySchemas" value="Microsoft.BizTalk.GlobalPropertySchemas, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </aliases> <properties> <property name="IssuerName" type="WCF.IssuerName" assembly="globalPropertySchemas" /> <property name="IssuerSecret" type="WCF.IssuerSecret" assembly="globalPropertySchemas" /> <property name="StsUri" type="WCF.StsUri" assembly="globalPropertySchemas" /> <property name="Label" type="SBMessaging.Label" assembly="globalPropertySchemas" /> </properties> </adapterPropertyManifest>

4. Register the new assembly in the global assembly cache.

To create a Custom Itinerary Messaging Service

1. Create a custom routing service that is based on the RoutingService in the Microsoft.Practices.ESB.Itinerary.Services Assembly. I used Reflector to get the code from the RoutingService class.

2. Add extra code to set the URI for the Service Bus Access Control Service STS endpoint, the issuer name and the issuer key for the Service Bus namespace because the properties are not set on the adapter, but on the message as context properties. Also the Brokered Message Properties are set on the message as context properties.

//Set WCF-properties msg.Context.Write("IssuerName", http://schemas.microsoft.com/BizTalk/2006/01/Adapters/WCF-properties, endpointConfigItems["IssuerName"]); msg.Context.Write("IssuerSecret", http://schemas.microsoft.com/BizTalk/2006/01/Adapters/WCF-properties, endpointConfigItems["IssuerSecret"]); msg.Context.Write("StsUri", http://schemas.microsoft.com/BizTalk/2006/01/Adapters/WCF-properties, endpointConfigItems["StsUri"]); //Set BrokeredMessage-properties msg.Context.Write("Label", http://schemas.microsoft.com/BizTalk/2012/Adapter/BrokeredMessage-properties, endpointConfigItems["Label"]);

3. Register the Custom Itinerary Messaging Service by adding it to the Esb.config configuration file using an <itineraryService> element.

<itineraryService id="10000" name="itHero.ESB.Itinerary.Services.ServiceBusRouting" type="itHero.ESB.Itinerary.Services.ServiceBusService, itHero.ESB.Itinerary.Services, Version=1.0.0.0, Culture=neutral, PublicKeyToken=191980cbfe160b14" scope="Messaging" stage="AllReceive"/>

4. Register the new assembly in the global assembly cache.

Creating the itinerary

1. Create an itinerary that contains the Custom Service Bus Routing Service. Use a Resolver to set the SB-Messaging Adapter Provider.

2. Set the adapter name and the location of the Azure Queue in the resolver for the Service Bus Routing Service.

3. Click Access Key in the Azure Management Portal to obtain the credentials associated with your queue.

4. Set the Authentication properties and Brokered Message Properties in the Endpoint Configuration pop-up.

Testing the sample

1. In Windows Explorer, open the folder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then start the application named Esb.Itinerary.Test.exe.

2. Run WireShark to verify that the authentication was successful.

3. Run the Service Bus Explorer to get the XML message that is sent to the Azure Service Bus Queue. Here you can also view the Brokered Message Properties that are set on the message

Conclusion

It is unfortunate that the SB-Messaging adapter provider is not available out of the box in the ESB Toolkit. You can easily expand the ESB Toolkit but it’s not extensively documented so it took me quite some time to create the Custom Messaging Service and the SB-Messaging Adapter Provider to set the necessary properties,.

You can download the Custom Messaging Service and the SB-Messaging Adapter Provider with the source code here:
http://code.msdn.microsoft.com/Using-the-SB-Messaging-38230f9e