.NET Aspire Azure Event Hubs 통합

이 문서에서는 .NET AspireAzure Event Hubs 통합을 사용하는 방법을 알아봅니다. Aspire.Azure.Messaging.EventHubs 라이브러리는 다음 형식을 등록하기 위한 옵션을 제공합니다.

• EventHubProducerClient
• EventHubBufferedProducerClient
• EventHubConsumerClient
• EventProcessorClient
• PartitionReceiver

이러한 타입은 Azure Event Hubs에 연결하기 위해 DI 컨테이너에 등록됩니다.

필수 구성 요소

• Azure 구독: 무료로 하나만드세요.
• Azure Event Hubs 네임스페이스: 자세한 내용은 을 참조하고 Event Hubs 네임스페이스 추가는를 참조하세요. 또는 프로덕션 환경에서 권장되지 않는 연결 문자열을 사용할 수 있습니다.

시작

.NET Aspire Azure Event Hubs 통합을 시작하려면 📦Aspire설치합니다.Azure. Messaging.EventHubs는 클라이언트 사용 프로젝트에서 NuGet 패키지를, 즉 Azure Event Hubs 클라이언트를 사용하는 애플리케이션용 프로젝트입니다.

.NET CLI

dotnet add package Aspire.Azure.Messaging.EventHubs

PackageReference

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

자세한 내용은 dotnet add package 또는 .NET 응용 프로그램에서 패키지 종속성 관리를 참조하십시오.

옵션 클래스를 사용하는 지원되는 클라이언트

다음 클라이언트는 해당 옵션 및 설정 클래스와 함께 라이브러리에서 지원됩니다.

Azure Client 형식	Azure 옵션 클래스	.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 네임스페이스와 Event Hub를 만들고 이벤트 허브에 이벤트를 보내도록 EventHubProducerClient 구성하려고 합니다. EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorClient및 PartitionReceiver비슷한 방식으로 구성됩니다.

클라이언트를 사용하는 프로젝트의 Program.cs 파일에서 AddAzureEventHubProducerClient 확장을 호출하여, 종속성 주입 컨테이너를 통해 사용할 EventHubProducerClient를 등록합니다.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

그런 다음 종속성 주입을 사용하여 EventHubProducerClient 인스턴스를 검색할 수 있습니다. 예를 들어 서비스에서 클라이언트를 검색하려면 다음을 수행합니다.

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

자세한 내용은 EventHubProducerClient에서 확인할 수 있습니다.

앱 호스트 사용

Azure에 IDistributedApplicationBuilder Event Hub 호스팅 지원을 추가하려면 📦 프로젝트에서 AspireAzure.Hosting..EventHubs NuGet 패키지를 설치합니다.

.NET CLI

dotnet add package Aspire.Hosting.Azure.EventHubs

PackageReference

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

앱 호스트 프로젝트에서 Event Hubs 연결 및 이벤트 허브 리소스를 추가하고 다음 방법을 사용하여 연결을 사용합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

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

AddAzureEventHubs 메서드는 ConnectionStrings:eventHubsConnectionName 구성 키 아래의 AppHost 구성(예: "사용자 비밀")에서 연결 정보를 읽습니다. WithReference 메서드는 해당 연결 정보를 eventHubsConnectionName 프로젝트의 ExampleService 연결 문자열에 전달합니다.

.NET Aspire 8.1을 기준으로 Azure용 .NET Aspire EventHubs 확장은 EventHubs에 대한 로컬 에뮬레이터 실행을 지원합니다. 다음과 같이 RunAsEmulator() 확장 메서드를 적용하여 에뮬레이터를 사용할 수 있습니다.

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

Azure EventHubs에 대한 에뮬레이터는 Event Hubs 리소스 이름에서 파생된 이름을 사용하여 .NET Aspire 내부에서 두 개의 컨테이너 리소스를 실행합니다.

중요하다

심지어 네임스페이스와 동시에 AddEventHub을 사용하여 이벤트 허브를 생성하는 경우에도, .NET.NET Aspire 버전 preview-5에서 연결 문자열에는 EntityPath 속성이 포함되지 않으므로 EventHubName 속성은 선호 클라이언트의 설정 콜백에서 설정해야 합니다. 이후 버전의 Aspire 연결 문자열에 EntityPath 속성이 포함되며 이 시나리오에서는 EventHubName 속성을 설정할 필요가 없습니다.

ExampleService의 Program.cs 파일에서, 연결은 지원되는 Event Hubs 클라이언트 확장 메서드를 호출하여 사용할 수 있습니다.

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

구성

.NET Aspire Azure Event Hubs 라이브러리는 프로젝트의 요구 사항 및 규칙에 따라 Azure Event Hubs 연결을 구성하는 여러 옵션을 제공합니다. FullyQualifiedNamespace 또는 ConnectionString 중 하나가 반드시 제공되어야 합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 builder.AddAzureEventHubProducerClient() 및 기타 지원되는 Event Hubs 클라이언트를 호출할 때 연결 문자열의 이름을 제공합니다. 이 예제에서 연결 문자열은 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 Aspire Azure Event Hubs 통합은 다음 로그 범주를 사용합니다.

• Azure.Core
• Azure.Identity

추적

.NET Aspire Azure Event Hubs 통합은 OpenTelemetry를 사용하여 다음의 추적 활동을 발생시킵니다.

• "Azure.Messaging.EventHubs.*"

측정 지표

.NET Aspire Azure Event Hubs 통합은 현재 Azure.NET SDK의 제한 사항으로 인해 기본적으로 메트릭을 지원하지 않습니다. 나중에 변경되는 경우 이 섹션은 해당 변경 내용을 반영하도록 업데이트됩니다.

참고 항목

• Azure Event Hubs
• .NET .NET Aspire 연동
• .NET Aspire GitHub 리포지토리