Get started with Relay Hybrid Connections

This tutorial provides an introduction to Azure Relay Hybrid Connections, and shows how to use Node.js to create a client application that sends messages to a corresponding listener application.

What will be accomplished

Because Hybrid Connections requires both a client and a server component, we will create two console applications in this tutorial. Here are the steps:

  1. Create a Relay namespace, using the Azure portal.
  2. Create a hybrid connection, using the Azure portal.
  3. Write a server console application to receive messages.
  4. Write a client console application to send messages.

Prerequisites

  1. Node.js.
  2. An Azure subscription.
Note

To complete this tutorial, you need an Azure account. You can activate your MSDN subscriber benefits or sign up for a free account.

1. Create a namespace using the Azure portal

If you already have a Relay namespace created, jump to the Create a hybrid connection using the Azure portal section.

  1. Log on to the Azure portal.
  2. In the left navigation pane of the portal, click New, then click Enterprise Integration, and then click Relay.
  3. In the Create namespace dialog, enter a namespace name. The system immediately checks to see if the name is available.
  4. In the Subscription field, choose an Azure subscription in which to create the namespace.
  5. In the Resource group field, choose an existing resource group in which the namespace will live, or create a new one.
  6. In Location, choose the country or region in which your namespace should be hosted.

    Create namespace

  7. Click Create. The system now creates your namespace and enables it. After a few minutes, the system provisions resources for your account.

Obtain the management credentials

  1. In the list of namespaces, click the newly created namespace name.
  2. In the namespace blade, click Shared access policies.
  3. In the Shared access policies blade, click RootManageSharedAccessKey.

    connection-info

  4. In the Policy: RootManageSharedAccessKey blade, click the copy button next to Connection string–primary key, to copy the connection string to your clipboard for later use. Paste this value into Notepad or some other temporary location.

    connection-string

  5. Repeat the previous step, copying and pasting the value of Primary key to a temporary location for later use.

2. Create a hybrid connection using the Azure portal

If you already have a hybrid connection created, jump to the Create a server application section.

Ensure that you have already created a Relay namespace, as shown here.

  1. Log on to the Azure portal.
  2. In the left navigation pane of the portal, click Relay.
  3. Select the namespace in which you would like to create the Hybrid Connection. In this case, it is mynewns.

    Create a hc

  4. In the Relay namespace blade, select Hybrid Connections, then click + Hybrid Connection.

    Select hc

  5. Enter the Hybrid Connection Name and leave the other values with their defaults.

    Select New

  6. At the bottom of the blade, click Create.

3. Create a server application (listener)

To listen and receive messages from the Relay, we will write a Node.js console application.

Create a Node.js application

Create a new JavaScript file called listener.js.

Add the Relay NPM package

Run npm install hyco-ws from a Node command prompt in your project folder.

Write some code to receive messages

  1. Add the following constant to the top of the listener.js file.

    const WebSocket = require('hyco-ws');
    
  2. Add the following constants to the listener.js file for the hybrid connection details. Replace the placeholders in brackets with the values you obtained when you created the hybrid connection.

    1. const ns - The Relay namespace. Be sure to use the fully qualified namespace name; for example, {namespace}.servicebus.windows.net.
    2. const path - The name of the hybrid connection.
    3. const keyrule - The name of the SAS key.
    4. const key - The SAS key value.
  3. Add the following code to the listener.js file:

    var wss = WebSocket.createRelayedServer(
    {
        server : WebSocket.createRelayListenUri(ns, path),
        token: WebSocket.createRelayToken('http://' + ns, keyrule, key)
    }, 
    function (ws) {
        console.log('connection accepted');
        ws.onmessage = function (event) {
            console.log(event.data);
        };
        ws.on('close', function () {
            console.log('connection closed');
        });       
    });
    
    console.log('listening');
    
    wss.on('error', function(err) {
        console.log('error' + err);
    });
    

    Here is what your listener.js file should look like:

    const WebSocket = require('hyco-ws');
    
    const ns = "{RelayNamespace}";
    const path = "{HybridConnectionName}";
    const keyrule = "{SASKeyName}";
    const key = "{SASKeyValue}";
    
    var wss = WebSocket.createRelayedServer(
        {
            server : WebSocket.createRelayListenUri(ns, path),
            token: WebSocket.createRelayToken('http://' + ns, keyrule, key)
        }, 
        function (ws) {
            console.log('connection accepted');
            ws.onmessage = function (event) {
                console.log(event.data);
            };
            ws.on('close', function () {
                console.log('connection closed');
            });       
    });
    
    console.log('listening');
    
    wss.on('error', function(err) {
        console.log('error' + err);
    });
    

4. Create a client application (sender)

To send messages to the Relay, we will write a Node.js console application.

Create a Node.js application

Create a new JavaScript file called sender.js.

Add the Relay NPM package

Run npm install hyco-ws from a Node command prompt in your project folder.

Write some code to send messages

  1. Add the following constants to the top of the sender.js file.

    const WebSocket = require('hyco-ws');
    const readline = require('readline')
        .createInterface({
            input: process.stdin,
            output: process.stdout
        });;
    
  2. Add the following constants to the sender.js file for the hybrid connection details. Replace the placeholders in brackets with the values you obtained when you created the hybrid connection.

    1. const ns - The Relay namespace. Be sure to use the fully qualified namespace name; for example, {namespace}.servicebus.windows.net.
    2. const path - The name of the hybrid connection.
    3. const keyrule - The name of the SAS key.
    4. const key - The SAS key value.
  3. Add the following code to the sender.js file:

    WebSocket.relayedConnect(
        WebSocket.createRelaySendUri(ns, path),
        WebSocket.createRelayToken('http://'+ns, keyrule, key),
        function (wss) {
            readline.on('line', (input) => {
                wss.send(input, null);
            });
    
            console.log('Started client interval.');
            wss.on('close', function () {
                console.log('stopping client interval');
                process.exit();
            });
        }
    );
    

    Here is what your sender.js file should look like:

    const WebSocket = require('hyco-ws');
    const readline = require('readline')
        .createInterface({
            input: process.stdin,
            output: process.stdout
        });;
    
    const ns = "{RelayNamespace}";
    const path = "{HybridConnectionName}";
    const keyrule = "{SASKeyName}";
    const key = "{SASKeyValue}";
    
    WebSocket.relayedConnect(
        WebSocket.createRelaySendUri(ns, path),
        WebSocket.createRelayToken('http://'+ns, keyrule, key),
        function (wss) {
            readline.on('line', (input) => {
                wss.send(input, null);
            });
    
            console.log('Started client interval.');
            wss.on('close', function () {
                console.log('stopping client interval');
                process.exit();
            });
        }
    );
    

5. Run the applications

  1. Run the server application: from a Node.js command prompt type node listener.js.
  2. Run the client application: from a Node.js command prompt type node sender.js, and enter some text.
  3. Ensure that the server application console outputs the text that was entered in the client application.

running-applications

Congratulations, you have created an end-to-end Hybrid Connections application using Node.js!

Next steps: