.NET용 Azure Event Hubs 클라이언트 라이브러리 - 버전 5.8.1

  • 아티클

Azure Event Hubs 초당 수백만 개의 이벤트를 수집하고 여러 소비자에게 스트리밍할 수 있는 확장성이 뛰어난 게시 구독 서비스입니다. 이렇게 하면 연결된 디바이스 및 애플리케이션에서 생성되는 대량의 데이터를 처리하고 분석할 수 있습니다. Event Hubs가 데이터를 수집하면 실시간 분석 공급자 또는 일괄 처리/스토리지 어댑터를 사용하여 데이터를 검색, 변환 및 저장할 수 있습니다. Azure Event Hubs 대해 자세히 알아보려면 Event Hubs란?을 검토할 수 있습니다.

Azure Event Hubs 클라이언트 라이브러리를 사용하면 Azure Event Hubs 이벤트를 게시하고 사용할 수 있으며 다음을 수행할 수 있습니다.

  • 비즈니스 인텔리전스 및 진단 목적으로 애플리케이션에 대한 원격 분석을 내보냅니다.

  • 이해 당사자가 관찰하고 작업을 수행하기 위한 트리거로 사용할 수 있는 애플리케이션 상태에 대한 사실을 게시합니다.

  • 느슨하게 연결된 시스템을 함께 묶을 필요 없이 상호 작용할 수 있도록 비즈니스 또는 기타 에코시스템 내에서 일어나는 흥미로운 작업 및 상호 작용을 관찰합니다.

  • 하나 이상의 게시자로부터 이벤트를 수신하고 에코시스템의 요구 사항을 더 잘 충족하도록 변환한 다음, 소비자가 관찰할 수 있도록 변환된 이벤트를 새 스트림에 게시합니다.

소스 코드 | 패키지(NuGet) | API 참조 설명서 | 제품 설명서 | 마이그레이션 가이드 | 문제 해결 가이드

시작

필수 조건

  • Azure 구독: Azure Event Hubs 포함한 Azure 서비스를 사용하려면 구독이 필요합니다. 기존 Azure 계정이 없는 경우 평가판에 등록하거나 계정을 만들 때 Visual Studio 구독 혜택을 사용할 수 있습니다.

  • Event Hubs 네임스페이스와 이벤트 허브: Azure Event Hubs 상호 작용하려면 네임스페이스 및 이벤트 허브도 사용할 수 있어야 합니다. Azure 리소스를 만드는 데 익숙하지 않은 경우 Azure Portal 사용하여 이벤트 허브를 만들기 위한 단계별 가이드를 따를 수 있습니다. 또한 Azure CLI, Azure PowerShell 또는 ARM(Azure Resource Manager) 템플릿을 사용하여 이벤트 허브를 만들기 위한 자세한 지침을 찾을 수 있습니다.

  • C# 8.0: Azure Event Hubs 클라이언트 라이브러리는 C# 8.0에서 도입된 새로운 기능을 사용합니다. C# 8.0 구문을 활용하려면 언어 버전latest이 인 .NET Core SDK 3.0 이상을 사용하여 컴파일하는 것이 좋습니다.

    C# 8.0 구문을 최대한 활용하려는 Visual Studio 사용자는 Visual Studio 2019 이상을 사용해야 합니다. 체험 Community 버전을 비롯한 Visual Studio 2019는 여기서 다운로드할 수 있습니다. Visual Studio 2017 사용자는 Microsoft.Net.Compilers NuGet 패키지를 사용하고 언어 버전을 설정하여 C# 8 구문을 활용할 수 있지만 편집 환경은 이상적이지 않을 수 있습니다.

    이전 C# 언어 버전에서 라이브러리를 계속 사용할 수 있지만 새 구문의 이점을 활용하지 않고 비동기 열거 가능 및 비동기 일회용 멤버를 수동으로 관리해야 합니다. 이전 버전의 .NET Core 또는 .NET Framework를 포함하여 .NET Core SDK에서 지원하는 모든 프레임워크 버전을 대상으로 지정할 수 있습니다. 자세한 내용은 대상 프레임워크를 지정하는 방법을 참조하세요.
    중요 참고 사항:예제 와 샘플을 수정하지 않고 빌드하거나 실행하려면 C# 11.0을 사용해야 합니다. 다른 언어 버전에 맞게 조정하려는 경우에도 샘플을 실행할 수 있습니다. 이러한 작업의 예는 이전 언어 버전 샘플에서 사용할 수 있습니다.

Azure에서 기본 Event Hubs 리소스 집합을 빠르게 만들고 이에 대한 연결 문자열을 받으려면 다음을 클릭하여 샘플 템플릿을 배포할 수 있습니다.

Azure에 배포

패키지 설치

NuGet을 사용하여 .NET용 Azure Event Hubs 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.Messaging.EventHubs

클라이언트 인증

Event Hubs 클라이언트 라이브러리가 이벤트 허브와 상호 작용하려면 Event Hubs에 연결하고 권한을 부여하는 방법을 이해해야 합니다. 이렇게 하는 가장 쉬운 방법은 Event Hubs 네임스페이스를 만들 때 자동으로 만들어지는 연결 문자열을 사용하는 것입니다. Event Hubs에서 연결 문자열을 사용하는 데 익숙하지 않은 경우 단계별 가이드에 따라 Event Hubs 연결 문자열을 가져올 수 있습니다.

주요 개념

  • 이벤트 허브 클라이언트는 Event Hubs 클라이언트 라이브러리와 상호 작용하는 개발자를 위한 기본 인터페이스입니다. 이벤트 게시 또는 소비와 같은 Event Hubs의 특정 용도에만 사용되는 여러 이벤트 허브 클라이언트가 있습니다.

  • 이벤트 허브 생산자는 원격 분석 데이터, 진단 정보, 사용 현황 로그 또는 기타 로그 데이터의 원본으로 사용되는 클라이언트 유형으로, 포함된 디바이스 솔루션, 모바일 디바이스 애플리케이션, 콘솔 또는 다른 디바이스에서 실행되는 게임 타이틀, 일부 클라이언트 또는 서버 기반 비즈니스 솔루션 또는 웹 사이트에 포함됩니다.

  • 이벤트 허브 소비자는 이벤트 허브에서 정보를 읽고 그 처리를 허용하는 클라이언트 유형입니다. 처리에는 집계, 복잡한 계산, 필터링이 포함될 수 있습니다. 또한 처리에 원시 또는 변환된 방식으로 정보를 배포하거나 저장하는 작업이 포함될 수도 있습니다. 이벤트 허브 소비자는 Azure Stream Analytics, Apache Spark, Apache Storm 같은 기본 제공 분석 기능이 있는 강력하고 확장성이 뛰어난 플랫폼 인프라 부분인 경우가 많습니다.

  • 파티션은 이벤트 허브에 보관되는 순서가 지정된 이벤트 시퀀스입니다. 파티션은 이벤트 소비자에게 필요한 병렬 처리와 관련된 데이터 조직의 수단입니다. Azure Event Hubs는 각 소비자가 메시지 스트림의 특정 하위 집합 또는 파티션만 읽는 분할된 소비자 패턴을 통해 메시지 스트리밍을 제공합니다. 최신 이벤트가 도착하면 이 시퀀스의 끝에 추가됩니다. 파티션 수는 이벤트 허브를 만들 때 지정되며 변경할 수 없습니다.

  • 소비자 그룹은 전체 이벤트 허브의 보기입니다. 소비자 그룹을 통해 데이터를 사용하는 여러 애플리케이션이 각각 개별 이벤트 스트림 보기를 사용할 수 있으며 고유한 위치에서 고유한 속도로 독립적으로 스트림을 읽을 수 있습니다. 소비자 그룹당 파티션에는 최대 5개의 동시 reader가 있을 수 있습니다. 그러나 지정된 파티션 및 소비자 그룹 페어링에 대해 활성 소비자가 하나만 있는 것이 좋습니다. 각 활성 reader는 해당 파티션의 모든 이벤트를 수신합니다. 동일한 파티션에 여러 reader가 있는 경우 중복된 이벤트를 수신합니다.

더 많은 개념과 심층적인 논의는 Event Hubs 기능을 참조하세요.

클라이언트 수명

각 Event Hubs 클라이언트 유형은 이벤트를 정기적으로 게시하거나 읽을 때 모범 사례인 애플리케이션 수명 동안 캐시하고 싱글톤으로 사용하는 것이 안전합니다. 클라이언트는 네트워크, CPU 및 메모리 사용을 효율적으로 관리하여 비활성 기간 동안 사용량을 낮게 유지하는 작업을 담당합니다. CloseAsync 네트워크 리소스 및 기타 관리되지 않는 개체가 제대로 정리되도록 하려면 클라이언트에서 또는 DisposeAsync 를 호출해야 합니다.

스레드로부터의 안전성

모든 클라이언트 instance 메서드가 스레드로부터 안전하고 서로 독립적임을 보장합니다(지침). 이렇게 하면 스레드 간에도 클라이언트 인스턴스를 다시 사용하는 것이 항상 안전합니다.

및 EventDataBatch 와 같은 EventData 데이터 모델 형식은 스레드로부터 안전하지 않습니다. 스레드 간에 공유하거나 클라이언트 메서드와 동시에 사용해서는 안 됩니다.

추가 개념

클라이언트 옵션 | 오류 | 처리 진단 | 조롱

예제

이벤트 허브 검사

많은 이벤트 허브 작업은 특정 파티션 범위 내에서 수행됩니다. 파티션은 이벤트 허브가 소유하므로 생성 시 해당 이름이 할당됩니다. 사용할 수 있는 파티션을 이해하려면 이벤트 허브 클라이언트 중 하나를 사용하여 이벤트 허브를 쿼리합니다. 예를 들어 다음 예제에서는 EventHubProducerClient를 보여 주지만 개념 및 형식은 클라이언트 간에 공통적입니다.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    string[] partitionIds = await producer.GetPartitionIdsAsync();
}

이벤트 허브에 이벤트 게시

이벤트를 게시하려면 EventHubProducerClient를 만들어야 합니다. 생산자는 이벤트를 일괄 처리로 게시하고 특정 파티션을 요청하거나 Event Hubs 서비스가 게시할 파티션 이벤트를 결정하도록 허용할 수 있습니다. 이벤트 게시를 고가용성으로 사용해야 하거나 파티션 간에 이벤트 데이터를 균등하게 분산해야 하는 경우 자동 라우팅을 사용하는 것이 좋습니다. 예제에서는 자동 라우팅을 활용합니다.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

이벤트 허브에서 이벤트 읽기

이벤트 허브에서 이벤트를 읽으려면 특정 소비자 그룹에 대한 EventHubConsumerClient를 만들어야 합니다. 이벤트 허브를 만들면 이벤트 허브 탐색을 시작하는 데 사용할 수 있는 기본 소비자 그룹을 제공합니다. 예제에서는 반복기를 사용하여 이벤트 허브에 게시된 모든 이벤트를 읽는 데 초점을 맞춥니다.

참고: 이 사용 방법은 Event Hubs 클라이언트 라이브러리를 탐색하고 프로토타입을 만드는 환경을 개선하기 위한 것입니다. 프로덕션 시나리오에서는 사용하지 않는 것이 좋습니다. 프로덕션에서는 보다 강력하고 성능의 환경을 제공하는 이벤트 프로세서 클라이언트를 사용하는 것이 좋습니다.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync(cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the Event Hub.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

이벤트 허브 파티션에서 이벤트 읽기

이벤트 허브 파티션에 대한 이벤트를 읽으려면 지정된 소비자 그룹에 대한 을 만들어야 EventHubConsumerClient 합니다. 이벤트 허브를 만들면 이벤트 허브 탐색을 시작하는 데 사용할 수 있는 기본 소비자 그룹을 제공합니다. 특정 파티션에서 읽으려면 소비자는 이벤트 스트림에서 이벤트 수신을 시작할 위치를 지정해야 합니다. 이 예제에서는 이벤트 허브의 첫 번째 파티션에 대해 게시된 모든 이벤트를 읽는 데 집중합니다.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    EventPosition startingPosition = EventPosition.Earliest;
    string partitionId = (await consumer.GetPartitionIdsAsync()).First();

    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsFromPartitionAsync(partitionId, startingPosition, cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the partition.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

이벤트 프로세서 클라이언트를 사용하여 이벤트 처리

대부분의 프로덕션 시나리오에서는 이벤트 프로세서 클라이언트 를 사용하여 이벤트를 읽고 처리하는 것이 좋습니다. 프로세서는 상태를 유지하는 수단을 제공하면서 성능 및 내결함성 방식으로 이벤트 허브의 모든 파티션에서 이벤트를 처리하기 위한 강력한 환경을 제공하기 위한 것입니다. 또한 이벤트 프로세서 클라이언트는 지정된 Event Hub에 대한 소비자 그룹의 컨텍스트 내에서 협조적으로 작업할 수 있습니다. 여기서 인스턴스를 사용할 수 있거나 그룹에 사용할 수 없게 되면 작업의 배포 및 분산을 자동으로 관리합니다.

EventProcessorClient는 상태의 지속성을 위해 Azure Storage Blob에 의존하기 때문에 사용해야 하는 스토리지 계정 및 컨테이너에 대해 구성된 프로세서에 대한 BlobContainerClient를 제공해야 합니다.

var cancellationSource = new CancellationTokenSource();
cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";

var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";

Task processEventHandler(ProcessEventArgs eventArgs) => Task.CompletedTask;
Task processErrorHandler(ProcessErrorEventArgs eventArgs) => Task.CompletedTask;

var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);

processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;

await processor.StartProcessingAsync();

try
{
    // The processor performs its work in the background; block until cancellation
    // to allow processing to take place.

    await Task.Delay(Timeout.Infinite, cancellationSource.Token);
}
catch (TaskCanceledException)
{
    // This is expected when the delay is canceled.
}

try
{
    await processor.StopProcessingAsync();
}
finally
{
    // To prevent leaks, the handlers should be removed when processing is complete.

    processor.ProcessEventAsync -= processEventHandler;
    processor.ProcessErrorAsync -= processErrorHandler;
}

자세한 내용은 이벤트 프로세서 클라이언트 추가 정보 및 함께 제공되는 샘플에서 확인할 수 있습니다.

Event Hub 클라이언트에서 Active Directory 보안 주체 사용

Azure ID 라이브러리는 Event Hubs를 포함하여 Azure 클라이언트 라이브러리에 사용할 수 있는 Azure Active Directory 인증 지원을 제공합니다.

Active Directory 보안 주체를 사용하기 위해 Event Hubs 클라이언트를 Azure.Identity 만들 때 라이브러리에서 사용 가능한 자격 증명 중 하나가 지정됩니다. 또한 정규화된 Event Hubs 네임스페이스와 원하는 Event Hub의 이름은 Event Hubs 연결 문자열 대신 제공됩니다. 예를 들어 다음 예제에서는 EventHubProducerClient를 보여 주지만 개념 및 형식은 클라이언트 간에 공통적입니다.

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();

await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Azure Active Directory를 사용하는 경우 주체에 역할과 같은 Azure Event Hubs Data Owner Event Hubs에 대한 액세스를 허용하는 역할이 할당되어야 합니다. Event Hubs에서 Azure Active Directory 권한 부여를 사용하는 방법에 대한 자세한 내용은 관련 설명서를 참조하세요.

문제 해결

자세한 문제 해결 정보는 Event Hubs 문제 해결 가이드를 참조하세요.

로깅 및 진단

Event Hubs 클라이언트 라이브러리는 .NET EventSource 을 사용하여 정보를 내보내는 다양한 수준의 세부 정보로 정보를 로깅하기 위해 완전히 계측됩니다. 로깅은 각 작업에 대해 수행되며 작업의 시작점, 완료 및 발생한 예외를 표시하는 패턴을 따릅니다. 인사이트를 제공할 수 있는 추가 정보는 연결된 작업의 컨텍스트에도 기록됩니다.

Event Hubs 클라이언트 로그는 "Azure-Messaging-EventHubs"라는 원본을 옵트인하거나 특성이 "AzureEventSource"인 모든 원본을 옵트인하여 사용할 수 EventListener 있습니다. Azure 클라이언트 라이브러리에서 로그를 더 Azure.Core 쉽게 캡처할 수 있도록 Event Hubs에서 사용하는 라이브러리는 을 AzureEventSourceListener제공합니다. 자세한 내용은 AzureEventSourceListener를 사용하여 Event Hubs 로그 캡처에서 찾을 수 있습니다.

Event Hubs 클라이언트 라이브러리는 Application Insights 또는 OpenTelemetry를 사용하여 분산 추적을 위해 계측됩니다. 자세한 내용은 Azure.Core 진단 샘플에서 찾을 수 있습니다.

다음 단계

설명된 소개 시나리오 외에도 Azure Event Hubs 클라이언트 라이브러리는 Azure Event Hubs 서비스의 전체 기능 집합을 활용하는 데 도움이 되는 추가 시나리오를 지원합니다. 이러한 시나리오 중 일부를 탐색하는 데 도움이 되도록 Event Hubs 클라이언트 라이브러리는 일반적인 시나리오에 대한 그림으로 사용할 샘플 프로젝트를 제공합니다. 자세한 내용은 샘플 추가 정보를 참조하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

자세한 내용은 기여 가이드를 참조하세요.

Impressions