Get started with the Azure Service Bus integration

Azure Service Bus is a fully managed enterprise message broker with message queues and publish-subscribe topics. The Aspire Azure Service Bus integration enables you to connect to Azure Service Bus instances from your applications.

In this introduction, you'll see how to install and use the Aspire Azure Service Bus integrations in a simple configuration. If you already have this knowledge, see Azure Service Bus Hosting integration for full reference details.

Set up hosting integration

To begin, install the Aspire Azure Service Bus Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Service Bus resources from your Aspire hosting projects:

dotnet add package Aspire.Hosting.Azure.ServiceBus

Next, in the AppHost project, create an Azure Service Bus resource and pass it to the consuming client projects:

var builder = DistributedApplication.CreateBuilder(args);
  
var serviceBus = builder.AddAzureServiceBus("messaging");
var queue = serviceBus.AddServiceBusQueue("queue");
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(queue);
  
// After adding all resources, run the app...
  
builder.Build().Run();

The preceding code adds an Azure Service Bus resource named messaging to the AppHost project, adds a queue to it, and passes the queue connection information to the ExampleProject project.

Set up client integration

To use Azure Service Bus from your client applications, install the Aspire Azure Service Bus client integration in your client project:

dotnet add package Aspire.Azure.Messaging.ServiceBus

In the Program.cs file of your client-consuming project, call the AddAzureServiceBusClient extension method to register a ServiceBusClient for use via the dependency injection container:

builder.AddAzureServiceBusClient(connectionName: "queue");

Use injected Azure Service Bus properties

In the AppHost, when you used the WithReference method to pass an Azure Service Bus resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called queue becomes QUEUE_URI.

Use the GetValue() method to obtain these environment variables in consuming projects:

string serviceBusHost = builder.Configuration.GetValue<string>("QUEUE_HOST");
string serviceBusUri = builder.Configuration.GetValue<string>("QUEUE_URI");
string queueName = builder.Configuration.GetValue<string>("QUEUE_QUEUENAME");

Use Azure Service Bus resources in client code

After adding the ServiceBusClient, you can retrieve the client instance using dependency injection:

public class ExampleService(ServiceBusClient client)
{
    // Use client...
}

For full details on using the client integration, see Azure Service Bus Client integration.

Next steps