How to use the Service Bus WCF Relay with .NET

8 min to read Contributors
  • Seth Manheim
  • Kim Whitlatch
  • Tyson Nevil
  • John Taubensee

This article describes how to use the Service Bus relay service. The samples are written in C# and use the Windows Communication Foundation (WCF) API with extensions contained in the Service Bus assembly. For more information about the Service Bus relay, see the Service Bus relayed messaging overview.

Note

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

What is the Service Bus relay?

The Service Bus relay service enables you to build hybrid applications that run in both an Azure datacenter and your own on-premises enterprise environment. The Service Bus relay facilitates this by enabling you to securely expose Windows Communication Foundation (WCF) services that reside within a corporate enterprise network to the public cloud, without having to open a firewall connection, or requiring intrusive changes to a corporate network infrastructure.

WCF Relay Concepts

The Service Bus relay enables you to host WCF services within your existing enterprise environment. You can then delegate listening for incoming sessions and requests to these WCF services to the Service Bus service running within Azure. This enables you to expose these services to application code running in Azure, or to mobile workers or extranet partner environments. Service Bus enables you to securely control who can access these services at a fine-grained level. It provides a powerful and secure way to expose application functionality and data from your existing enterprise solutions and take advantage of it from the cloud.

This article demonstrates how to use the Service Bus relay to create a WCF web service, exposed using a TCP channel binding, that implements a secure conversation between two parties.

Create a service namespace

To begin using the Service Bus relay in Azure, you must first create a namespace. A namespace provides a scoping container for addressing Service Bus resources within your application.

To create a service namespace:

  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 Service Bus.
  3. In the Create namespace dialog, enter a namespace name. The system immediately checks to see if the name is available.
  4. After making sure the namespace name is available, choose the pricing tier (Basic, Standard, or Premium).
  5. In the Subscription field, choose an Azure subscription in which to create the namespace.
  6. In the Resource group field, choose an existing resource group in which the namespace will live, or create a new one.
  7. In Location, choose the country or region in which your namespace should be hosted.

    Create namespace

  8. Click Create. The system now creates your namespace and enables it. You might have to wait several minutes as 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

Get the Service Bus NuGet package

The Service Bus NuGet package is the easiest way to get the Service Bus API and to configure your application with all of the Service Bus dependencies. To install the NuGet package in your project, do the following:

  1. In Solution Explorer, right-click References, then click Manage NuGet Packages.
  2. Search for "Service Bus" and select the Microsoft Azure Service Bus item. Click Install to complete the installation, then close the following dialog box:

Use Service Bus to expose and consume a SOAP web service with TCP

To expose an existing WCF SOAP web service for external consumption, you must make changes to the service bindings and addresses. This may require changes to your configuration file or it could require code changes, depending on how you have set up and configured your WCF services. Note that WCF allows you to have multiple network endpoints over the same service, so you can retain the existing internal endpoints while adding Service Bus endpoints for external access at the same time.

In this task, you will build a simple WCF service and add a Service Bus listener to it. This exercise assumes some familiarity with Visual Studio, and therefore does not walk through all the details of creating a project. Instead, it focuses on the code.

Before starting these steps, complete the following procedure to set up your environment:

  1. Within Visual Studio, create a console application that contains two projects, "Client" and "Service", within the solution.
  2. Add the Microsoft Azure Service Bus NuGet package to both projects. This package adds all the necessary assembly references to your projects.

How to create the service

First, create the service itself. Any WCF service consists of at least three distinct parts:

  • Definition of a contract that describes what messages are exchanged and what operations are to be invoked.
  • Implementation of said contract.
  • Host that hosts the WCF service and exposes several endpoints.

The code examples in this section address each of these components.

The contract defines a single operation, AddNumbers, that adds two numbers and returns the result. The IProblemSolverChannel interface enables the client to more easily manage the proxy lifetime. Creating such an interface is considered a best practice. It's a good idea to put this contract definition into a separate file so that you can reference that file from both your "Client" and "Service" projects, but you can also copy the code into both projects.

using System.ServiceModel;

[ServiceContract(Namespace = "urn:ps")]
interface IProblemSolver
{
    [OperationContract]
    int AddNumbers(int a, int b);
}

interface IProblemSolverChannel : IProblemSolver, IClientChannel {}

With the contract in place, the implementation is trivial.

class ProblemSolver : IProblemSolver
{
    public int AddNumbers(int a, int b)
    {
        return a + b;
    }
}

Configure a service host programmatically

With the contract and implementation in place, you can now host the service. Hosting occurs inside a System.ServiceModel.ServiceHost object, which takes care of managing instances of the service and hosts the endpoints that listen for messages. The following code configures the service with both a regular local endpoint and a Service Bus endpoint to illustrate the appearance, side by side, of internal and external endpoints. Replace the string namespace with your namespace name and yourKey with the SAS key that you obtained in the previous setup step.

ServiceHost sh = new ServiceHost(typeof(ProblemSolver));

sh.AddServiceEndpoint(
   typeof (IProblemSolver), new NetTcpBinding(),
   "net.tcp://localhost:9358/solver");

sh.AddServiceEndpoint(
   typeof(IProblemSolver), new NetTcpRelayBinding(),
   ServiceBusEnvironment.CreateServiceUri("sb", "namespace", "solver"))
    .Behaviors.Add(new TransportClientEndpointBehavior {
          TokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider("RootManageSharedAccessKey", "<yourKey>")});

sh.Open();

Console.WriteLine("Press ENTER to close");
Console.ReadLine();

sh.Close();

In the example, you create two endpoints that are on the same contract implementation. One is local and one is projected through Service Bus. The key differences between them are the bindings; NetTcpBinding for the local one and NetTcpRelayBinding for the Service Bus endpoint and the addresses. The local endpoint has a local network address with a distinct port. The Service Bus endpoint has an endpoint address composed of the string sb, your namespace name, and the path "solver." This results in the URI sb://[serviceNamespace].servicebus.windows.net/solver, identifying the service endpoint as a Service Bus TCP endpoint with a fully qualified external DNS name. If you place the code replacing the placeholders into the Main function of the Service application, you will have a functional service. If you want your service to listen exclusively on Service Bus, remove the local endpoint declaration.

Configure a service host in the App.config file

You can also configure the host using the App.config file. The service hosting code in this case appears in the next example.

ServiceHost sh = new ServiceHost(typeof(ProblemSolver));
sh.Open();
Console.WriteLine("Press ENTER to close");
Console.ReadLine();
sh.Close();

The endpoint definitions move into the App.config file. The NuGet package has already added a range of definitions to the App.config file, which are the required configuration extensions for Service Bus. The following example, which is the exact equivalent of the previous code, should appear directly beneath the system.serviceModel element. This code example assumes that your project C# namespace is named Service. Replace the placeholders with your Service Bus service namespace and SAS key.

<services>
    <service name="Service.ProblemSolver">
        <endpoint contract="Service.IProblemSolver"
                  binding="netTcpBinding"
                  address="net.tcp://localhost:9358/solver"/>
        <endpoint contract="Service.IProblemSolver"
                  binding="netTcpRelayBinding"
                  address="sb://namespace.servicebus.windows.net/solver"
                  behaviorConfiguration="sbTokenProvider"/>
    </service>
</services>
<behaviors>
    <endpointBehaviors>
        <behavior name="sbTokenProvider">
            <transportClientEndpointBehavior>
                <tokenProvider>
                    <sharedAccessSignature keyName="RootManageSharedAccessKey" key="<yourKey>" />
                </tokenProvider>
            </transportClientEndpointBehavior>
        </behavior>
    </endpointBehaviors>
</behaviors>

After you make these changes, the service starts as it did before, but with two live endpoints: one local and one listening in the cloud.

Create the client

Configure a client programmatically

To consume the service, you can construct a WCF client using a ChannelFactory object. Service Bus uses a token-based security model implemented using SAS. The TokenProvider class represents a security token provider with built-in factory methods that return some well-known token providers. The following example uses the CreateSharedAccessSignatureTokenProvider method to handle the acquisition of the appropriate SAS token. The name and key are those obtained from the portal as described in the previous section.

First, reference or copy the IProblemSolver contract code from the service into your client project.

Then, replace the code in the Main method of the client, again replacing the placeholder text with your Service Bus namespace and SAS key.

var cf = new ChannelFactory<IProblemSolverChannel>(
    new NetTcpRelayBinding(),
    new EndpointAddress(ServiceBusEnvironment.CreateServiceUri("sb", "namespace", "solver")));

cf.Endpoint.Behaviors.Add(new TransportClientEndpointBehavior
            { TokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider("RootManageSharedAccessKey","<yourKey>") });

using (var ch = cf.CreateChannel())
{
    Console.WriteLine(ch.AddNumbers(4, 5));
}

You can now build the client and the service, run them (run the service first), and the client calls the service and prints 9. You can run the client and server on different machines, even across networks, and the communication will still work. The client code can also run in the cloud or locally.

Configure a client in the App.config file

The following code shows how to configure the client using the App.config file.

var cf = new ChannelFactory<IProblemSolverChannel>("solver");
using (var ch = cf.CreateChannel())
{
    Console.WriteLine(ch.AddNumbers(4, 5));
}

The endpoint definitions move into the App.config file. The following example, which is the same as the code listed previously, should appear directly beneath the system.serviceModel element. Here, as before, you must replace the placeholders with your Service Bus namespace and SAS key.

<client>
    <endpoint name="solver" contract="Service.IProblemSolver"
              binding="netTcpRelayBinding"
              address="sb://namespace.servicebus.windows.net/solver"
              behaviorConfiguration="sbTokenProvider"/>
</client>
<behaviors>
    <endpointBehaviors>
        <behavior name="sbTokenProvider">
            <transportClientEndpointBehavior>
                <tokenProvider>
                    <sharedAccessSignature keyName="RootManageSharedAccessKey" key="<yourKey>" />
                </tokenProvider>
            </transportClientEndpointBehavior>
        </behavior>
    </endpointBehaviors>
</behaviors>

Next steps

Now that you've learned the basics of the Service Bus relay service, follow these links to learn more.