通过

.NET Aspire Azure Event Hubs 集成

  • 项目

本文介绍如何使用 .NET AspireAzure Event Hubs 集成。 Aspire.Azure.Messaging.EventHubs 库提供了用于注册以下类型的选项：

这些类型在 DI 容器中注册，以用于连接到 Azure Event Hubs。

先决条件

入门

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

dotnet add package Aspire.Azure.Messaging.EventHubs

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

支持具有选项类的客户端

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

Azure Client 类型 Azure Options 类 .NET .NET Aspire 设置类
EventHubProducerClient EventHubProducerClientOptions AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient EventHubBufferedProducerClientOptions AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient EventHubConsumerClientOptions AzureMessagingEventHubsConsumerSettings
EventProcessorClient EventProcessorClientOptions AzureMessagingEventHubsProcessorSettings
PartitionReceiver PartitionReceiverOptions AzureMessagingEventHubsPartitionReceiverSettings

客户端类型来自用于 .NET的 Azure SDK，相应的选项类也一样。 设置类由 .NET AspireAzure Event Hubs 集成库提供。

示例用法

以下示例假定你创建了一个 Azure Event Hubs 命名空间，并创建了一个事件中心，并希望配置 EventHubProducerClient 以将事件发送到事件中心。 EventHubBufferedProducerClient、EventHubConsumerClient、EventProcessorClient和 PartitionReceiver配置方式类似。

在客户端使用项目的 Program.cs 文件中，调用 AddAzureEventHubProducerClient 扩展，通过依赖注入容器注册一个 EventHubProducerClient 以供使用。

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

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

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

有关详细信息，请参阅 Azure.Messaging.EventHubs 文档，以获取有关使用 EventHubProducerClient的示例。

应用主机使用情况

若要将 Azure 事件中心托管支持添加到 IDistributedApplicationBuilder，请在 📦 项目中安装 AspireAzure.Hosting..EventHubs NuGet 包。

dotnet add package Aspire.Hosting.Azure.EventHubs

在应用主机项目中，添加事件中心连接和事件中心资源，并使用以下方法使用连接：

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName")
                       .AddEventHub("MyHub");

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

AddAzureEventHubs 方法将从 AppHost 的配置中（例如，从 ConnectionStrings:eventHubsConnectionName 配置密钥下的“用户机密信息”）读取连接信息。 WithReference 方法将该连接信息传递到 eventHubsConnectionName 项目中名为 ExampleService 的连接字符串中。

从 .NET Aspire 8.1 开始，Azure 的 .NET Aspire EventHubs 扩展支持为 EventHubs 启动本地模拟器。 可以通过应用 RunAsEmulator() 扩展方法来使用模拟器，如下所示：

var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName")
                       .RunAsEmulator()
                       .AddEventHub("MyHub");

Azure EventHubs 的模拟器会导致在派生自事件中心资源名称 .NET Aspire 内部启动两个容器资源。

重要

尽管我们正在创建事件中心，同时使用 AddEventHub 作为命名空间，从 .NET.NET Aspire 版本 preview-5开始，连接字符串将不会包含 EntityPath 属性，因此必须在首选客户端的设置回调中设置 EventHubName 属性。 Aspire 的未来版本将在连接字符串中包含 EntityPath 属性，并且不需要在此方案中设置 EventHubName 属性。

在 ExampleServiceProgram.cs 文件中，可以通过调用受支持的事件中心客户端扩展方法来使用连接：

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

配置

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

使用连接字符串

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

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

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

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

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

{
  "ConnectionStrings": {
    "eventHubsConnectionName": "{your_namespace}.servicebus.windows.net"
  }
}

连接字符串

或者，使用连接字符串：

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

使用配置提供程序

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

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

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

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    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 集成目前默认不支持指标。 如果将来发生此更改，将更新此部分以反映这些更改。

另请参阅