Azure Integration with AMQP

Requirements:

• IPWorks IoT
• An Azure account

Contents

• Introduction
• Configuration Guide
  • Azure Service Bus Queues
  • Azure Service Bus Topics and Subscriptions
• Sample Code

Introduction

AMQP is a messaging system for communicating between two different containers with a variety of nodes. It defines both the protocol for sending messages between nodes and the structure of the messages themselves. For more information about the AMQP component please see the Getting Started with AMQP guide.

The AMQP component in the IPWorks IoT toolkit can be used to integrate with cloud messaging brokers such as AmazonMQ and Azure Service Bus. In this guide you will learn how to integrate with Azure Service Bus and build a multi-tenant application to send and receive messages. The component is a fully-featured implementation supporting queues, topics, and subscriptions.

Configuration Guide

Create a Service Bus resource in the Azure Portal and take note of the resource's domain name. Once the namespace has been created, it can be managed from the namespace main window:

Create a queue using the + button in the namespace main window.

The first step in configuring the AMQP client component is to set the ContainerId property to any name that identifies the top-level organizational grouping of AMQP protocol elements. Then, set the RemoteHost property to domain name of the Service Bus resource.

amqp.ContainerId = "MyContainer"; amqp.RemoteHost = "nsoftware.servicebus.windows.net"; amqp.RemotePort = 5671; amqp.SSLEnabled = true;

Azure Service Bus requires the use of TLS. By default, it supports connections over port 5671 for TLS over TCP.

Next, we will set authentication information in the component. All of the necessary information is already available in the Azure Portal. In the namespace window click Shared access policies.

At the time you created your namespace, an initial Shared Access Signature rule (SAS) with a pair of primary and secondary keys was generated. This rule, named RootManageSharedAccessKey, confers rights for managing the entire namespace. Click on the rule to view the associated primary and secondary keys.

Set the User property to the name of the SAS policy and the Password property to the primary key or secondary key to connect to the resource.

# The AuthScheme property must be set to SASL Plain to connect with a username and password combination amqp.AuthScheme = AmqpAuthSchemes.smSASLPlain; amqp.User = "RootManageSharedAccessKey"; amqp.Password = "hA8s+pCW0I71DBS6uNclP4tRcwhTUvP5wYENXB5TaIY="; amqp.Connected = true;

Once a connection has been established you can create a session and send/receive links. The parameters passed to the CreateSenderLink and CreateReceiverLink methods will be different depending on whether you are building a Queue client or Publishing/Subscription client.

Queues

Service Bus queues are a brokered messaging communication model. Clients connected to the broker communicate indirectly with each other by passing messages via a queue. This is particularly useful in distributed Producer-Consumer applications.

Producer client

amqp.ContainerId = "MyContainer"; amqp.RemoteHost = "nsoftware.servicebus.windows.net"; amqp.RemotePort = 5671; amqp.SSLEnabled = true; amqp.AuthScheme = AmqpAuthSchemes.smSASLPlain; amqp.User = "RootManageSharedAccessKey"; amqp.Password = "hA8s+pCW0I71DBS6uNclP4tRcwhTUvP5wYENXB5TaIY="; amqp.Connected = true; amqp.CreateSession("MySession"); amqp.CreateSenderLink("MySession", "MySenderLink", "AzureQueue"); amqp.Message.Value = messageValue; amqp.SendMessage("MySenderLink");

The Target parameter of the CreateSenderLink method should be set to the name of the queue you created in Azure Portal. The Name parameter of the CreateSenderLink method can be set to any name that identifies the send link. The Name property of the CreateSession method can be set to any name that identifies the session.

That's it! Messages are sent by setting the Message property and by passing the name of the sender link to the SendMessage method.

Consumer client

amqp.OnMessageIn += (obj, evt) => { Console.WriteLine("Message received. Id = " + evt.MessageId); }; amqp.ContainerId = "MyContainer"; amqp.RemoteHost = "nsoftware.servicebus.windows.net"; amqp.RemotePort = 5671; amqp.SSLEnabled = true; amqp.AuthScheme = AmqpAuthSchemes.smSASLPlain; amqp.User = "RootManageSharedAccessKey"; amqp.Password = "hA8s+pCW0I71DBS6uNclP4tRcwhTUvP5wYENXB5TaIY="; amqp.Connected = true; amqp.CreateSession("MySession"); amqp.CreateReceiverLink("MySession", "MyReceiverLink", "AzureQueue");

The Source parameter of the CreateReceiverLink method should be set to the name of the queue you created in Azure Portal. The Name parameter of the CreateReceiverLink method can be set to any name that identifies the receive link. The Name parameter of the CreateSession method can be set to any name that identifies the session.

That's it! Messages are received by handling the OnMessageIn event.

Topics and Subscriptions

Service Bus topics and subscriptions are a one-to-many form of communication that use a publish/subscribe communication model. In contrast with queues, a message sent to a topic is made available to each subscription to handle and process independently.

A topic can be created in the main namespace window in the Azure Portal. Once a topic has been created it will be added to the topic list under the Entities tab:

Clicking on a topic in the list will take you to the topic window. It is there that you can add subscriptions to the topic.

Publishing Client

amqp.ContainerId = "MyContainer"; amqp.RemoteHost = "nsoftware.servicebus.windows.net"; amqp.RemotePort = 5671; amqp.SSLEnabled = true; amqp.AuthScheme = AmqpAuthSchemes.smSASLPlain; amqp.User = "RootManageSharedAccessKey"; amqp.Password = "hA8s+pCW0I71DBS6uNclP4tRcwhTUvP5wYENXB5TaIY="; amqp.Connected = true; amqp.CreateSession("MySession"); amqp.CreateSenderLink("MySession", "MySenderLink", "AzureTopic"); amqp.Message.Value = messageValue; amqp.SendMessage("MySenderLink");

A publishing client is nearly identical to a Producer client in Service Bus queues. The Target parameter of the CreateSenderLink method should be set to the name of the Topic in your Azure Portal.

Subscription Client

amqp.OnMessageIn += (obj, evt) => { Console.WriteLine("Message received. Id = " + evt.MessageId); }; amqp.ContainerId = "MyContainer"; amqp.RemoteHost = "nsoftware.servicebus.windows.net"; amqp.RemotePort = 5671; amqp.SSLEnabled = true; amqp.AuthScheme = AmqpAuthSchemes.smSASLPlain; amqp.User = "RootManageSharedAccessKey"; amqp.Password = "hA8s+pCW0I71DBS6uNclP4tRcwhTUvP5wYENXB5TaIY="; amqp.Connected = true; amqp.CreateSession("MySession"); amqp.CreateReceiverLink("MySession", "AzureSubscriber1", "AzureTopic");

The Source parameter of the CreateReceiverLink method should be set to the name of the Topic in your Azure Portal. The Name parameter of the CreateReceiverLink method must be set to the name of a subscription on the topic (the subscriptions must be registered on a topic before a receive link can be created). The Name parameter of the CreateSession method can be set to any name that identifies the session.

That is all that is required to implement brokered messaging with the AMQP component.

Azure Topic and Subscriptions Example:

Sample Code

• Producer and consumer applications for Azure Service Bus Queues
• Publishing and subscription applications for Azure Service Bus Topics and Subscriptions