.NET Aspire Azure Event Hubs 集成

项目
02/27/2025

Azure Event Hubs 是一种云中原生的数据流服务，每秒可以传输数百万个事件，具有低延迟的特性，从任何源到达任何目标。 .NET Aspire Azure Event Hubs 集成使你能够从 .NET 应用程序连接到 Azure Event Hubs 实例。

托管集成

托管集成 .NET.NET AspireAzure Event Hubs 将各种事件中心资源建模为以下类型：

AzureEventHubsResource：表示顶级 Azure Event Hubs 资源，用于表示中心集合以及基础 Azure 资源的连接信息。
AzureEventHubResource：表示单个事件中心资源。
AzureEventHubsEmulatorResource：将 Azure Event Hubs 模拟器表示为容器资源。
AzureEventHubConsumerGroupResource：表示事件中心资源中的使用者组。

若要访问这些类型和 API 以在应用宿主项目中表达它们，请安装 📦Aspire.Hosting.Azure.EventHubs NuGet 包：

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.EventHubs

<PackageReference Include="Aspire.Hosting.Azure.EventHubs"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖性。

添加 Azure Event Hubs 资源

若要将 AzureEventHubsResource 添加到应用主机项目，请调用提供名称的 AddAzureEventHubs 方法，然后调用 AddHub：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

将 Azure Event Hubs 资源添加到应用主机时，它会公开其他有用的 API，以添加事件中心资源、消费组、显式配置预配，并启用 Azure Event Hubs 模拟器。前面的代码将名为 event-hubs 的 Azure Event Hubs 资源以及名为 messages 的事件中心添加到应用主机项目中。 WithReference 方法将连接信息传递给 ExampleService 项目。

重要

调用 AddAzureEventHubs时，它会隐式调用 AddAzureProvisioning(IDistributedApplicationBuilder)，这增加了在应用启动期间动态生成 Azure 资源的支持。应用必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置

生成的预配 Bicep

如果你是 Bicep的新手，它是一种用于定义 Azure 资源的领域专用语言。使用 .NET.NET Aspire，你无需手动编写 Bicep，因为预配 API 会自动为你生成 Bicep。发布应用时，生成的 Bicep 文件将与清单文件一同输出。添加 Azure Event Hubs 资源时，将生成以下 Bicep：

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param sku string = 'Standard'

param principalType string

param principalId string

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' = {
  name: take('event_hubs-${uniqueString(resourceGroup().id)}', 256)
  location: location
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'event-hubs'
  }
}

resource event_hubs_AzureEventHubsDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(event_hubs.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec')
    principalType: principalType
  }
  scope: event_hubs
}

resource messages 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = {
  name: 'messages'
  parent: event_hubs
}

output eventHubsEndpoint string = event_hubs.properties.serviceBusEndpoint

前面的 Bicep 是一个模块，它预配了具有以下默认值的 Azure Event Hubs 资源：

location：资源组的位置。
sku：事件中心资源的 SKU 默认为 Standard。
principalId：事件中心资源的主体 ID。
principalType：事件中心资源的主体类型。
event_hubs：事件中心命名空间资源。
event_hubs_AzureEventHubsDataOwner：事件中心资源所有者，基于内置的 Azure Event Hubs Data Owner 角色。有关详细信息，请参阅 Azure Event Hubs 数据所有者。
messages：事件中心资源。
eventHubsEndpoint：事件中心资源的终结点。

生成的 Bicep 是一个起始点，可以根据你的具体需求进行定制。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。这种类型通过提供流畅的 API 来配置 Azure 资源，使用 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API，从而实现对生成的 Bicep 的自定义。例如，可以配置 kind、consistencyPolicy、locations等。以下示例演示如何自定义 AzureAzure Cosmos DB 资源：

builder.AddAzureEventHubs("event-hubs")
    .ConfigureInfrastructure(infra =>
    {
        var eventHubs = infra.GetProvisionableResources()
                             .OfType<EventHubsNamespace>()
                             .Single();

        eventHubs.Sku = new EventHubsSku()
        {
            Name = EventHubsSkuName.Premium,
            Tier = EventHubsSkuTier.Premium,
            Capacity = 7,
        };
        eventHubs.PublicNetworkAccess = EventHubsPublicNetworkAccess.SecuredByPerimeter;
        eventHubs.Tags.Add("ExampleKey", "Example value");
    });

前面的代码：

将一个调用链接至 ConfigureInfrastructure API：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 检索单个 EventHubsNamespace 资源。
- EventHubsNamespace.Sku 属性被分配给一个新的 EventHubsSku 实例，该实例具有 Premium 名称和层次，以及 Capacity 是 7。
- PublicNetworkAccess 属性分配给 SecuredByPerimeter。
- 标记将添加到事件中心资源，其键为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义事件中心资源资源。有关详细信息，请参阅 Azure.Provisioning.PostgreSql。有关详细信息，请参阅 Azure.Provisioning 自定义设置。

连接到现有 Azure Event Hubs 命名空间

你可能希望连接到一个现有的 Azure Event Hubs 命名空间。您可以向应用程序主机添加连接字符串，而无需创建新的 Azure Event Hubs 资源。若要向现有 Azure Event Hubs 命名空间添加连接，请调用 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddConnectionString("event-hubs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(eventHubs);

// After adding all resources, run the app...

注释

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

连接字符串是在应用主机的配置中配置的，通常在部分下的 ConnectionStrings下。应用主机将此连接字符串作为环境变量注入到所有依赖资源中，例如：

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

依赖资源可以通过调用 GetConnectionString 方法并传递连接名称作为参数来访问注入的连接字符串，在本例中为 "event-hubs"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的简称。

添加事件中心使用者组

若要添加使用者组，请将对 IResourceBuilder<AzureEventHubsResource> 的调用链接到 AddConsumerGroup API：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
var messages = eventHubs.AddHub("messages");
messages.AddConsumerGroup("messagesConsumer");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

调用 AddConsumerGroup时，它将 messages 事件中心资源配置为具有名为 messagesConsumer的使用者组。消费者组是在您之前添加的由 AzureEventHubsResource 表示的 Azure Event Hubs 命名空间中创建的。有关详细信息，请参阅 Azure Event Hubs：使用者组。

添加 Azure Event Hubs 模拟器资源

.NET Aspire Azure Event Hubs 托管集成支持基于 mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest 容器映像在本地以模拟器的形式运行事件中心资源。这适用于想要在本地运行事件中心资源以进行开发和测试的情况，避免需要预配 Azure 资源或连接到现有 Azure Event Hubs 服务器。

若要以模拟器的形式运行事件中心资源，请调用 RunAsEmulator 方法：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator();

eventHubs.AddHub("messages");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(eventHubs);

// After adding all resources, run the app...

前面的代码将 Azure Event Hubs 资源配置为在容器中本地运行。有关详细信息，请参阅 Azure Event Hubs 模拟器。

配置事件中心模拟器容器

有各种配置可用于容器资源，例如，可以配置容器的端口、数据绑定装载、数据卷，或者提供替代所有内容的专用 JSON 配置。

配置事件中心模拟器容器主机端口

默认情况下，.NET.NET Aspire配置事件中心模拟器容器时，会公开以下终结点：

端点	图像	集装箱码头	主机端口
`emulator`	`mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest`	5672	动态的

默认情况下，侦听的端口是动态的。容器启动时，端口将映射到主机上的随机端口。若要配置终结点端口，请对 RunAsEmulator 方法提供的容器资源生成器进行链式调用，然后对 WithHostPort(IResourceBuilder<AzureEventHubsEmulatorResource>, Nullable<Int32>) 进行链式调用，如以下示例所示：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithHostPort(7777);
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

前面的代码将 Azure 事件模拟器容器的现有 emulator 终结点配置为侦听端口 7777。 Azure 事件模拟器容器的端口映射到主机端口，如下表所示：

终结点名称	端口映射（`container:host`）
`emulator`	`5672:7777`

添加包含数据卷的事件中心模拟器

若要将数据卷添加到事件中心模拟器资源，请在事件中心模拟器资源上调用 WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataVolume();
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

数据卷用于在容器的生命周期之外保留事件中心模拟器数据。数据卷被挂载到容器中的 /data 路径处。除非您提供 name 的参数集，否则将随机生成一个名称。关于数据卷以及它们为何优先于绑定挂载的原因，请参阅 Docker 文档：数据卷。

添加具有数据绑定挂载的事件中心模拟器

将绑定挂载添加到事件中心模拟器容器中，并将对 WithDataBindMount API 的调用链接起来，如以下示例所示：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataBindMount("/path/to/data");
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

重要

与卷相比，绑定装载的数据功能有限，而卷提供更好的性能、可移植性和安全性，因此它们更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定装载依赖于主机的文件系统在容器重启时保留 Azure Event Hubs 模拟器资源数据。数据卷挂载点在容器中的主机的 /path/to/data 路径上。有关数据挂载绑定的详细信息，请参阅 Docker 文档：挂载绑定。

配置事件中心模拟器容器的 JSON 配置

事件中心模拟器容器使用默认 config.json 文件运行。可以完全替代此文件，也可以使用配置 JSON 表示形式更新 JsonNode 配置。

若要提供自定义 JSON 配置文件，请调用 WithConfigurationFile(IResourceBuilder<AzureEventHubsEmulatorResource>, String) 方法：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfigurationFile("./messaging/custom-config.json");
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

前面的代码将事件中心模拟器容器配置为使用位于 ./messaging/custom-config.json的自定义 JSON 配置文件。这将作为只读文件挂载到容器上的 /Eventhubs_Emulator/ConfigFiles/Config.json 路径。若要替代默认配置中的特定属性，请调用 WithConfiguration(IResourceBuilder<AzureEventHubsEmulatorResource>, Action<JsonNode>) 方法：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfiguration(
                               (JsonNode configuration) =>
                               {
                                   var userConfig = configuration["UserConfig"];
                                   var ns = userConfig["NamespaceConfig"][0];
                                   var firstEntity = ns["Entities"][0];
                                   
                                   firstEntity["PartitionCount"] = 5;
                               });
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

前面的代码从默认配置中检索 UserConfig 节点。然后，它将第一个实体的 PartitionCount 更新为 5。

托管环境集成运行状况检查

Azure Event Hubs 托管集成会自动为 Event Hubs 资源添加健康检查。运行状况检查验证事件中心是否正常运行，并能与其建立连接。

托管集成依赖于 📦 AspNetCore.HealthChecks。Azure。Messaging.EventHubs NuGet 包。

Client 集成

若要开始进行 .NET AspireAzure Event Hubs 客户端集成，请在使用事件中心客户端的应用程序项目中安装 📦Aspire.Azure.Messaging.EventHubs NuGet 包。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.EventHubs

<PackageReference Include="Aspire.Azure.Messaging.EventHubs"
                  Version="*" />

支持的事件中心客户端类型

库支持以下事件中心客户端及其相应的选项和设置类：

Azure 客户端类型	Azure 选项类	.NET .NET Aspire 设置类
EventHubProducerClient	EventHubProducerClientOptions	AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient	EventHubBufferedProducerClientOptions	AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient	EventHubConsumerClientOptions	AzureMessagingEventHubsConsumerSettings
EventProcessorClient	EventProcessorClientOptions	AzureMessagingEventHubsProcessorSettings
PartitionReceiver	PartitionReceiverOptions	AzureMessagingEventHubsPartitionReceiverSettings

客户端类型来自用于 .NET的 Azure SDK，相应的选项类也一样。设置类由 .NET.NET Aspire提供。设置类用于配置客户端实例。

添加事件中心生产者客户端

在客户端使用项目的 Program.cs 文件中，对任何 AddAzureEventHubProducerClient 调用 IHostApplicationBuilder 扩展方法，将 EventHubProducerClient 注册到依赖注入容器中以供使用。该方法采用连接名称参数。

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

小提示

connectionName 参数必须与在应用主机项目中添加事件中心资源时使用的名称匹配。有关详细信息，请参阅添加 Azure Event Hubs 资源。

添加 EventHubProducerClient后，可以使用依赖项注入检索客户端实例。例如，若要从示例服务中检索数据源对象，请将其定义为构造函数参数，并确保 ExampleService 类注册到依赖项注入容器：

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

有关详细信息，请参阅：

Azure。Messaging.EventHubs 文档有关使用 EventHubProducerClient的示例。
有关依赖项注入的详细信息，请参阅 .NET中的。

要考虑的其他 API

客户端集成提供用于配置客户端实例的其他 API。需要注册事件中心客户端时，请考虑以下 API：

Azure 客户端类型	注册 API
EventHubProducerClient	AddAzureEventHubProducerClient
EventHubBufferedProducerClient	AddAzureEventHubBufferedProducerClient
EventHubConsumerClient	AddAzureEventHubConsumerClient
EventProcessorClient	AddAzureEventProcessorClient
PartitionReceiver	AddAzurePartitionReceiverClient

上述所有 API 都包含用于配置客户端实例的可选参数。

添加键化事件中心生成者客户端

在某些情况下，可能需要使用不同的连接名称注册多个 EventHubProducerClient 实例。若要注册密钥事件中心客户端，请调用 AddKeyedAzureServiceBusClient 方法：

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

重要

使用密钥服务时，预计您的事件中心资源应配置两个命名中心，一个用于 messages，一个用于 commands。

然后，可以使用依赖项注入检索客户端实例。例如，若要从服务检索客户：

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

有关详细信息，请参阅 .NET中的键服务。

要考虑的其他关键 API

客户端集成提供用于配置密钥客户端实例的其他 API。需要注册密钥事件中心客户端时，请考虑以下 API：

Azure 客户端类型	注册 API
EventHubProducerClient	AddKeyedAzureEventHubProducerClient
EventHubBufferedProducerClient	AddKeyedAzureEventHubBufferedProducerClient
EventHubConsumerClient	AddKeyedAzureEventHubConsumerClient
EventProcessorClient	AddKeyedAzureEventProcessorClient
PartitionReceiver	AddKeyedAzurePartitionReceiverClient

上述所有 API 都包含用于配置客户端实例的可选参数。

配置

.NET Aspire Azure Event Hubs 库提供了多个选项，用于根据项目的要求和约定配置 Azure Event Hubs 连接。必须提供一个FullyQualifiedNamespace或ConnectionString。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，在调用 builder.AddAzureEventHubProducerClient() 和其他受支持的事件中心客户端时提供连接字符串的名称。在此示例中，连接字符串不包括 EntityPath 属性，因此必须在设置回调中设置 EventHubName 属性：

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

然后，将从 ConnectionStrings 配置部分检索连接信息。支持两种连接格式：

完全限定的命名空间（FQN）

建议的方法是使用命名空间的完全限定名，与 AzureMessagingEventHubsSettings.Credential 属性配合来建立连接。如果未配置凭据，则使用 DefaultAzureCredential。

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

连接字符串

或者，使用连接字符串：

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

使用配置提供程序

.NET Aspire Azure Event Hubs 库支持 Microsoft.Extensions.Configuration。它通过使用 AzureMessagingEventHubsSettings 键前缀从配置中加载 EventProcessorClientOptions 和关联的选项（例如 Aspire:Azure:Messaging:EventHubs:），以及正在使用的特定客户端的名称。例如，考虑一下用于配置 appsettings.json某些选项的 EventProcessorClient：

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

还可以使用 Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder 方法的可选 AddAzureEventProcessorClient 参数设置选项类型。例如，若要为此客户端设置处理器的客户端 ID，请执行以下操作：

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

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Azure Event Hubs 集成使用以下日志类别：

Azure.Core
Azure.Identity

追踪

.NET Aspire Azure Event Hubs 集成将使用 OpenTelemetry发出以下跟踪活动：

Azure.Messaging.EventHubs.*

指标

由于.NET Aspire SDK 在Azure Event Hubs上的限制，Azure.NET 集成目前默认不支持指标。如果将来发生此更改，将更新此部分以反映这些更改。

通过

.NET Aspire Azure Event Hubs 集成

托管集成

添加 Azure Event Hubs 资源

生成的预配 Bicep

自定义预配基础结构

连接到现有 Azure Event Hubs 命名空间

添加事件中心使用者组

添加 Azure Event Hubs 模拟器资源

配置事件中心模拟器容器

配置事件中心模拟器容器主机端口

添加包含数据卷的事件中心模拟器

添加具有数据绑定挂载的事件中心模拟器

配置事件中心模拟器容器的 JSON 配置

托管环境集成运行状况检查

Client 集成

支持的事件中心客户端类型

添加事件中心生产者客户端

要考虑的其他 API

添加键化事件中心生成者客户端

要考虑的其他关键 API

配置

使用连接字符串

完全限定的命名空间（FQN）

连接字符串

使用配置提供程序

可观测性和遥测

伐木

追踪

指标

另请参阅

其他资源

通过

.NET Aspire Azure Event Hubs 集成

托管集成

添加 Azure Event Hubs 资源

生成的预配 Bicep

自定义预配基础结构

连接到现有 Azure Event Hubs 命名空间

添加事件中心使用者组

添加 Azure Event Hubs 模拟器资源

配置事件中心模拟器容器

配置事件中心模拟器容器主机端口

添加包含数据卷的事件中心模拟器

添加具有数据绑定挂载的事件中心模拟器

配置事件中心模拟器容器的 JSON 配置

托管环境集成运行状况检查

Client 集成

支持的事件中心客户端类型

添加事件中心生产者客户端

要考虑的其他 API

添加键化事件中心生成者客户端

要考虑的其他关键 API

配置

使用连接字符串

完全限定的命名空间 （FQN）

连接字符串

使用配置提供程序

可观测性和遥测

伐木

追踪

指标

另请参阅

其他资源

完全限定的命名空间（FQN）