.NET Aspire Azure Event Hubs 集成

包含： 托管集成 —&— Client 集成

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

托管集成

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

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

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

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 模拟器。 前面的代码将名为 Azure Event Hubs 的 event-hubs 资源以及名为 messages 的事件中心添加到应用主机项目中。 WithReference 方法将连接信息传递给 ExampleService 项目。

预配生成的 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'

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

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

output eventHubsEndpoint string = event_hubs.properties.serviceBusEndpoint

output name string = event_hubs.name

前述的 Bicep 是一个配置 Azure Event Hubs 资源的模块。 此外，在单独的模块中为 Azure 资源创建角色分配：

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

param event_hubs_outputs_name string

param principalType string

param principalId string

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' existing = {
  name: event_hubs_outputs_name
}

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
}

生成的 Bicep 是一个起点，并受到 C# 中预配基础结构变化的影响。 对 Bicep 文件进行的自定义将直接被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。 这类型通过提供用于配置 Azure 资源的流畅 API 来允许自定义生成的 Bicep - ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。 例如，可以配置 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 服务。 你可以链接调用以标注你的 AzureEventHubsResource 现有资源：

var builder = DistributedApplication.CreateBuilder(args);

var existingEventHubsName = builder.AddParameter("existingEventHubsName");
var existingEventHubsResourceGroup = builder.AddParameter("existingEventHubsResourceGroup");

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                    .AsExisting(existingEventHubsName, existingEventHubsResourceGroup);

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

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

有关将 Azure Event Hubs 资源视为现有资源的详细信息，请参阅 “使用现有 Azure 资源”。

添加事件中心使用者组

若要添加使用者组，请将对 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的使用者组。 使用者组是在您之前添加的 Azure Event Hubs 表示的 AzureEventHubsResource 命名空间中创建的。 有关详细信息，请参阅 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配置事件中心模拟器容器时，会公开以下终结点：

默认情况下，侦听的端口是动态的。 容器启动时，端口将映射到主机上的随机端口。 若要配置终结点端口，请对 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 事件模拟器容器的端口映射到主机端口，如下表所示：

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

若要将数据卷添加到事件中心模拟器资源，请在事件中心模拟器资源上调用 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...

前面的代码将事件中心模拟器容器配置为使用位于 JSON的自定义 ./messaging/custom-config.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 包。

dotnet add package Aspire.Azure.Messaging.EventHubs

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

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

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

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

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

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

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

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

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

有关详细信息，请参阅：

• Azure
• .NET 中的依赖项注入（了解依赖项注入的详细信息）。

要考虑的其他 API

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

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

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

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

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

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

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

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

要考虑的其他关键 API

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

上述所有 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"
            }
          }
        }
      }
    }
  }
}

有关完整的 Azure Event Hubs 客户端集成 JSON 架构，请参阅 Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json。

使用命名配置

该 .NET AspireAzure Event Hubs 库支持命名配置，允许你使用不同的设置配置同一客户端类型的多个实例。 命名配置使用连接名称作为特定客户端配置部分下的密钥。

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

在此示例中，当调用processor1时，可以使用processor2和AddAzureEventProcessorClient作为连接名称。

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

命名配置优先于顶级配置。 如果同时提供这两种设置，则命名配置中的设置将替代顶级设置。

你还可以使用 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 for Azure Event Hubs 限制的缘故，Azure.NET 集成目前默认不支持这些指标。 如果将来发生此更改，将更新此部分以反映这些更改。

另请参阅

• Azure Event Hubs
• .NET Aspire Azure 集成概述
• .NET .NET Aspire 集成
• .NET Aspire GitHub 存储库