Gebeurtenissen verzenden naar en ontvangen van Azure Event Hubs - .NET (Azure.Messaging.EventHubs)

In deze quickstart ziet u hoe u gebeurtenissen kunt verzenden naar en ontvangen van een Event Hub met behulp van de .NET-bibliotheek Azure.Messaging.EventHubs.

Vereisten

Als u nog geen ervaring hebt met Azure Event Hubs, raadpleegt u het Event Hubs-overzicht voordat u deze quickstart uitvoert.

Voor het voltooien van deze snelstart moet aan de volgende vereisten worden voldaan:

  • Microsoft Azure-abonnement. Als u Azure-services wilt gebruiken, met inbegrip van Azure Event Hubs, hebt u een abonnement nodig. Als u nog geen Azure-account hebt, kunt u zich aanmelden voor een gratis proefversie of uw voordelen als MSDN-abonnee gebruiken wanneer u een account maakt.
  • Microsoft Visual Studio 2019. De Azure Event Hubs-clientbibliotheek maakt gebruik van nieuwe functies die in C# 8.0 zijn geïntroduceerd. U kunt de bibliotheek nog steeds gebruiken met eerdere C#-taalversies, maar de nieuwe syntaxis is niet beschikbaar. Als u gebruik wilt maken van de volledige syntaxis, raden we u aan om te compileren met de .NET Core SDK 3.0 of hoger en de taalversie ingesteld op latest. Als u Visual Studio gebruikt, weet dan dat de versies vóór Visual Studio 2019 niet compatibel met de hulpprogramma's die nodig zijn om C# 8.0 projecten te bouwen. Visual Studio 2019, met inbegrip van de gratis Community-editie, hier worden gedownload.
  • Een Event Hubs-naamruimte en een Event Hub maken. In de eerste stap gebruikt u Azure Portal om een naamruimte van het type Event Hubs te maken en de beheerreferenties te verkrijgen die de toepassing nodig heeft om met de Event Hub te communiceren. Volg de procedure in dit artikel om een naamruimte en een Event Hub te maken. Haal vervolgens de verbindingsreeks voor de Event Hubs-naamruimte op door de instructies in het artikel te volgen: Verbindingstekenreeks ophalen. U gebruikt de verbindingsreeks later in deze quickstart.

Gebeurtenissen verzenden

In deze sectie wordt beschreven hoe u een .NET Core-consoletoepassing maakt voor het verzenden van gebeurtenissen naar een Event Hub.

Een consoletoepassing maken

  1. Start Visual Studio 2019.

  2. Selecteer Een nieuw project maken.

  3. Voer in het dialoogvenster Een nieuw project maken de volgende stappen uit: Als dit dialoogvenster niet wordt weergegeven, selecteert u in het menu Bestand, Nieuw en vervolgens Project.

    1. Selecteer de programmeertaal C# .

    2. Selecteer Console als het type toepassing.

    3. Selecteer Consoletoepassing in de lijst met resultaten.

    4. Selecteer vervolgens Volgende.

      Image showing the New Project dialog box

  4. Voer EventHubsSender in als projectnaam, EventHubsQuickStart als naam van de oplossing en selecteer OK om het project te maken.

    Image showing the page where you enter solution and project names

Het Event Hubs NuGet-pakket toevoegen

  1. Selecteer Tools>NuGet-pakketbeheer>Package Manager Console in het menu.

  2. Voer de volgende opdracht uit om het NuGet-pakket Azure.Messaging.EventHubs te installeren:

    Install-Package Azure.Messaging.EventHubs
    

Code schrijven om gebeurtenissen naar de Event Hub te verzenden

  1. Voeg aan het begin van het bestand usingProgram.csde volgende-instructies toe:

    using System;
    using System.Text;
    using System.Threading.Tasks;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Producer;
    
  2. Voeg aan de Program-klasse constanten toe voor de Event Hubs-verbindingsreeks en de naam van de Event Hub.

        // connection string to the Event Hubs namespace
        private const string connectionString = "<EVENT HUBS NAMESPACE - CONNECTION STRING>";
    
        // name of the event hub
        private const string eventHubName = "<EVENT HUB NAME>";
    
        // number of events to be sent to the event hub
        private const int numOfEvents = 3;
    

    Notitie

    Vervang tijdelijke aanduidingen door de verbindingsreeks naar uw naamruimte en de naam van de Event Hub. Zorg ervoor dat de verbindingsreeks de verbindingsreeks op naamruimteniveau is.

  3. Voeg de volgende statische eigenschap toe aan de Program klasse. Bekijk de codeopmerkingen.

        // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
        // of the application, which is best practice when events are being published or read regularly.
        static EventHubProducerClient producerClient;    
    
  4. Vervang de Main-methode door de volgende async Main-methode. Zie de opmerkingen bij de code voor meer informatie. Hier volgen de belangrijke stappen uit de code.

    1. Hiermee maakt u een EventHubProducerClient-object met behulp van de primaire verbindingsreeks met de naamruimte en de naam van de Event Hub.
    2. Roept de methode CreateBatchAsync op het EventHubProducerClient-object aan om een EventDataBatch-object te maken.
    3. Voeg gebeurtenissen toe aan de batch met behulp van de methode EventDataBatch.TryAdd .
    4. Verzendt de batch berichten naar de Event Hub met behulp van de methode EventHubProducerClient.SendAsync .
        static async Task Main()
        {
            // Create a producer client that you can use to send events to an event hub
            producerClient = new EventHubProducerClient(connectionString, eventHubName);
    
            // Create a batch of events 
            using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();
    
            for (int i = 1; i <= numOfEvents; i++)
            {
                if (! eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
                {
                    // if it is too large for the batch
                    throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
                }
            }
    
            try
            {
                // Use the producer client to send the batch of events to the event hub
                await producerClient.SendAsync(eventBatch);
                Console.WriteLine($"A batch of {numOfEvents} events has been published.");
            }
            finally
            {
                await producerClient.DisposeAsync();
            }
        }
    
  5. Bouw het project en controleer of er geen fouten zijn.

  6. Voer het programma uit en wacht op het bevestigingsbericht.

    A batch of 3 events has been published.
    
  7. In Azure Portal kunt u controleren of de Event Hub de gebeurtenissen heeft ontvangen. Schakel over naar de weergave Berichten in de sectie Metrische gegevens. U moet de pagina vernieuwen om de grafiek bij te werken. Het kan een paar seconden duren voordat wordt weergegeven dat de berichten zijn ontvangen.

    Image of the Azure portal page to verify that the event hub received the events

    Notitie

    Zie dit bestand op de GitHub voor de volledige broncode met meer informatieve opmerkingen

Gebeurtenissen ontvangen

In deze sectie wordt beschreven hoe u een .NET Core-consoletoepassing schrijft die gebeurtenissen van een Event Hub ontvangt met behulp van een gebeurtenisprocessor. De gebeurtenisprocessor vereenvoudigt het ontvangen van gebeurtenissen van Event Hubs door permanente controlepunten en parallelle ontvangst van deze Event Hubs te beheren. Een gebeurtenisprocessor is gekoppeld aan een specifieke Event hub en een consumentengroep. Er worden gebeurtenissen van meerdere partities in de Event Hub ontvangen en de worden aan een handler-gemachtigde doorgegeven voor verwerking met code die u opgeeft.

Waarschuwing

Als u deze code uitvoert op Azure Stack Hub, ondervindt u runtimefouten, tenzij u zich richt op een specifieke Storage-API-versie. Dat komt doordat de Event Hubs SDK gebruikmaakt van de nieuwste beschikbare Azure Storage-API die beschikbaar is in Azure, die mogelijk niet beschikbaar is op uw Azure Stack Hub-platform. Azure Stack Hub biedt mogelijk ondersteuning voor een andere versie van de Storage Blob-SDK dan de versies die doorgaans in Azure beschikbaar zijn. Als u Azure Blob-opslag gebruikt als controlepuntopslag, controleert u de ondersteunde versie van de Azure Storage-API voor uw build van Azure Stack Hub en stelt u die versie in uw code als doel in.

Als u bijvoorbeeld op Azure Stack Hub versie 2005 uitvoert, is de hoogste beschikbare versie van de Storage-service versie 2019-02-02. De Event Hubs-SDK-clientbibliotheek maakt standaard gebruik van de hoogste beschikbare versie op Azure (2019-07-07 op het moment van de release van de SDK). In dit geval moet u naast de volgende stappen in deze sectie ook code toevoegen om de API-versie van de Storage-service te richten op 2019-02-02. Zie dit voorbeeld op GitHub voor een voorbeeld van hoe u een specifieke versie van Storage-API instelt.

Een Azure Storage en een blobcontainer maken

In deze quickstart gebruikt u Azure Storage als controlepuntopslag. Volg deze stappen om een Azure Storage-account te maken.

  1. Een Azure Storage-account maken

  2. Een blobcontainer maken

  3. De verbindingsreeks voor het opslagaccount ophalen

    Noteer de verbindingsreeks en de naam van de container. U gebruikt deze in de receive-code.

Een project maken voor de ontvanger

  1. Klik in het Solution Explorer-venster met de rechtermuisknop op de oplossing EventHubQuickStart, wijs naar Toevoegen en selecteer Nieuw project.
  2. Selecteer Consoletoepassing en selecteer Volgende.
  3. Voer EventHubsReceiver in als Projectnaam en selecteer Maken.
  4. Klik in het venster Solution Explorer met de rechtermuisknop op EventHubsReceiver en selecteer Instellen als opstartproject.

Het Event Hubs NuGet-pakket toevoegen

  1. Selecteer Tools>NuGet-pakketbeheer>Package Manager Console in het menu.

  2. Controleer in het venster Package Manager Console of EventHubsReceiver is geselecteerd voor het standaardproject. Als dat niet het geval is, gebruikt u de vervolgkeuzelijst om EventHubsReceiver te selecteren.

  3. Voer de volgende opdracht uit om het NuGet-pakket Azure.Messaging.EventHubs te installeren:

    Install-Package Azure.Messaging.EventHubs
    
  4. Voer de volgende opdracht uit om het NuGet-pakket Azure.Messaging.EventHubs.Processor te installeren:

    Install-Package Azure.Messaging.EventHubs.Processor
    

De main-methode bijwerken

  1. Voeg aan het begin van het bestand usingProgram.csde volgende-instructies toe.

    using System;
    using System.Text;
    using System.Threading.Tasks;
    using Azure.Storage.Blobs;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Consumer;
    using Azure.Messaging.EventHubs.Processor;
    
  2. Voeg aan de Program-klasse constanten toe voor de Event Hubs-verbindingsreeks en de naam van de Event Hub. Vervang de tijdelijke aanduidingen tussen de haakjes door de juiste waarden die zijn verkregen bij het maken van de Event Hub. Vervang tijdelijke aanduidingen tussen de haakjes door de juiste waarden die u hebt verkregen bij het maken van de Event Hub en het opslagaccount (toegangssleutels - primaire verbindingsreeks). Zorg ervoor dat {Event Hubs namespace connection string} de verbindingsreeks op naamruimteniveau is en niet de event hub-tekenreeks.

        private const string ehubNamespaceConnectionString = "<EVENT HUBS NAMESPACE - CONNECTION STRING>";
        private const string eventHubName = "<EVENT HUB NAME>";
        private const string blobStorageConnectionString = "<AZURE STORAGE CONNECTION STRING>";
        private const string blobContainerName = "<BLOB CONTAINER NAME>";
    
  3. Voeg de volgende statische eigenschappen toe aan de Program klasse.

        static BlobContainerClient storageClient;
    
        // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
        // of the application, which is best practice when events are being published or read regularly.        
        static EventProcessorClient processor;    
    
  4. Vervang de Main-methode door de volgende async Main-methode. Zie de opmerkingen bij de code voor meer informatie. Hier volgen de belangrijke stappen uit de code.

    1. Hiermee maakt u een EventProcessorClient-object met behulp van de primaire verbindingsreeks met de naamruimte en de Event Hub. U moet een BlobContainerClient-object bouwen voor de container in de Azure-opslag die u eerder hebt gemaakt.
    2. Hiermee geeft u handlers op voor de gebeurtenissen ProcessEventAsync en ProcessErrorAsync van het EventProcessorClient-object .
    3. Hiermee wordt gestart met het verwerken van gebeurtenissen door het StartProcessingAsync aan te roepen op het EventProcessorClient-object .
    4. Wanneer de gebruiker op een toets drukt om de verwerking te beëindigen, roept u de StopProcessingAsync aan op het EventProcessorClient-object .
        static async Task Main()
        {
            // Read from the default consumer group: $Default
            string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;
    
            // Create a blob container client that the event processor will use 
            storageClient = new BlobContainerClient(blobStorageConnectionString, blobContainerName);
    
            // Create an event processor client to process events in the event hub
            processor = new EventProcessorClient(storageClient, consumerGroup, ehubNamespaceConnectionString, eventHubName);
    
            // Register handlers for processing events and handling errors
            processor.ProcessEventAsync += ProcessEventHandler;
            processor.ProcessErrorAsync += ProcessErrorHandler;
    
            // Start the processing
            await processor.StartProcessingAsync();
    
            // Wait for 30 seconds for the events to be processed
            await Task.Delay(TimeSpan.FromSeconds(30));
    
            // Stop the processing
            await processor.StopProcessingAsync();
        }
    
  5. Voeg nu de volgende gebeurtenis- en foutafhandelingsmethoden aan de klasse toe.

        static async Task ProcessEventHandler(ProcessEventArgs eventArgs)
        {
            // Write the body of the event to the console window
            Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
    
            // Update checkpoint in the blob storage so that the app receives only new events the next time it's run
            await eventArgs.UpdateCheckpointAsync(eventArgs.CancellationToken);
        }
    
        static Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
        {
            // Write details about the error to the console window
            Console.WriteLine($"\tPartition '{ eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
            Console.WriteLine(eventArgs.Exception.Message);
            return Task.CompletedTask;
        }    
    
  6. Bouw het project en controleer of er geen fouten zijn.

    Notitie

    Zie dit bestand op de GitHub voor de volledige broncode met meer informatieve opmerkingen.

  7. Voer de ontvangende toepassing uit.

  8. U ziet een bericht dat de gebeurtenissen zijn ontvangen.

    Received event: Event 1
    Received event: Event 2
    Received event: Event 3    
    

    Deze gebeurtenissen zijn de drie gebeurtenissen die u eerder naar de Event Hub hebt verzonden door het verzendprogramma uit te voeren.

  9. In Azure Portal kunt u controleren of er drie uitgaande berichten zijn. Dit zijn de berichten die Event Hubs naar de ontvangende toepassing hebben verzonden. U moet de pagina vernieuwen om de grafiek bij te werken. Het kan een paar seconden duren voordat wordt weergegeven dat de berichten zijn ontvangen.

    Image of the Azure portal page to verify that the event hub sent events to the receiving app

Volgende stappen

Deze quickstart bevat stapsgewijze instructies voor het implementeren van een eenvoudig scenario voor het verzenden van een batch gebeurtenissen naar een Event Hub en deze vervolgens te ontvangen. Bekijk de volgende voorbeelden op GitHub voor meer voorbeelden over andere en geavanceerde scenario's.