Delen via

Azure Event Hubs-clientbibliotheek voor .NET - versie 5.8.1

  • Artikel

Azure Event Hubs is een uiterst schaalbare service voor publiceren/abonneren waarmee miljoenen gebeurtenissen per seconde kunnen worden opgenomen en naar meerdere consumenten kunnen worden gestreamd. Hiermee kunt u de enorme hoeveelheden gegevens die door uw verbonden apparaten en toepassingen worden geproduceerd, verwerken en analyseren. Zodra Event Hubs de gegevens heeft verzameld, kunt u deze ophalen, transformeren en opslaan met behulp van een realtime analyseprovider of met batchverwerkings-/opslagadapters. Als u meer wilt weten over Azure Event Hubs, kunt u het volgende lezen: Wat is Event Hubs.

Met de Azure Event Hubs-clientbibliotheek kunt u gebeurtenissen van Azure Event Hubs publiceren en gebruiken. Deze kunnen worden gebruikt om:

  • Telemetrie over uw toepassing voor business intelligence en diagnostische doeleinden te verzenden;

  • Feiten te publiceren over de status van uw toepassing die geïnteresseerde partijen kunnen observeren en gebruiken als trigger om actie te ondernemen;

  • Interessante bewerkingen en interacties binnen uw bedrijf of een ander ecosysteem te observeren, zodat losjes gekoppelde systemen met elkaar kunnen communiceren zonder dat ze aan elkaar hoeven te worden gekoppeld;

  • Gebeurtenissen ontvangen van een of meer uitgevers, deze transformeren om beter te voldoen aan de behoeften van uw ecosysteem en de getransformeerde gebeurtenissen vervolgens publiceren naar een nieuwe stroom die gebruikers kunnen observeren.

Broncode | Pakket (NuGet) | API-referentiedocumentatie | Productdocumentatie | Migratiehandleiding | Gids voor probleemoplossing

Aan de slag

Vereisten

  • Azure-abonnement: Als u Azure-services wilt gebruiken, waaronder Azure Event Hubs, hebt u een abonnement nodig. Als u geen bestaand Azure-account hebt, kunt u zich registreren voor een gratis proefversie of de voordelen van uw Visual Studio Subscription gebruiken wanneer u een account maakt.

  • Event Hubs-naamruimte met een Event Hub: Als u wilt communiceren met Azure Event Hubs, moet u ook een naamruimte en Event Hub beschikbaar hebben. Als u niet bekend bent met het maken van Azure-resources, kunt u de stapsgewijze handleiding voor het maken van een Event Hub volgen met behulp van de Azure Portal. Daar vindt u ook gedetailleerde instructies voor het gebruik van de Azure CLI-, Azure PowerShell- of Arm-sjablonen (Azure Resource Manager) om een Event Hub te maken.

  • C# 8.0: De Azure Event Hubs-clientbibliotheek maakt gebruik van nieuwe functies die zijn geïntroduceerd in C# 8.0. Als u wilt profiteren van de C# 8.0-syntaxis, wordt u aangeraden te compileren met behulp van de .NET Core SDK 3.0 of hoger met een taalversie van latest.

    Visual Studio-gebruikers die volledig willen profiteren van de C# 8.0-syntaxis, moeten Visual Studio 2019 of hoger gebruiken. Visual Studio 2019, met inbegrip van de gratis Community-editie, hier worden gedownload. Gebruikers van Visual Studio 2017 kunnen profiteren van de C# 8-syntaxis door gebruik te maken van het Microsoft.Net.Compilers NuGet-pakket en de taalversie in te stellen, hoewel de bewerkingservaring mogelijk niet ideaal is.

    U kunt de bibliotheek nog steeds gebruiken met eerdere C#-taalversies, maar u moet asynchrone opsommings- en asynchrone wegwerpleden handmatig beheren in plaats van te profiteren van de nieuwe syntaxis. U kunt zich nog steeds richten op elke frameworkversie die wordt ondersteund door uw .NET Core SDK, inclusief eerdere versies van .NET Core of het .NET Framework. Zie Doelframeworks opgeven voor meer informatie.
    Belangrijke opmerking: Als u de voorbeelden en voorbeelden wilt bouwen of uitvoeren zonder wijziging, is het gebruik van C# 11.0 nodig. U kunt de voorbeelden nog steeds uitvoeren als u besluit ze aan te passen voor andere taalversies. Een voorbeeld hiervan is beschikbaar in het voorbeeld: Eerdere taalversies.

Als u snel een basisset Event Hubs-resources in Azure wilt maken en een connection string voor deze resources wilt ontvangen, kunt u onze voorbeeldsjabloon implementeren door te klikken op:

Implementeren op Azure

Het pakket installeren

Installeer de Azure Event Hubs-clientbibliotheek voor .NET met NuGet:

dotnet add package Azure.Messaging.EventHubs

De client verifiëren

Als u wilt dat de Event Hubs-clientbibliotheek kan communiceren met een Event Hub, moet deze weten hoe u verbinding kunt maken en ermee kunt autoriseren. De eenvoudigste manier om dit te doen, is het gebruik van een connection string, die automatisch wordt gemaakt bij het maken van een Event Hubs-naamruimte. Als u niet bekend bent met het gebruik van verbindingsreeksen met Event Hubs, kunt u de stapsgewijze handleiding volgen om een Event Hubs-connection string op te halen.

Belangrijkste concepten

  • Een Event Hub-client is de primaire interface voor ontwikkelaars die communiceren met de Event Hubs-clientbibliotheek. Er zijn verschillende Event Hub-clients, die elk zijn toegewezen aan een specifiek gebruik van Event Hubs, zoals het publiceren of gebruiken van gebeurtenissen.

  • Een Event Hub-producent is een type client dat fungeert als bron van telemetriegegevens, diagnostische gegevens, gebruikslogboeken of andere logboekgegevens, als onderdeel van een ingesloten apparaatoplossing, een toepassing voor mobiele apparaten, een gametitel die wordt uitgevoerd op een console of ander apparaat, een zakelijke oplossing op basis van een client of server of een website.

  • Een Event Hub-consument is een type client dat informatie uit de Event Hub leest en verwerking ervan toestaat. Verwerking kan bestaan uit aggregatie, complexe berekeningen en filteren. Verwerking kan ook betrekking hebben op de distributie of opslag van de informatie op onbewerkte of getransformeerde wijze. Event Hub-gebruikers zijn vaak robuuste en grootschalige platforminfrastructuuronderdelen met ingebouwde analysemogelijkheden, zoals Azure Stream Analytics, Apache Spark of Apache Storm.

  • Een partitie is een geordende reeks gebeurtenissen die wordt gehouden in een Event Hub. Partities zijn een methode voor gegevensorganisatie die is gekoppeld aan de parallelle uitvoering die is vereist door gebeurtenisgebruikers. Azure Event Hubs biedt berichtstreaming via een gepartitioneerd consumentenpatroon waarbij elke consument alleen een specifieke subset of partitie van de berichtenstroom leest. Als er nieuwere gebeurtenissen plaatsvinden, worden deze toegevoegd aan het einde van deze reeks. Het aantal partities wordt opgegeven op het moment dat een Event Hub wordt gemaakt en kan niet worden gewijzigd.

  • Een consumentengroep is een weergave van een hele Event Hub. Met consumentengroepen kunnen meerdere verbruikende toepassingen elk een afzonderlijke weergave van de gebeurtenisstroom hebben en de stream onafhankelijk in hun eigen tempo en vanuit hun eigen positie lezen. Er kunnen maximaal 5 gelijktijdige lezers op een partitie per consumentengroep zijn; Het wordt echter aanbevolen dat er slechts één actieve consument is voor een bepaalde koppeling tussen partities en consumentengroepen. Elke actieve lezer ontvangt alle gebeurtenissen van zijn partitie; Als er meerdere lezers op dezelfde partitie zijn, ontvangen ze dubbele gebeurtenissen.

Zie Functies van Event Hubs voor meer concepten en diepere discussies.

Clientlevensduur

Elk van de Event Hubs-clienttypen is veilig in de cache en te gebruiken als een singleton voor de levensduur van de toepassing. Dit is de aanbevolen procedure wanneer gebeurtenissen regelmatig worden gepubliceerd of gelezen. De clients zijn verantwoordelijk voor efficiënt beheer van het netwerk-, CPU- en geheugengebruik, waarbij het gebruik laag blijft tijdens perioden van inactiviteit. Het aanroepen van CloseAsync of DisposeAsync op een client is vereist om ervoor te zorgen dat netwerkbronnen en andere onbeheerde objecten correct worden opgeschoond.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaarmethoden thread-veilig en onafhankelijk van elkaar zijn (richtlijn). Dit zorgt ervoor dat de aanbeveling om clientexemplaren opnieuw te gebruiken altijd veilig is, zelfs voor alle threads.

De gegevensmodeltypen, zoals EventData en EventDataBatch , zijn niet thread-veilig. Ze mogen niet worden gedeeld tussen threads en mogen niet gelijktijdig met clientmethoden worden gebruikt.

Aanvullende concepten

Clientopties | Afhandeling van fouten | Diagnostics | Spottende

Voorbeelden

Een Event Hub inspecteren

Veel Event Hub-bewerkingen vinden plaats binnen het bereik van een specifieke partitie. Omdat partities eigendom zijn van de Event Hub, worden hun namen toegewezen op het moment van maken. Om te begrijpen welke partities beschikbaar zijn, voert u een query uit op de Event Hub met behulp van een van de Event Hub-clients. Ter illustratie wordt de EventHubProducerClient in deze voorbeelden gedemonstreerd, maar het concept en de vorm zijn gebruikelijk op verschillende clients.

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();
}

Gebeurtenissen publiceren naar een Event Hub

Als u gebeurtenissen wilt publiceren, moet u een EventHubProducerClientmaken. Producenten publiceren gebeurtenissen in batches en kunnen een specifieke partitie aanvragen of de Event Hubs-service toestaan om te bepalen naar welke partitiegebeurtenissen moeten worden gepubliceerd. Het wordt aanbevolen om automatische routering te gebruiken wanneer het publiceren van gebeurtenissen maximaal beschikbaar moet zijn of wanneer gebeurtenisgegevens gelijkmatig over de partities moeten worden verdeeld. In ons voorbeeld wordt gebruikgemaakt van automatische routering.

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);
}

Gebeurtenissen van een Event Hub lezen

Als u gebeurtenissen van een Event Hub wilt lezen, moet u een EventHubConsumerClient maken voor een bepaalde consumentengroep. Wanneer een Event Hub wordt gemaakt, biedt deze een standaardconsumentengroep die kan worden gebruikt om aan de slag te gaan met het verkennen van Event Hubs. In ons voorbeeld richten we ons op het lezen van alle gebeurtenissen die zijn gepubliceerd naar de Event Hub met behulp van een iterator.

Opmerking: Het is belangrijk op te merken dat deze benadering van verbruik is bedoeld om de ervaring van het verkennen van de Event Hubs-clientbibliotheek en prototyping te verbeteren. Het wordt aanbevolen deze niet te gebruiken in productiescenario's. Voor productiegebruik raden we u aan de Gebeurtenisprocessorclient te gebruiken, omdat deze een robuustere en beter presterende ervaring biedt.

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.
    }
}

Gebeurtenissen van een Event Hub-partitie lezen

Als u gebeurtenissen voor een Event Hub-partitie wilt lezen, moet u een EventHubConsumerClient maken voor een bepaalde consumentengroep. Wanneer een Event Hub wordt gemaakt, biedt deze een standaardconsumentengroep die kan worden gebruikt om aan de slag te gaan met het verkennen van Event Hubs. Als u wilt lezen van een specifieke partitie, moet de consument ook opgeven waar in de gebeurtenisstroom gebeurtenissen moeten worden ontvangen; in ons voorbeeld richten we ons op het lezen van alle gepubliceerde gebeurtenissen voor de eerste partitie van de Event Hub.

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.
    }
}

Gebeurtenissen verwerken met behulp van een gebeurtenisprocessorclient

Voor de meeste productiescenario's wordt aanbevolen dat de Gebeurtenisprocessorclient wordt gebruikt voor het lezen en verwerken van gebeurtenissen. De processor is bedoeld om een robuuste ervaring te bieden voor het verwerken van gebeurtenissen in alle partities van een Event Hub op een performante en fouttolerante manier, terwijl het een manier biedt om de status te behouden. Event Processor-clients zijn ook in staat om samen te werken binnen de context van een consumentengroep voor een bepaalde Event Hub, waar ze automatisch de distributie en taakverdeling beheren wanneer exemplaren beschikbaar of niet beschikbaar zijn voor de groep.

Omdat de EventProcessorClient afhankelijk is van Azure Storage-blobs voor persistentie van de status, moet u een BlobContainerClient opgeven voor de processor, die is geconfigureerd voor het opslagaccount en de container die moeten worden gebruikt.

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;
}

Meer informatie vindt u in leesmij voor gebeurtenisprocessorclient en de bijbehorende voorbeelden.

Een Active Directory-principal gebruiken met de Event Hub-clients

De Azure Identity-bibliotheek biedt ondersteuning voor Azure Active Directory-verificatie die kan worden gebruikt voor de Azure-clientbibliotheken, waaronder Event Hubs.

Als u gebruik wilt maken van een Active Directory-principal, wordt een van de beschikbare referenties uit de Azure.Identity bibliotheek opgegeven bij het maken van de Event Hubs-client. Daarnaast worden de volledig gekwalificeerde Event Hubs-naamruimte en de naam van de gewenste Event Hub opgegeven in plaats van de Event Hubs-connection string. Ter illustratie wordt de EventHubProducerClient in deze voorbeelden gedemonstreerd, maar het concept en de vorm zijn gebruikelijk op verschillende clients.

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);
}

Wanneer u Azure Active Directory gebruikt, moet aan uw principal een rol worden toegewezen die toegang tot Event Hubs toestaat, zoals de Azure Event Hubs Data Owner rol. Raadpleeg de bijbehorende documentatie voor meer informatie over het gebruik van Azure Active Directory-autorisatie met Event Hubs.

Problemen oplossen

Raadpleeg de Handleiding voor het oplossen van problemen met Event Hubs voor gedetailleerde informatie over het oplossen van problemen.

Logboekregistratie en diagnostische gegevens

De Event Hubs-clientbibliotheek is volledig geïnstrueerd voor het vastleggen van gegevens op verschillende detailniveaus met behulp van .NET EventSource om informatie te verzenden. Logboekregistratie wordt uitgevoerd voor elke bewerking en volgt het patroon van het markeren van het beginpunt van de bewerking, de voltooiing ervan en eventuele uitzonderingen die zijn opgetreden. Aanvullende informatie die mogelijk inzicht biedt, wordt ook vastgelegd in de context van de bijbehorende bewerking.

De Event Hubs-clientlogboeken zijn beschikbaar voor iedereen EventListener door u aan te melden voor de bron met de naam 'Azure-Messaging-EventHubs' of door u aan te melden voor alle bronnen die de eigenschap AzureEventSource hebben. Om het vastleggen van logboeken uit de Azure-clientbibliotheken gemakkelijker te maken, biedt de Azure.Core bibliotheek die wordt gebruikt door Event Hubs een AzureEventSourceListener. Meer informatie vindt u in Event Hubs-logboeken vastleggen met behulp van de AzureEventSourceListener.

De Event Hubs-clientbibliotheek is ook geïnstrueerd voor gedistribueerde tracering met behulp van Application Insights of OpenTelemetry. Meer informatie vindt u in het azure.Core Diagnostics-voorbeeld.

Volgende stappen

Naast de besproken inleidende scenario's biedt de Azure Event Hubs-clientbibliotheek ondersteuning voor aanvullende scenario's om te profiteren van de volledige functieset van de Azure Event Hubs-service. Om een aantal van deze scenario's te verkennen, biedt de Event Hubs-clientbibliotheek een project met voorbeelden als illustratie voor veelvoorkomende scenario's. Raadpleeg de voorbeelden LEESMIJ voor meer informatie.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Raadpleeg onze gids voor bijdragen voor meer informatie.

Weergaven