.NET Aspire Azure Event Hubs-Integration

Artikel
12/14/2024

In diesem Artikel erfahren Sie, wie Sie die .NET AspireAzure Event Hubs Integration verwenden. Die Aspire.Azure.Messaging.EventHubs-Bibliothek bietet Optionen zum Registrieren der folgenden Typen:

Diese Typen werden im DI-Container registriert, um eine Verbindung mit Azure Event Hubsherzustellen.

Voraussetzungen

Azure Abonnement: ein kostenloseserstellen.
Azure Event Hubs Namespace: Weitere Informationen finden Sie unter Hinzufügen eines Event Hubs-Namespace. Alternativ können Sie eine Verbindungszeichenfolge verwenden, die in Produktionsumgebungen nicht empfohlen wird.

Loslegen

Um mit der .NET AspireAzure Event Hubs-Integration zu beginnen, installieren Sie das NuGet-Paket 📦Aspire.Azure.Messaging.EventHubs im Projekt client-Nutzung, also das Projekt für die Anwendung, die die Azure Event Hubsclientverwendet.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.EventHubs

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

Weitere Informationen finden Sie unter dotnet add package oder Verwalten Sie Paketabhängigkeiten in .NET Anwendungen.

Unterstützte Clients mit Optionenklassen

Die folgenden Clients werden von der Bibliothek zusammen mit den entsprechenden Optionen und Einstellungsklassen unterstützt:

Azure Client Typ	Azure Options-Klasse	.NET .NET Aspire Einstellungen-Klasse
`EventHubProducerClient`	`EventHubProducerClientOptions`	`AzureMessagingEventHubsProducerSettings`
`EventHubBufferedProducerClient`	`EventHubBufferedProducerClientOptions`	`AzureMessagingEventHubsBufferedProducerSettings`
`EventHubConsumerClient`	`EventHubConsumerClientOptions`	`AzureMessagingEventHubsConsumerSettings`
`EventProcessorClient`	`EventProcessorClientOptions`	`AzureMessagingEventHubsProcessorSettings`
`PartitionReceiver`	`PartitionReceiverOptions`	`AzureMessagingEventHubsPartitionReceiverSettings`

Der client Typ stammt aus dem Azure SDK für .NET, ebenso wie die entsprechenden Optionsklassen. Die Konfigurationseinstellungen werden von der .NET AspireAzure Event Hubs Integrationsbibliothek bereitgestellt.

Beispielverwendung

Im folgenden Beispiel wird davon ausgegangen, dass Sie einen Azure Event Hubs Namespace und einen Event Hub erstellt haben. Sie möchten eine EventHubProducerClient konfigurieren, um Ereignisse an den Event Hub zu senden. Die EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorClientund PartitionReceiverwerden auf ähnliche Weise konfiguriert.

Rufen Sie in der datei Program.cs Ihres client-verbrauchenden Projekts die AddAzureEventHubProducerClient-Erweiterung auf, um eine EventHubProducerClient für die Verwendung über den Container zum Einfügen von Abhängigkeiten zu registrieren.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

Anschließend können Sie die EventHubProducerClient Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die client von einem Dienst ab:

public class ExampleService(EventHubProducerClient client)
{
    // Use client...
}

Weitere Informationen sehen Sie in der Dokumentation "Azure.Messaging.EventHubs" mit Beispielen für die Verwendung des EventHubProducerClient.

Nutzung des App-Hosts

Um Azure Event Hub-Hostingunterstützung zu Ihrem IDistributedApplicationBuilderhinzuzufügen, installieren Sie die 📦Aspire. Hosting.Azure. EventHubs NuGet-Paket im App-Host Projekt.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.EventHubs

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

Fügen Sie in Ihrem App-Hostprojekt eine Event Hubs-Verbindung und eine Event Hub-Ressource hinzu, und nutzen Sie die Verbindung mit den folgenden Methoden:

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleService = builder.AddProject<Projects.ExampleService>()
                            .WithReference(eventHubs);

Die AddAzureEventHubs-Methode liest Verbindungsinformationen aus der Konfiguration von AppHost aus (zum Beispiel aus "Benutzergeheimnissen") unter dem Konfigurationsschlüssel ConnectionStrings:eventHubsConnectionName. Die WithReference-Methode übergibt die Verbindungsinformationen an eine Verbindungszeichenfolge mit dem Namen eventHubsConnectionName im ExampleService-Projekt.

Ab .NET Aspire 8.1 unterstützt die Azure EventHubs-Erweiterung für .NET Aspire das Starten eines lokalen Emulators für EventHubs. Sie können den Emulator verwenden, indem Sie die RunAsEmulator() Erweiterungsmethode wie folgt anwenden:

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

Der Emulator für Azure EventHubs führt dazu, dass zwei Containerressourcen innerhalb .NET Aspire gestartet werden, die vom Namen des Ereignishubs-Ressourcennamens abgeleitet wurden.

Wichtig

Obwohl wir einen Event Hub mit dem AddEventHub gleichzeitig mit dem Namespace erstellen, enthält die Verbindungszeichenfolge ab .NET.NET Aspire Version preview-5nicht die EntityPath-Eigenschaft, sodass die EventHubName-Eigenschaft im Einstellungsrückruf für die bevorzugte clientfestgelegt werden muss. Zukünftige Versionen von Aspire enthalten die EntityPath-Eigenschaft in der Verbindungszeichenfolge und erfordern nicht, dass die EventHubName-Eigenschaft in diesem Szenario festgelegt wird.

In der Program.cs-Datei von ExampleServicekann die Verbindung durch Aufruf der unterstützten Event Hubs client-Erweiterungsmethoden genutzt werden:

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

Konfiguration

Die .NET AspireAzure Event Hubs bibliothek bietet mehrere Optionen zum Konfigurieren der Azure Event Hubs Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts. Entweder ein FullyQualifiedNamespace oder ein ConnectionString ist zu liefern erforderlich.

Verbindungszeichenfolge verwenden

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, geben Sie den Namen der Verbindungszeichenfolge beim Aufrufen builder.AddAzureEventHubProducerClient() und anderer unterstützter Event Hubs-Clients an. In diesem Beispiel enthält die Verbindungszeichenfolge nicht die Eigenschaft EntityPath, sodass die Eigenschaft EventHubName im Einstellungsrückruf festgelegt werden muss.

builder.AddAzureEventHubProducerClient(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

Anschließend werden die Verbindungsinformationen aus dem Konfigurationsabschnitt ConnectionStrings abgerufen. Zwei Verbindungsformate werden unterstützt:

Vollqualifizierter Namespace (FQN)

Der empfohlene Ansatz besteht darin, einen vollqualifizierten Namespace zu verwenden, der mit der AzureMessagingEventHubsSettings.Credential-Eigenschaft funktioniert, um eine Verbindung herzustellen. Wenn keine Anmeldeinformationen konfiguriert sind, wird das DefaultAzureCredential verwendet.

{
  "ConnectionStrings": {
    "eventHubsConnectionName": "{your_namespace}.servicebus.windows.net"
  }
}

Verbindungszeichenfolge

Alternativ können Sie eine Verbindungszeichenfolge verwenden:

{
  "ConnectionStrings": {
    "eventHubsConnectionName": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub"
  }
}

Konfigurationsanbieter verwenden

Die .NET AspireAzure Event Hubs-Bibliothek unterstützt Microsoft.Extensions.Configuration. Es lädt die AzureMessagingEventHubsSettings sowie die zugehörigen Optionen, z. B. EventProcessorClientOptions, aus der Konfiguration mithilfe des Schlüsselpräfixes Aspire:Azure:Messaging:EventHubs:, gefolgt vom Namen des verwendeten spezifischen client. Betrachten Sie beispielsweise die appsettings.json, mit der einige der Optionen für eine EventProcessorClientkonfiguriert werden:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "EventHubName": "MyHub",
            "ClientOptions": {
              "Identifier": "PROCESSOR_ID"
            }
          }
        }
      }
    }
  }
}

Sie können den Optionstyp auch mit dem optionalen Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder-Parameter der AddAzureEventProcessorClient-Methode festlegen. Um beispielsweise die client-ID des Prozessors für diese clientfestzulegen:

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions(
        options => options.Identifier = "PROCESSOR_ID"));

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als den Säulen der Observabilitybezeichnet werden. Weitere Informationen zur Integrationsbeobachtbarkeit und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom Back-End-Dienst unterstützen manche Integrationen möglicherweise nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Configuration beschrieben sind.

Protokollierung

Die .NET AspireAzure Event Hubs-Integration verwendet die folgenden Protokollkategorien:

Azure.Core
Azure.Identity

Verfolgung

Die .NET AspireAzure Event Hubs Integration gibt die folgenden Tracing-Aktivitäten mithilfe von OpenTelemetryaus.

Azure.Messaging.EventHubs.*

Metriken

Die .NET AspireAzure Event Hubs-Integration unterstützt standardmäßig derzeit keine Metriken aufgrund von Einschränkungen mit dem Azure SDK für .NET. Wenn sich dies in Zukunft ändert, wird dieser Abschnitt aktualisiert, um diese Änderungen widerzuspiegeln.

Freigeben über