.NET Aspire Azure Event Hubs интеграция

Из этой статьи вы узнаете, как использовать интеграцию .NET AspireAzure Event Hubs. Библиотека Aspire.Azure.Messaging.EventHubs предоставляет возможности для регистрации следующих типов:

• EventHubProducerClient
• EventHubBufferedProducerClient
• EventHubConsumerClient
• EventProcessorClient
• PartitionReceiver

Эти типы регистрируются в контейнере DI для подключения к Azure Event Hubs.

Необходимые условия

• подписка Azure: создать ее бесплатно.
• Azure Event Hubs пространство имен: дополнительные сведения см. в разделе о добавлении пространства имен для Центров событий. Кроме того, можно использовать строку подключения, которая не рекомендуется в рабочих средах.

Начало работы

Чтобы приступить к работе с интеграцией .NET AspireAzure Event Hubs, установите пакет NuGet 📦Aspire.Azure. Messaging.EventHubs в проект, использующий client, то есть, это проект для приложения, использующего Azure Event Hubsclient.

.NET CLI (интерфейс командной строки)

dotnet add package Aspire.Azure.Messaging.EventHubs

PackageReference

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

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в .NET applications.

Клиенты с поддержкой классов опций

Следующие клиенты поддерживаются библиотекой вместе с соответствующими параметрами и классами параметров:

тип AzureClient	Класс options Azure	класс параметров .NET.NET Aspire
EventHubProducerClient	EventHubProducerClientOptions	AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient	EventHubBufferedProducerClientOptions	AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient	EventHubConsumerClientOptions	AzureMessagingEventHubsConsumerSettings
EventProcessorClient	EventProcessorClientOptions	AzureMessagingEventHubsProcessorSettings
PartitionReceiver	PartitionReceiverOptions	AzureMessagingEventHubsPartitionReceiverSettings

Тип client из пакета SDK Azure для .NET, как и соответствующие классы параметров. Классы параметров предоставляются библиотекой интеграции .NET AspireAzure Event Hubs.

Пример использования

В следующем примере предполагается, что у вас есть пространство имен Azure Event Hubs и созданный концентратор событий и хотите настроить EventHubProducerClient для отправки событий в Концентратор событий. EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorClientи PartitionReceiverнастраиваются аналогичным образом.

В файле Program.cs вашего проекта, использующего client, вызовите расширение AddAzureEventHubProducerClient, чтобы зарегистрировать EventHubProducerClient для использования через контейнер внедрения зависимостей.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

Затем можно получить экземпляр EventHubProducerClient с помощью внедрения зависимостей. Например, чтобы получить client из сервиса:

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

Для получения дополнительной информации, см. документацию Azureпо Messaging.EventHubs для примеров использования EventHubProducerClient.

Использование узла приложения

Чтобы добавить поддержку размещения концентратора событий Azure в IDistributedApplicationBuilder, установите пакет NuGet 📦Aspire.Hosting.Azure.EventHubs в проекте узла приложения.

.NET CLI

dotnet add package Aspire.Hosting.Azure.EventHubs

PackageReference

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

В вашем проекте хоста приложения добавьте подключения к Event Hubs и ресурс Event Hub и используйте соединение с помощью следующих методов:

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 расширение EventHubs для .NET Aspire версии Azure поддерживает запуск локального эмулятора для EventHubs. Эмулятор можно использовать, применяя метод расширения RunAsEmulator() следующим образом:

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

Эмулятор для Azure EventHubs приводит к запуску двух ресурсов контейнера внутри .NET Aspire, производных от имени ресурса Центров событий.

Важный

Несмотря на то что мы создаем Event Hub с помощью AddEventHub одновременно с пространством имен, начиная с версии .NET.NET Aspirepreview-5, строка подключения не будет включать свойство EntityPath, поэтому свойство EventHubName должно быть установлено в коллбэке настроек для предпочтительного client. Будущие версии Aspire будут включать свойство EntityPath в строку подключения и не потребуют установки свойства EventHubName в этом сценарии.

В файле Program.csExampleServiceподключение можно использовать с помощью вызова поддерживаемых методов расширения Центров событий client:

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

Конфигурация

Библиотека .NET AspireAzure 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 AspireAzure Event Hubs поддерживает Microsoft.Extensions.Configuration. Он загружает AzureMessagingEventHubsSettings и связанные параметры, например EventProcessorClientOptions, из конфигурации с помощью префикса ключа Aspire:Azure:Messaging:EventHubs:, а затем имени конкретного client, используемого. Например, рассмотрим appsettings.json, который конфигурирует некоторые параметры для EventProcessorClient:

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

Можно также настроить тип параметров с помощью необязательного параметра Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder метода AddAzureEventProcessorClient. Например, чтобы задать идентификатор client для процессора, используемого в этом client:

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

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации логирования, трассировки и метрик, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireAzure Event Hubs использует следующие категории журналов:

• Azure.Core
• Azure.Identity

Отслеживание

Интеграция .NET AspireAzure Event Hubs будет испускать следующие действия трассировки с помощью OpenTelemetry:

• "Azure.Messaging.EventHubs.*"

Метрика

Интеграция .NET AspireAzure Event Hubs в настоящее время не поддерживает метрики по умолчанию из-за ограничений пакета SDK Azure для .NET. Если это изменится в будущем, этот раздел будет обновлен для отражения этих изменений.

См. также

• Azure Event Hubs
• интеграции .NET.NET Aspire
• .NET Aspire GitHub репозиторий