Manage routing in the new Azure Service Bus EAI

Study Case: In this tutorial we are going to assume that an enterprise wants to rout their XML format emails from their employees, using a bridge and azure queues as well as connection routing definition. When as email arrives the bridges filters it and using the receiver name decides in which queue it’s going to store the email (XML message). Using this example you can imagine a whole bunch of scenarios and try to implement them using this algorithm and example.

Create a Service Bus project
Create a Schema
Design the Bridge
Add Queues
Configure the Bridge
Enrich the Message
Set the routing conditions
Create the Queues
Test the solution

Exercise

1. Create a Service Bus project

Open Visual Studio and select -> New Project -> Visual C# -> Service Bus -> Enterprise Application Integration

2. Create a Schema

You can use my own example XSD (Schema) example or imagine your own scenario with your examples. My code is described below:

3. Designing the Bridge

In this step just drag-and-drop a one-way-bridge (you can find in it the visual studio tool box) which is going to be an entry point to our windows azure appfabric space. Just notice or change it to something more familiar, the Bridge relative path, which is going to be used to build a full path to this azure entry point.

In my case I changed it to “ReceptorEmails”.

4. Configure Bridge Configurations Namespace

Open the BridgeConfiguration.bcs file (locate it in de solution explorer) which is automatically created with the project and in its properties change the namespace value to your namespace, created in appfabric portal.

5. Add Queues

Add the bridge by drag-and-drop which one of them into your BridgeConfiguration.bcs file. Change the queues names to make the distinguish process easier. In my case I choose {Queue1 => “RuiMachado”, Queue2 => “SandroPereira”, Queue3 => “JoãoPinto”}.

Next step is connecting the bridge to each queue. This connector is where you are going to define the filter condition so that the bridge can decide to which queue route a message. To do this connection don´t drag and drop the connection because it’s not going to work (yes its true), you must click on the connection item in the toolbox and then click on the bridge send point and now without releasing your mouse button join this point with the one placed in the queues. Example:

6. Configure the Bridge

Now we are going to build our Bridge Definition, just double-click your bridge (in my case ReceptorEmails ) and you will see this visual configuration wizard:

Now click the plus (+) button (a Message Type Picker Wizard will pop up) in the top and define the format of your receive XML message (Schema).

Select the Schema you’re created in step 2. In my case I named it Email so my Schema is the one named Email (as I only created one it’s the only available). Click OK and close the bridge wizard.

7. Enrich the Message

In this step we are going to choose and define by which property in our Schema created in step 2 should the bridge route the messages. It’s similar to promote a node in BizTalk and use it as routing in your Receive Location, however in this tutorial you don´t need to promote any node because we will use the enrichment process.

To do this enrichment you just need to open your Schema and select the one that you want to use as a filter in the routing.

In my case I selected the NameReceiver element to be my routing filter so it’s the one you see selected. Now with your chosen element selected check the Instance XPath in the properties window.

Based on Xpath language which was created to optimize the selection of nodes in XML (Based on the XML tree), an Instance Xpath defines the Xpath expression to access that particular node (in this case the NameReceiver element).

Copy that Instance Xpath because we will use it to specify the filter node in the enrichment configuration.

You will have an expression like: /*[local-name()='Email' and namespace-uri()='http://TesteRouting.Email']/*[local-name()='NameReceiver' and namespace-uri()='']

You don´t need to know what all that symbols mean however you want to know more about Xpath google it, there are lots of articles about it.

Now open de Bridge Wizard again (double-click your bridge in the BridgeConfiguration.bcs file). See step 6.

With your bridge wizard open click in the enrichment element (there are two options, before transformation or after, as we aren´t applying any transformation select the one before transformation).

To know if the Enrich is selected check if its color turned into blue as you can see above. Now with the Enrich selected go to its properties and click the square button with the ellipsis on it, at the right of Property Definitions:

A Property definition wizard will pop up.

Now click on the Add button and the configuration starts:

In the type element you need to specify the type of property we are going to use, among http, soap or ftp you will find a Xpath option, select it.

Next element to configure is Identifier; this one is for you to specify the Instance Xpath for your node that you copied before. Paste it there.

In the message type you need to specify what schema defines your XML message. In our case we just have one Schema configured (Email) so it’s the only one visible. Select it.

Now comes the Property configuration, in this part you will build the filter property based on the Schema node you identified with the Instance Xpath address. Give any name you want, try to choose a suggestive one. I chose “receptor”. In the Data Type define the type of property you are building, as in this case it’s a name I will select String but for example if you choose a DateTime you have a DateTime option.

Ok, the configuration is finished. You should have somehing like:

Click Ok and close the Bridge Wizard.

8. Set the routing conditions

Now it’s time to set the routing conditions based on this Property you just built in the enrichment process.

To do this click on a connector in your BridgeConfiguration.bcs file and on the properties windows click on Filter Condition.

You will see that a square button with an ellipsis on it will appear on the right of the Filter Condition property. Click on it. A wizard will pop up.

In this wizard we just need to define the filter based on the property created in the enrichment process. As we define that property name as “receptor” start writingiin the filter textbox “receptor=” and now choose the NameReceiver name that should be used to filter. Notice that this is the value that will come in the NameReceiver node in the received XML message. So the final expression filter in this first query will be “receptor=’Rui Machado’” because I want to say that every XML messages (Emails in XML) that arrive to Mr. Rui Machado will be routed to this queue. You shoul have something like:

Click OK and now right below Filter Condition in the properties windows you have the Messaging Protocol, select REST and the final result for this queue will be:

Now do this for each queue. In my case I got this:

Now save this changes as well as the whole project and Visual Studio. The Visual Studio part is complete.

9. Configuring the queues in azure

In this step you need create the Queues in the Azure AppFabric Portal, to do this you have two options, a visual one and a command prompt based one. I will show you how to do both.

Starting with the visual option, access to portal.appfabriclabs.com and sign in to your account. If you haven´t access the portal because I will do a small demo on how to have access to the appfabric azure portal. If you already have a appfabric azure namespace to use in this project ignore this 9.a step and jump to 9.b.

A) Accessing the portal and creating a namespace

When you access the appfabric portal for the first time you will be routed to a windows live id sing in page. If you don’t have windows live id, create one. Now with your windows live id email and password access the portal.

Once you sign in the portal will appear.

Now click on the appfabric button (The last button on the left-down area of the portal)

When the Appfabric page opens, select New Namespace on the left-up area of the portal:

Just give a name to your namespace, select the Service Bus checkbox on the left, click ok and your appfabric azure namespace is created.

Now that you have a namespace it’s time to create the queues.

b) Create queues in azure appfabric portal

In the Appfabric page expand the services menu item on the left and click Service Bus.

Now you can see your subscription in the body. Expand your subscription (or desired subscription if you have more than one) and click on the namespace in which you want to create the queues.

Now select the New Queue option in the header menu of the page.

A wizard pop up will appear. Just give the queue a name and a maximum queue size. Don´t worry with the other fields, leave them as they are.

Click ok and your first queue is created. Now do this for the other two queues (if you created 3 queues in your visual studio project as I made, otherwise, create one for each queue you have). In my case you can see the three queues with suggesting names.

If you don´t want to access your portal to create the queues (you will need anyway) or loose time with the visual creation process, download the Samples.zip file from http://www.microsoft.com/en-us/download/details.aspx?id=17691http://www.microsoft.com/en-us/download/details.aspx?id=17691 , unzip it and open in Visual Studio the Samples -> Tools -> MessageReceiver project. Now built it in visual studio and close it.

Open you cmd.exe (Command Prompt) in windows.

Now using cmd go to the directory in wich MessageSender is built ( to change directory use the command cd Example:

cd Desktop\MessageReceiver\bin\debug )

Once in the folder run:

MessageReceiver.exe <Your namespace> <Issuer name> <Your issuer key> <Queue name> Create

This information can be found in your appfabric azure portal. Where?

<your namespace>

<issuer name> and <issuer key> , click on view (last option in the properties menu of appfabric portal)

A information menu will pop-up.

The <queue name> is the name you want to give to your queue.

When you collect all the info build the command based on that abstract example and run.

10. Test the solution

With the queues and the project created its time to test our application. To do this we will use another project provided in the Samples folder which is MessageSender. This Message Sender will send the XML files to the Bridge and MessageReceiver will allow us to read all the xml messages that a specific queue as. It’s our own command-prompt based Microsoft Outlook.

Start by generating an XML file based on the Schema created.

Once you have the XML or several XML files build the MessageSender, see how to do it in the 9.b step, cand open the cmd again.

To send messages use the following:

Navigate in cmd to the folder where the MessageSender was built
Run the following:
- MessageSender.exe <Your namespace> <your issuer name> <Your issuer key> <Your endpoint> <Path to sample file> application/xml

See how to get this info in 9.b step. Once you have all the info run the command. If everything was correctly you shoul see this in your cmd (Hidden my issuer key):

Now you may want to read your message. To do this runs the following command (Similar to create queue but now we replace the keyword Create for Listen):

MessageReceiver.exe <Your namespace> <Issuer name> <Your issuer key> <Queue name> Create

As you can see when you send a message you send define any king of queue, you just send it to the bridge and it will route the message based on the node NameReceiver which was defined in the enrichment process. However to read messages you need to specify the queue from which you want to read.

When you execute this command you should have the following result (Don´t forget to navigate to the path in which you built the MessagReceiver):

You can now see the XML that you sent. One last note, this Listen command only works once, it’s like a Not Read email inbox. You can send a message, but when you Listen it, the queue deletes the message. Don´t forget this is only a beta version of EAI and EDI Labs.
ce, it’s like a Not Read email inbox. You can send a message, but when you Listen it, the queue deletes the message. Don´t forget this is only a beta version of EAI and EDI Labs.

Thats it, Thanks,

Rui Machado
http://rpmachado.wordpress.com

I was recruited by Sandro Pereira (http://sandroaspbiztalkblog.wordpress.com/)