integrazione di .NET AspireAzure Event Hubs

Articolo
12/16/2024

Questo articolo illustra come usare l'integrazione .NET AspireAzure Event Hubs. La libreria Aspire.Azure.Messaging.EventHubs offre opzioni per la registrazione dei tipi seguenti:

Questi tipi vengono registrati nel contenitore DI per la connessione a Azure Event Hubs.

Prerequisiti

sottoscrizione Azure: crearne una gratuitamente.
Lo spazio dei nomi Azure Event Hubs: per ulteriori informazioni, vedere per aggiungere uno spazio dei nomi di Event Hubs. In alternativa, è possibile usare una stringa di connessione, che non è consigliata negli ambienti di produzione.

Inizia

Per iniziare a usare l'integrazione di , installare il pacchetto NuGet ..Messaging.EventHubs nel progetto cliente-consumatore, ovvero il progetto per l'applicazione che usa il client .

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.EventHubs

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

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Supporto fornito ai clienti tramite classi di opzioni

I client seguenti sono supportati dalla libreria, insieme alle relative opzioni e classi di impostazioni corrispondenti:

tipo di AzureClient	Classe di opzioni Azure	Classe Impostazioni di .NET.NET Aspire
`EventHubProducerClient`	`EventHubProducerClientOptions`	`AzureMessagingEventHubsProducerSettings`
`EventHubBufferedProducerClient`	`EventHubBufferedProducerClientOptions`	`AzureMessagingEventHubsBufferedProducerSettings`
`EventHubConsumerClient`	`EventHubConsumerClientOptions`	`AzureMessagingEventHubsConsumerSettings`
`EventProcessorClient`	`EventProcessorClientOptions`	`AzureMessagingEventHubsProcessorSettings`
`PartitionReceiver`	`PartitionReceiverOptions`	`AzureMessagingEventHubsPartitionReceiverSettings`

Il tipo di client proviene dall'SDK di Azure per .NET, così come le classi delle opzioni corrispondenti. Le classi di impostazioni vengono fornite dalla libreria di integrazione .NET AspireAzure Event Hubs.

Esempio di utilizzo

L'esempio seguente presuppone che si disponga di uno spazio dei nomi Azure Event Hubs e di un hub eventi creato e si vuole configurare un EventHubProducerClient per inviare eventi all'hub eventi. I EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorCliente PartitionReceivervengono configurati in modo analogo.

Nel file Program.cs del progetto che usa il client, si chiama l'estensione AddAzureEventHubProducerClient per registrare un EventHubProducerClient da utilizzare attraverso il contenitore di iniezione delle dipendenze.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

È quindi possibile recuperare l'istanza di EventHubProducerClient tramite l'iniezione delle dipendenze. Ad esempio, per recuperare il client da un servizio:

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

Per ulteriori informazioni, consultare la documentazione di Azure.Messaging.EventHubs per esempi sull'uso del EventHubProducerClient.

Utilizzo dell'host dell'app

Per aggiungere Azure supporto per l'hosting dell'Hub eventi alla IDistributedApplicationBuilder, installare il 📦Aspire.Hosting.Azure.EventHubs pacchetto NuGet nell'host dell'app del progetto.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.EventHubs

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

Nel progetto host dell'app, aggiungere una connessione a Event Hubs e una risorsa di Event Hubs e utilizzare la connessione con i metodi seguenti:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Il metodo AddAzureEventHubs leggerà le informazioni di connessione dalla configurazione di AppHost (ad esempio, da "segreti utente") nella chiave di configurazione ConnectionStrings:eventHubsConnectionName. Il metodo WithReference passa tali informazioni di connessione in una stringa di connessione denominata eventHubsConnectionName nel progetto ExampleService.

A partire da .NET Aspire 8.1, l'estensione Azure EventHubs per .NET Aspire supporta l'avvio di un emulatore locale per EventHubs. È possibile usare l'emulatore applicando il metodo di estensione RunAsEmulator() come indicato di seguito:

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

L'emulatore per Azure EventHubs comporta l'avvio di due risorse contenitore all'interno di .NET Aspire, che sono basate sul nome della risorsa EventHubs.

Importante

Anche se si sta creando un hub eventi usando il AddEventHub contemporaneamente allo spazio dei nomi, a partire dalla versione .NET.NET Aspirepreview-5, la stringa di connessione non includerà la proprietà EntityPath, pertanto la proprietà EventHubName deve essere impostata nel callback delle impostazioni per il client preferito. Le versioni future di Aspire includeranno la proprietà EntityPath nella stringa di connessione e non richiederanno l'impostazione della proprietà EventHubName in questo scenario.

Nel file Program.cs di ExampleService, la connessione può essere consumata chiamando i metodi di estensione forniti dal client di Event Hubs supportati.

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

Configurazione

La libreria .NET AspireAzure Event Hubs offre più opzioni per configurare la connessione Azure Event Hubs in base ai requisiti e alle convenzioni del progetto. Deve essere fornito un FullyQualifiedNamespace o un ConnectionString.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, specificare il nome della stringa di connessione quando si chiama builder.AddAzureEventHubProducerClient() e altri client di Hub eventi supportati. In questo esempio la stringa di connessione non include la proprietà EntityPath, pertanto la proprietà EventHubName deve essere impostata nel callback delle impostazioni:

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

Le informazioni di connessione verranno quindi recuperate dalla sezione di configurazione ConnectionStrings. Sono supportati due formati di connessione:

Spazio dei nomi completo (FQN)

L'approccio consigliato consiste nell'usare uno spazio dei nomi completamente qualificato, che funziona con la proprietà AzureMessagingEventHubsSettings.Credential per stabilire una connessione. Se non è configurata alcuna credenziale, viene usato il DefaultAzureCredential.

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

Stringa di connessione

In alternativa, usare una stringa di connessione:

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

Utilizzare i provider di configurazione

La libreria di .NET AspireAzure Event Hubs supporta Microsoft.Extensions.Configuration. Carica il AzureMessagingEventHubsSettings e le Opzioni associate, ad esempio EventProcessorClientOptions, dalla configurazione usando il prefisso della chiave Aspire:Azure:Messaging:EventHubs:, seguito dal nome del client specifico in uso. Si consideri ad esempio il appsettings.json che configura alcune delle opzioni per un EventProcessorClient:

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

È anche possibile configurare il tipo Options usando il parametro facoltativo Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder del metodo AddAzureEventProcessorClient. Ad esempio, per impostare l'ID client del processore per questo client:

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

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzure Event Hubs usa le categorie di log seguenti:

Azure.Core
Azure.Identity

Tracciamento

L'integrazione .NET AspireAzure Event Hubs genererà le attività di traccia seguenti usando OpenTelemetry:

"Azure.Messaging.EventHubs.*"

Metriche

L'integrazione .NET AspireAzure Event Hubs attualmente non supporta le metriche di default a causa delle limitazioni con Azure SDK per .NET. Se tali modifiche verranno apportate in futuro, questa sezione verrà aggiornata in modo da riflettere tali modifiche.

Condividi tramite