Get started with Relay Hybrid Connections HTTP requests in .NET

In this quickstart, you create .NET sender and receiver applications that send and receive messages by using the HTTP protocol. The applications use Hybrid Connections feature of Azure Relay. To learn about Azure Relay in general, see Azure Relay.

In this quickstart, you take the following steps:

  1. Create a Relay namespace by using the Azure portal.
  2. Create a hybrid connection in that namespace by using the Azure portal.
  3. Write a server (listener) console application to receive messages.
  4. Write a client (sender) console application to send messages.
  5. Run applications.

Prerequisites

To complete this tutorial, you need the following prerequisites:

Create a namespace

  1. Sign in to the Azure portal.

  2. Select Create a resource. Then, select Integration > Relay. If you don't see Relay in the list, select See All in the top-right corner.

  3. Select Create, and enter a namespace name in the Name field. Azure portal checks to see if the name is available.

  4. Choose an Azure subscription in which to create the namespace.

  5. For Resource group, choose an existing resource group in which to place the namespace, or create a new one.

  6. Select the country or region in which your namespace should be hosted.

    Create namespace

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

Get management credentials

  1. Select All resources, and then choose the newly created namespace name.

  2. Select Shared access policies.

  3. Under Shared access policies, select RootManageSharedAccessKey.

  4. Under SAS Policy: RootManageSharedAccessKey, select the Copy button next to Primary Connection String. This action copies the connection string to your clipboard for later use. Paste this value into Notepad or some other temporary location.

  5. Repeat the preceding step to copy and paste the value of Primary key to a temporary location for later use.

    connection-string

Create a hybrid connection

Ensure that you have already created a Relay namespace.

  1. Sign in to the Azure portal.

  2. In the left menu, select All resources.

  3. Select the namespace where you want to create the hybrid connection. In this case, it is mynewns.

  4. Under Relay namespace, select Hybrid Connections.

    Create a hybrid connection

  5. In the namespace overview window, select + Hybrid Connection

    Select the hybrid connection

  6. Under Create Hybrid Connection, enter a value for the hybrid connection name. Leave the other default values.

    Select New

  7. Select Create.

Create a server application (listener)

In Visual Studio, write a C# console application to listen for and receive messages from the relay.

Create a console application

In Visual Studio, create a new Console App (.NET Framework) project.

Add the Relay NuGet package

  1. Right-click the newly created project, and then select Manage NuGet Packages.
  2. Select Include prerelease option.
  3. Select Browse, and then search for Microsoft.Azure.Relay. In the search results, select Microsoft Azure Relay.
  4. For the version, select 2.0.0-preview1-20180523.
  5. Select Install to complete the installation. Close the dialog box.

Write code to receive messages

  1. At the top of the Program.cs file, replace the existing using statements with the following using statements:

    using System;
    using System.IO;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Azure.Relay;
    using System.Net;
    
  2. Add constants to the Program class for the hybrid connection details. Replace the placeholders in brackets with the values that you obtained when you created the hybrid connection. Be sure to use the fully qualified namespace name.

    // replace {RelayNamespace} with the name of your namespace
    private const string RelayNamespace = "{RelayNamespace}.servicebus.windows.net";
    
    // replace {HybridConnectionName} with the name of your hybrid connection
    private const string ConnectionName = "{HybridConnectionName}";
    
    // replace {SAKKeyName} with the name of your Shared Access Policies key, which is RootManageSharedAccessKey by default
    private const string KeyName = "{SASKeyName}";
    
    // replace {SASKey} with the primary key of the namespace you saved earlier
    private const string Key = "{SASKey}";
    
  3. Add the RunAsync method to the Program class:

    private static async Task RunAsync()
    {
        var cts = new CancellationTokenSource();
    
        var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(KeyName, Key);
        var listener = new HybridConnectionListener(new Uri(string.Format("sb://{0}/{1}", RelayNamespace, ConnectionName)), tokenProvider);
    
        // Subscribe to the status events.
        listener.Connecting += (o, e) => { Console.WriteLine("Connecting"); };
        listener.Offline += (o, e) => { Console.WriteLine("Offline"); };
        listener.Online += (o, e) => { Console.WriteLine("Online"); };
    
        // Provide an HTTP request handler
        listener.RequestHandler = (context) =>
        {
            // Do something with context.Request.Url, HttpMethod, Headers, InputStream...
            context.Response.StatusCode = HttpStatusCode.OK;
            context.Response.StatusDescription = "OK, This is pretty neat";
            using (var sw = new StreamWriter(context.Response.OutputStream))
            {
                sw.WriteLine("hello!");
            }
    
            // The context MUST be closed here
            context.Response.Close();
        };
    
        // Opening the listener establishes the control channel to
        // the Azure Relay service. The control channel is continuously 
        // maintained, and is reestablished when connectivity is disrupted.
        await listener.OpenAsync();
        Console.WriteLine("Server listening");
    
        // Start a new thread that will continuously read the console.
        await Console.In.ReadLineAsync();
    
        // Close the listener after you exit the processing loop.
        await listener.CloseAsync();
    }
    
  4. Add the following line of code to the Main method in the Program class:

    RunAsync().GetAwaiter().GetResult();
    

    The completed Program.cs file should look like this:

    namespace Server
    {
        using System;
        using System.IO;
        using System.Threading;
        using System.Threading.Tasks;
        using Microsoft.Azure.Relay;
    
        public class Program
        {
            private const string RelayNamespace = "{RelayNamespace}.servicebus.windows.net";
            private const string ConnectionName = "{HybridConnectionName}";
            private const string KeyName = "{SASKeyName}";
            private const string Key = "{SASKey}";
    
            public static void Main(string[] args)
            {
                RunAsync().GetAwaiter().GetResult();
            }
    
            private static async Task RunAsync()
            {
                var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(KeyName, Key);
                var listener = new HybridConnectionListener(new Uri(string.Format("sb://{0}/{1}", RelayNamespace, ConnectionName)), tokenProvider);
    
                // Subscribe to the status events.
                listener.Connecting += (o, e) => { Console.WriteLine("Connecting"); };
                listener.Offline += (o, e) => { Console.WriteLine("Offline"); };
                listener.Online += (o, e) => { Console.WriteLine("Online"); };
    
                // Provide an HTTP request handler
                listener.RequestHandler = (context) =>
                {
                    // Do something with context.Request.Url, HttpMethod, Headers, InputStream...
                    context.Response.StatusCode = HttpStatusCode.OK;
                    context.Response.StatusDescription = "OK";
                    using (var sw = new StreamWriter(context.Response.OutputStream))
                    {
                        sw.WriteLine("hello!");
                    }
    
                    // The context MUST be closed here
                    context.Response.Close();
                };
    
                // Opening the listener establishes the control channel to
                // the Azure Relay service. The control channel is continuously 
                // maintained, and is reestablished when connectivity is disrupted.
                await listener.OpenAsync();
                Console.WriteLine("Server listening");
    
                // Start a new thread that will continuously read the console.
                await Console.In.ReadLineAsync();
    
                // Close the listener after you exit the processing loop.
                await listener.CloseAsync();
            }
        }
    }
    

Create a client application (sender)

In Visual Studio, write a C# console application to send messages to the relay.

Create a console application

If you have disabled the "Requires Client Authorization" option when creating the Relay, you can send requests to the Hybrid Connections URL with any browser. For accessing protected endpoints, you need to create and pass a token in the ServiceBusAuthorization header, which is shown here.

In Visual Studio, create a new Console App (.NET Framework) project.

Add the Relay NuGet package

  1. Right-click the newly created project, and then select Manage NuGet Packages.
  2. Select Include prerelease option.
  3. Select Browse, and then search for Microsoft.Azure.Relay. In the search results, select Microsoft Azure Relay.
  4. For the version, select 2.0.0-preview1-20180523.
  5. Select Install to complete the installation. Close the dialog box.

Write code to send requests

  1. At the top of the Program.cs file, replace the existing using statements with the following using statements:

    using System;
    using System.IO;
    using System.Threading;
    using System.Threading.Tasks;
    using System.Net.Http;
    using Microsoft.Azure.Relay;
    
  2. Add constants to the Program class for the hybrid connection details. Replace the placeholders in brackets with the values that you obtained when you created the hybrid connection. Be sure to use the fully qualified namespace name.

    private const string RelayNamespace = "{RelayNamespace}.servicebus.windows.net";
    private const string ConnectionName = "{HybridConnectionName}";
    private const string KeyName = "{SASKeyName}";
    private const string Key = "{SASKey}";
    
  3. Add the following method to the Program class:

    private static async Task RunAsync()
    {
        var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(
                KeyName, Key);
        var uri = new Uri(string.Format("https://{0}/{1}", RelayNamespace, ConnectionName));
        var token = (await tokenProvider.GetTokenAsync(uri.AbsoluteUri, TimeSpan.FromHours(1))).TokenString;
        var client = new HttpClient();
        var request = new HttpRequestMessage()
        {
            RequestUri = uri,
            Method = HttpMethod.Get,
        };
        request.Headers.Add("ServiceBusAuthorization", token);
        var response = await client.SendAsync(request);
        Console.WriteLine(await response.Content.ReadAsStringAsync());        Console.ReadLine();
    }
    
  4. Add the following line of code to the Main method in the Program class.

    RunAsync().GetAwaiter().GetResult();
    

    The Program.cs should look like this:

    using System;
    using System.IO;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Azure.Relay;
    
    namespace Client
    {
        class Program
        {
            private const string RelayNamespace = "{RelayNamespace}.servicebus.windows.net";
            private const string ConnectionName = "{HybridConnectionName}";
            private const string KeyName = "{SASKeyName}";
            private const string Key = "{SASKey}";
    
            static void Main(string[] args)
            {
                RunAsync().GetAwaiter().GetResult();
            }
    
            private static async Task RunAsync()
            {
               var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(
                KeyName, Key);
                var uri = new Uri(string.Format("https://{0}/{1}", RelayNamespace, ConnectionName));
                var token = (await tokenProvider.GetTokenAsync(uri.AbsoluteUri, TimeSpan.FromHours(1))).TokenString;
                var client = new HttpClient();
                var request = new HttpRequestMessage()
                {
                    RequestUri = uri,
                    Method = HttpMethod.Get,
                };
                request.Headers.Add("ServiceBusAuthorization", token);
                var response = await client.SendAsync(request);
                Console.WriteLine(await response.Content.ReadAsStringAsync());
            }
        }
    }
    

Run the applications

  1. Run the server application. You see the following text in the console window:

    Online
    Server listening
    
  2. Run the client application. You see hello! in the client window. The client sent an HTTP request to the server, and server responded with a hello!.

  3. Now, to close the console windows, press ENTER in both the console windows.

Congratulations, you've created a complete Hybrid Connections application!

Next steps

In this quickstart, you created .NET client and server applications that used HTTP to send and receive messages. The Hybrid Connections feature of Azure Relay also supports using WebSockets to send and receive messages. To learn how to use WebSockets with Azure Relay Hybrid Connections, see the WebSockets quickstart.

In this quickstart, you used .NET Framework to create client and server applications. To learn how to write client and server applications using Node.js, see the Node.js WebSockets quickstart or the Node.js HTTP quickstart.