Edit

.NET Aspire Azure Service Bus component

  • Article

Cloud-native apps often require communication with messaging services such as Azure Service Bus. Messaging services help decouple applications and enable scenarios that rely on features such as queues, topics and subscriptions, atomic transactions, load balancing, and more. The .NET Aspire Service Bus component handles the following concerns to connect your app to Azure Service Bus:

  • A ServiceBusClient is registered in the DI container for connecting to Azure Service Bus.
  • Applies ServiceBusClient configurations either inline through code or through configuration file settings.

Prerequisites

Get started

To get started with the .NET Aspire Azure Service Bus component, install the Aspire.Azure.Messaging.ServiceBus NuGet package.

dotnet add package Aspire.Azure.Messaging.ServiceBus --prerelease

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Example usage

In the Program.cs file of your project, call the AddAzureServiceBus extension to register a ServiceBusClient for use via the dependency injection container.

builder.AddAzureServiceBus("messaging");

To retrieve the configured ServiceBusClient instance using dependency injection, require it as a constructor parameter. For example, to retrieve the client from an example service:

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

Configuration

The .NET Aspire Service Bus component provides multiple options to configure the ServiceBusClient based on the requirements and conventions of your project.

Use configuration providers

The Service Bus component supports Microsoft.Extensions.Configuration. It loads the AzureMessagingServiceBusSettings from appsettings.json or other configuration files using Aspire:Azure:Messaging:ServiceBus key.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "HealthChecks": false,
          "Tracing": true,
          "ClientOptions": {
            "Identifier": "CLIENT_ID"
          }
        }
      }
    }
  }
}

If you have set up your configurations in the Aspire:Azure:Messaging:ServiceBus section of your appsettings.json file you can just call the method AddAzureServiceBus without passing any parameters.

Use inline delegates

You can also pass the Action<AzureMessagingServiceBusSettings> delegate to set up some or all the options inline, for example to set the Namespace:

builder.AddAzureServiceBus(
    "messaging",
    static settings => settings.Namespace = "YOUR_SERVICE_BUS_NAMESPACE");

You can also set up the ServiceBusClientOptions using Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>> delegate, the second parameter of the AddAzureServiceBus method. For example to set the ServiceBusClient ID to identify the client:

builder.AddAzureServiceBus(
    "messaging",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.Identifier = "CLIENT_ID"));

Named instances

If you want to add more than one ServiceBusClient you can use named instances. Load the named configuration section from the JSON config by calling the AddAzureServiceBus method and passing in the INSTANCE_NAME.

builder.AddAzureServiceBus("INSTANCE_NAME");

The corresponding configuration JSON is defined as follows:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "INSTANCE_NAME": {
          "Namespace": "YOUR_SERVICE_BUS_NAMESPACE",
          "ClientOptions": {
            "Identifier": "CLIENT_ID"
          }
        }
      }
    }
  }
}

Configuration options

The following configurable options are exposed through the AzureMessagingServiceBusSettings class:

Name Description
ConnectionString The connection string used to connect to the Service Bus namespace.
Credential The credential used to authenticate to the Service Bus namespace.
Namespace The fully qualified Service Bus namespace.

Orchestration

In your orchestrator project, register the Service Bus component and consume the service using the following methods:

// Service registration
var serviceBus = builder.AddAzureServiceBus("messaging");

// Service consumption
builder.AddProject<Projects.ExampleProject>()
    .WithReference(serviceBus)

Health checks

By default, .NET Aspire components enable health checks for all services. For more information, see .NET Aspire components overview.

The .NET Aspire Azure Service Bus component handles the following:

  • Adds the AzureServiceBusHealthCheck health check, which attempts to connect to and query the specified service bus
  • Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic

Observability and telemetry

.NET Aspire components automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about component observability and telemetry, see .NET Aspire components overview. Depending on the backing service, some components may only support some of these features. For example, some components support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire Azure Service Bus component uses the following log categories:

  • Azure.Core
  • Azure.Identity

Tracing

The .NET Aspire Azure Service Bus component will emit the following tracing activities using OpenTelemetry:

  • Azure.Data.Tables.TableServiceClient

Metrics

The .NET Aspire Azure Service Bus component currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. If that changes in the future, this section will be updated to reflect those changes.

See also