Senden oder Empfangen von Ereignissen an und von Azure Event Hubs: .NET (Azure.Messaging.EventHubs)

Artikel
07/27/2022
10 Minuten Lesedauer

In dieser Schnellstartanleitung erfahren Sie, wie Sie mithilfe der .NET-Bibliothek Azure.Messaging.EventHubs Ereignisse an einen Event Hub senden bzw. von dort empfangen.

Voraussetzungen

Wenn Sie mit Azure Event Hubs noch nicht vertraut sind, lesen Sie vor dem Durcharbeiten dieser Schnellstartanleitung die Informationen unter Übersicht über Event Hubs.

Zum Durchführen dieser Schnellstartanleitung benötigen Sie Folgendes:

Microsoft Azure-Abonnement. Für die Verwendung von Azure-Diensten benötigen Sie ein Abonnement. Das gilt auch für Azure Event Hubs. Falls Sie noch nicht über ein Azure-Konto verfügen, können Sie sich für eine kostenlose Testversion registrieren oder beim Erstellen eines Kontos Ihre MSDN-Abonnentenvorteile nutzen.
Microsoft Visual Studio 2019. Die Azure Event Hubs-Clientbibliothek nutzt neue Features, die in C# 8.0 eingeführt wurden. Die Bibliothek kann zwar auch weiterhin mit älteren Versionen von C# verwendet werden, doch die neue Syntax steht dann nicht zur Verfügung. Wenn Sie die ganze Syntax nutzen möchten, sollten Sie mit dem .NET Core SDK 3.0 oder höher kompilieren, wobei die Sprachversion auf latest festgelegt sein muss. Bei Verwendung von Visual Studio sind Versionen vor Visual Studio 2019 nicht mit den Tools kompatibel, die zum Erstellen von C# 8.0-Projekten erforderlich sind. Visual Studio 2019 (einschließlich der kostenlosen Community-Edition) kann hier heruntergeladen werden.
Erstellen Sie einen Event Hubs-Namespace und einen Event Hub. Verwenden Sie zunächst das Azure-Portal, um einen Namespace vom Typ „Event Hubs“ zu erstellen, und beschaffen Sie die Verwaltungsanmeldeinformationen, die Ihre Anwendung für die Kommunikation mit dem Event Hub benötigt. Erstellen Sie anhand der Anleitung in diesem Artikel einen Namespace und einen Event Hub. Gehen Sie dann wie im folgenden Artikel beschrieben vor, um die Verbindungszeichenfolge für den Event Hubs-Namespace abzurufen: Abrufen der Verbindungszeichenfolge. Sie verwenden die Verbindungszeichenfolge im weiteren Verlauf dieser Schnellstartanleitung.

Senden von Ereignisse

In diesem Abschnitt erfahren Sie, wie Sie eine .NET Core-Anwendung zum Senden von Ereignissen an einen Event Hub erstellen.

Erstellen einer Konsolenanwendung

Starten Sie Visual Studio 2019.
Wählen Sie Neues Projekt erstellen aus.
Führen Sie im Dialogfeld Neues Projekt erstellen die folgenden Schritte aus: Sollte dieses Dialogfeld nicht angezeigt werden, wählen Sie im Menü die Option Datei und anschließend Neu > Projekt aus.
1. Wählen Sie die Programmiersprache C# aus.
2. Wählen Sie den Anwendungstyp Konsole aus.
3. Wählen Sie in der Ergebnisliste die Option Konsolenanwendung aus.
4. Klicken Sie anschließend auf Weiter.
Geben Sie EventHubsSender als Projektname und EventHubsQuickStart als Projektmappenname ein, und wählen Sie anschließend OK aus, um das Projekt zu erstellen.

Hinzufügen des Event Hubs-NuGet-Pakets

Wählen Sie im Menü Extras>NuGet-Paket-Manager>Paket-Manager-Konsole aus.
Führen Sie den folgenden Befehl aus, um das NuGet-Paket Azure.Messaging.EventHubs zu installieren:
```
Install-Package Azure.Messaging.EventHubs
```

Schreiben von Code zum Senden von Ereignissen an den Event Hub

Fügen Sie am Anfang der Datei Program.cs die folgenden using-Anweisungen hinzu:

using System;
using System.Text;
using System.Threading.Tasks;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;

Fügen Sie der Klasse Program Konstanten für die Event Hubs-Verbindungszeichenfolge und den Namen des Event Hubs hinzu.
```
    // 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;
```
Hinweis

Ersetzen Sie Platzhalterwerte durch die Verbindungszeichenfolge für Ihren Namespace und den Namen des Event Hubs. Stellen Sie sicher, dass es sich bei der Verbindungszeichenfolge um die Verbindungszeichenfolge auf Namespace-Ebene handelt.

Fügen Sie der Klasse Program die folgende statische Eigenschaft hinzu. Informationen dazu finden Sie in den Codekommentaren.

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

Ersetzen Sie die Methode Main durch die folgende Methode vom Typ async Main. Weitere Einzelheiten finden Sie in den Codekommentaren. Im Folgenden sind die wichtigsten Schritte aus dem Code aufgeführt.

Es wird ein EventHubProducerClient-Objekt unter Verwendung der primären Verbindungszeichenfolge für den Namespace und den Event Hub-Namen erstellt.
Die Methode CreateBatchAsync für das Objekt EventHubProducerClient wird aufgerufen, um ein EventDataBatch-Objekt zu erstellen.
Dem Batch werden mithilfe der Methode EventDataBatch.TryAdd Ereignisse hinzugefügt.
Der Nachrichtenbatch wird mithilfe der EventHubProducerClient.SendAsync-Methode an den Event Hub gesendet.

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

Erstellen Sie das Projekt, und vergewissern Sie sich, dass keine Fehler vorhanden sind.
Führen Sie das Programm aus, und warten Sie auf die Bestätigungsmeldung.
```
A batch of 3 events has been published.
```
Im Azure-Portal können Sie überprüfen, ob der Event Hub die Ereignisse empfangen hat. Wechseln Sie im Abschnitt Metriken zur Ansicht Nachrichten. Aktualisieren Sie die Seite, um das Diagramm zu aktualisieren. Es kann einige Sekunden dauern, bis angezeigt wird, dass die Nachrichten empfangen wurden.

Hinweis

Den gesamten Quellcode mit weiteren informativen Kommentaren finden Sie auf GitHub in dieser Datei.

Empfangen von Ereignissen

In diesem Abschnitt erfahren Sie, wie Sie eine .NET Core-Konsolenanwendung schreiben, die Ereignisse unter Verwendung eines Ereignisprozessors von einem Event Hub empfängt. Der Ereignisprozessor vereinfacht das Empfangen von Ereignissen von Event Hubs durch die Verwaltung permanenter Prüfpunkte und paralleler Empfangsvorgänge von diesen Event Hubs. Ein Ereignisprozessor wird einem bestimmten Event Hub und einer bestimmten Consumergruppe zugeordnet. Er empfängt Ereignisse von mehreren Partitionen im Event Hub und übergibt sie zur Verarbeitung an einen Handlerdelegaten, der dafür von Ihnen bereitgestellten Code verwendet.

Warnung

Wenn Sie diesen Code in Azure Stack Hub ausführen, treten Laufzeitfehler auf, es sei denn, Sie verwenden eine bestimmte Storage-API-Version als Ziel. Dies liegt daran, dass das Event Hubs SDK die neueste verfügbare Azure Storage-API verwendet, die in Azure verfügbar und auf Ihrer Azure Stack Hub-Plattform möglicherweise nicht verfügbar ist. Azure Stack Hub unterstützt möglicherweise eine andere Storage Blob SDK-Version als die üblicherweise in Azure verfügbaren SDKs. Wenn Sie Azure Blob Storage als Prüfpunktspeicher verwenden, überprüfen Sie die unterstützte Azure Storage-API-Version für Ihren Azure Stack Hub-Build, und verwenden Sie diese Version im Code als Ziel.

Wenn Sie z. B. die Azure Stack Hub-Version 2005 verwenden, ist die Version 2019-02-02 die höchste verfügbare Version für den Storage-Dienst. Standardmäßig verwendet die Clientbibliothek des Event Hubs SDK die höchste verfügbare Version in Azure (2019-07-07 zum Zeitpunkt der Veröffentlichung des SDK). In diesem Fall müssen Sie neben den folgenden Schritten in diesem Abschnitt auch Code für die API-Version 2019-02-02 des Storage-Diensts hinzufügen. Ein Beispiel für die Verwendung einer bestimmten Storage-API-Version als Ziel finden Sie in diesem Beispiel auf GitHub.

Erstellen eines Azure Storage-Kontos und eines Blobcontainers

In dieser Schnellstartanleitung wird Azure Storage als Prüfpunktspeicher verwendet. Führen Sie die folgenden Schritte aus, um ein Azure Storage-Konto zu erstellen:

Erstellen Sie ein Azure Storage-Konto.
Erstellen eines Blobcontainers
Abrufen der Verbindungszeichenfolge für das Speicherkonto

Notieren Sie sich die Verbindungszeichenfolge und den Containernamen. Diese Angaben werden im Empfangscode verwendet.

Erstellen eines Projekts für den Empfänger

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe EventHubQuickStart, zeigen Sie auf Hinzufügen, und wählen Sie anschließend Neues Projekt aus.
Wählen Sie zuerst Konsolenanwendung, dann Weiter aus.
Geben Sie unter Projektname den Namen EventHubsReceiver ein, and wählen Sie Erstellen aus.
Klicken Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf EventHubsReceiver, und wählen Sie Als Startprojekt festlegen aus.

Hinzufügen des Event Hubs-NuGet-Pakets

Wählen Sie im Menü Extras>NuGet-Paket-Manager>Paket-Manager-Konsole aus.
Bestätigen Sie im Fenster Paket-Manager-Konsole, dass EventHubsReceiver als Standardprojekt ausgewählt wurde. Ist dies nicht der Fall, wählen Sie in der Dropdownliste EventHubsReceiver aus.
Führen Sie den folgenden Befehl aus, um das NuGet-Paket Azure.Messaging.EventHubs zu installieren:
```
Install-Package Azure.Messaging.EventHubs
```
Führen Sie den folgenden Befehl aus, um das NuGet-Paket Azure.Messaging.EventHubs.Processor zu installieren:
```
Install-Package Azure.Messaging.EventHubs.Processor
```

Aktualisieren der Methode „Main“

Fügen Sie am Anfang der Datei Program.cs die folgenden using-Anweisungen hinzu.

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;

Fügen Sie der Klasse Program Konstanten für die Event Hubs-Verbindungszeichenfolge und den Namen des Event Hubs hinzu. Ersetzen Sie die in Klammern gesetzten Platzhalter durch die entsprechenden Werte, die Sie beim Erstellen des Event Hubs erhalten haben. Ersetzen Sie die in Klammern gesetzten Platzhalter durch die entsprechenden Werte, die Sie beim Erstellen des Event Hubs und des Speicherkontos erhalten haben (Zugriffsschlüssel, primäre Verbindungszeichenfolge). Stellen Sie sicher, dass es sich bei {Event Hubs namespace connection string} um die Verbindungszeichenfolge auf Namespaceebene und nicht um die Event Hub-Zeichenfolge handelt.
```
    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>";
```

Fügen Sie der Klasse Program die folgenden statischen Eigenschaften hinzu.

    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;

Es wird ein EventProcessorClient-Objekt unter Verwendung der primären Verbindungszeichenfolge für den Namespace und den Event Hub erstellt. Sie müssen das BlobContainerClient-Objekt für den Container im Azure-Speicher erstellen, den Sie zuvor erstellt haben.
Es werden Handler für die Ereignisse ProcessEventAsync und ProcessErrorAsync des Objekts EventProcessorClient angegeben.
Die Verarbeitung von Ereignissen wird gestartet, indem die Funktion StartProcessingAsync für das Objekt EventProcessorClient aufgerufen wird.
Wenn der Benutzer eine Taste drückt, um die Verarbeitung zu beenden, wird der Befehl StopProcessingAsync für das Objekt EventProcessorClient aufgerufen.

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

Fügen Sie der Klasse nun die folgenden Ereignis- und Fehlerhandlermethoden hinzu.

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

Erstellen Sie das Projekt, und vergewissern Sie sich, dass keine Fehler vorhanden sind.

Hinweis

Den gesamten Quellcode mit weiteren informativen Kommentaren finden Sie auf GitHub in dieser Datei.
Führen Sie die Empfängeranwendung aus.
Daraufhin sollte eine Nachricht mit dem Hinweis angezeigt werden, dass die Ereignisse empfangen wurden.
```
Received event: Event 1
Received event: Event 2
Received event: Event 3    
```
Bei diesen Ereignissen handelt es sich um die drei Ereignisse, die Sie zuvor durch Ausführen des Sendeprogramms an den Event Hub gesendet haben.
Im Azure-Portal können Sie überprüfen, ob drei ausgehende Nachrichten vorhanden sind. Dies sind die Nachrichten, die Event Hubs an die empfangende Anwendung gesendet hat. Aktualisieren Sie die Seite, um das Diagramm zu aktualisieren. Es kann einige Sekunden dauern, bis angezeigt wird, dass die Nachrichten empfangen wurden.

Nächste Schritte

Dieser Schnellstart bietet eine Schrittanleitung für die Implementierung eines einfachen Szenarios, bei dem ein Batch von Nachrichten an einen Event Hub gesendet und anschließend empfangen wird. Weitere Beispiele zu anderen und komplexeren Szenarien finden Sie in den folgenden Beispielen auf GitHub.