.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 Hubsclient이 사용하는 애플리케이션의 프로젝트, 즉 client을 참조하는 프로젝트에 설치됩니다.

dotnet add package Aspire.Azure.Messaging.EventHubs

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

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

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

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

client 유형과 해당 옵션 클래스는 모두 .NET용 Azure SDK에서 가져옵니다. 설정 클래스는 .NET AspireAzure Event Hubs 통합 라이브러리에서 제공됩니다.

예제 사용

다음 예제에서는 Azure Event Hubs 네임스페이스와 Event Hub를 만들고 이벤트 허브에 이벤트를 보내도록 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사용 예제를에서 확인할 수 있습니다.

앱 호스트 사용

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

dotnet add package Aspire.Hosting.Azure.EventHubs

<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 메서드는 해당 연결 정보를 ExampleService 프로젝트의 eventHubsConnectionName 연결 문자열에 전달합니다.

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

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

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

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

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)을 로드한 후, 사용 중인 특정 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 Aspire Azure Event Hubs 통합은 다음 로그 범주를 사용합니다.

• Azure.Core
• Azure.Identity

추적

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

• "Azure.Messaging.EventHubs.*"

측정 지표

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

참고 항목

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