通过

.NET Aspire Azure Event Hubs 集成

  • 项目

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

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

先决条件

入门

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

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

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

示例用法

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

在 client消耗项目的 Program.cs 文件中，调用 AddAzureEventHubProducerClient 扩展以注册 EventHubProducerClient，以便通过依赖项注入容器使用。

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

然后，可以使用依赖项注入检索 EventHubProducerClient 实例。 例如，要从某个服务中检索 client，

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

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

应用主机使用情况

若要将 Azure 事件中心托管支持添加到 IDistributedApplicationBuilder，请在 应用主机 项目中安装 📦Aspire.Hosting.Azure.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 方法将该连接信息传递到 ExampleService 项目中名为 eventHubsConnectionName 的连接字符串中。

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

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

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

重要

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

在 ExampleService的 Program.cs 文件中，可以通过调用受支持的 client 事件中心扩展方法来实现连接。

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），然后是正在使用的特定 client 的名称。 例如，考虑一下用于配置 EventProcessorClient某些选项的 appsettings.json：

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

还可以使用 AddAzureEventProcessorClient 方法的可选 Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder 参数设置选项类型。 例如，若要为此 client设置处理器的 client 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.*”

指标

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

另请参阅