Azure Event Hubs Client integration

To get started with the Aspire Azure Event Hubs client integration, install the 📦 Aspire.Azure.Messaging.EventHubs NuGet package in the client-consuming project, that is, the project for the application that uses the Event Hubs client.

dotnet add package Aspire.Azure.Messaging.EventHubs

Supported Event Hubs client types

The following Event Hub clients are supported by the library, along with their corresponding options and settings classes:

The client types are from the Azure SDK for .NET, as are the corresponding options classes. The settings classes are provided by Aspire. The settings classes are used to configure the client instances.

Add an Event Hubs producer client

In the Program.cs file of your client-consuming project, call the AddAzureEventHubProducerClient extension method on any IHostApplicationBuilder to register an EventHubProducerClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureEventHubProducerClient(connectionName: "event-hubs");

After adding the EventHubProducerClient, you can retrieve the client instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

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

For more information, see:

• Azure.Messaging.EventHubs documentation for examples on using the EventHubProducerClient.
• Dependency injection in .NET for details on dependency injection.

Additional APIs to consider

The client integration provides additional APIs to configure client instances. When you need to register an Event Hubs client, consider the following APIs:

All of the aforementioned APIs include optional parameters to configure the client instances.

Properties of the Azure Event Hubs resources

When you use the WithReference method to pass an Azure Event Hubs resource from the AppHost project to a consuming client project, several properties are available to 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 eventhubs becomes EVENTHUBS_URI.

Azure Event Hubs namespace

The Azure Event Hubs namespace resource exposes the following connection properties:

In emulator mode, additional properties are available:

Azure Event Hub

The Azure Event Hub resource inherits all properties from its parent namespace and adds:

Azure Event Hub consumer group

The Azure Event Hub consumer group resource inherits all properties from its parent hub and adds:

For example, if you reference an Event Hub resource named messages in your AppHost project, the following environment variables will be available in the consuming project:

• MESSAGES_HOST
• MESSAGES_URI
• MESSAGES_EVENTHUBNAME

Add keyed Event Hubs producer client

There might be situations where you want to register multiple EventHubProducerClient instances with different connection names. To register keyed Event Hubs clients, call the AddKeyedAzureEventHubProducerClient method:

builder.AddKeyedAzureEventHubProducerClient(name: "messages");
builder.AddKeyedAzureEventHubProducerClient(name: "commands");

Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service:

public class ExampleService(
    [KeyedService("messages")] EventHubProducerClient messagesClient,
    [KeyedService("commands")] EventHubProducerClient commandsClient)
{
    // Use clients...
}

For more information, see Keyed services in .NET.

Additional keyed APIs to consider

The client integration provides additional APIs to configure keyed client instances. When you need to register a keyed Event Hubs client, consider the following APIs:

All of the aforementioned APIs include optional parameters to configure the client instances.

Configuration

The Aspire Azure Event Hubs library provides multiple options to configure the Azure Event Hubs connection based on the requirements and conventions of your project. Either a FullyQualifiedNamespace or a ConnectionString is required to be supplied.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, provide the name of the connection string when calling builder.AddAzureEventHubProducerClient() and other supported Event Hubs clients. In this example, the connection string does not include the EntityPath property, so the EventHubName property must be set in the settings callback:

builder.AddAzureEventHubProducerClient(
    "event-hubs",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

And then the connection information will be retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

Fully Qualified Namespace (FQN)

The recommended approach is to use a fully qualified namespace, which works with the Credential property to establish a connection. If no credential is configured, a default credential is used.

{
  "ConnectionStrings": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

Connection string

Alternatively, use a connection string:

{
  "ConnectionStrings": {
    "event-hubs": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub"
  }
}

Use configuration providers

The Aspire Azure Event Hubs library supports Microsoft.Extensions.Configuration. It loads the AzureMessagingEventHubsSettings and the associated Options, e.g. EventProcessorClientOptions, from configuration by using the Aspire:Azure:Messaging:EventHubs: key prefix, followed by the name of the specific client in use. For example, consider the appsettings.json that configures some of the options for an EventProcessorClient:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "EventHubName": "MyHub",
            "ClientOptions": {
              "Identifier": "PROCESSOR_ID"
            }
          }
        }
      }
    }
  }
}

For the complete Azure Event Hubs client integration JSON schema, see Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json.

Use named configuration

The Aspire Azure Event Hubs library supports named configuration, which allows you to configure multiple instances of the same client type with different settings. The named configuration uses the connection name as a key under the specific client configuration section.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "processor1": {
              "EventHubName": "MyHub1",
              "ClientOptions": {
                "Identifier": "PROCESSOR_1"
              }
            },
            "processor2": {
              "EventHubName": "MyHub2",
              "ClientOptions": {
                "Identifier": "PROCESSOR_2"
              }
            }
          }
        }
      }
    }
  }
}

In this example, the processor1 and processor2 connection names can be used when calling AddAzureEventProcessorClient:

builder.AddAzureEventProcessorClient("processor1");
builder.AddAzureEventProcessorClient("processor2");

Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings.

You can also setup the Options type using the optional Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder parameter of the AddAzureEventProcessorClient method. For example, to set the processor's client ID for this client:

builder.AddAzureEventProcessorClient(
    "event-hubs",
    configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions(
        options => options.Identifier = "PROCESSOR_ID"));

Observability and telemetry

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

Logging

The Aspire Azure Event Hubs integration uses the following log categories:

• Azure.Core
• Azure.Identity

Tracing

The Aspire Azure Event Hubs integration will emit the following tracing activities using OpenTelemetry:

• Azure.Messaging.EventHubs.*

Metrics

The Aspire Azure Event Hubs integration 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.