Aspire Azure Event Hubs integrazione

Include: —&— Client

Azure Event Hubs è un servizio di streaming di dati nativo nel cloud che può trasmettere milioni di eventi al secondo, con bassa latenza, da qualsiasi origine a qualsiasi destinazione. L'integrazione AspireAzure Event Hubs consente di connettersi alle istanze di Azure Event Hubs dalle applicazioni .NET.

Integrazione del servizio di hosting

L'integrazione AspireAzure Event Hubs dell'hosting modella le varie risorse di Hub eventi come i tipi seguenti:

• AzureEventHubsResource: rappresenta una risorsa Azure Event Hubs di primo livello, usata per rappresentare raccolte di hub e le informazioni di connessione alla risorsa Azure sottostante.
• AzureEventHubResource: rappresenta una singola risorsa dell'hub eventi.
• AzureEventHubsEmulatorResource: rappresenta un emulatore di Azure Event Hubs come risorsa contenitore.
• AzureEventHubConsumerGroupResource: rappresenta un gruppo di consumer all'interno di una risorsa di Hub eventi.

Per accedere a questi tipi e API per esprimerle all'interno del progetto AppHost, installare .📦Aspire Hosting.Azure. Pacchetto NuGet di EventHubs:

dotnet add package Aspire.Hosting.Azure.EventHubs

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

Per ulteriori informazioni, vedere dotnet add package o .NET.

Aggiungere una risorsa Azure Event Hubs

Per aggiungere un oggetto AzureEventHubsResource al progetto AppHost, chiamare il AddAzureEventHubs metodo specificando un nome e quindi chiamare AddHub:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

Quando si aggiunge una Azure Event Hubs risorsa ad AppHost, espone altre API utili per aggiungere risorse dell'hub eventi, gruppi di consumer, esprimere la configurazione del provisioning esplicito e abilitare l'uso dell'emulatore Azure Event Hubs . Il codice precedente aggiunge una Azure Event Hubs risorsa denominata event-hubs e un hub eventi denominato messages al progetto AppHost. Il metodo WithReference passa le informazioni di connessione al progetto ExampleService.

Connettersi a un'area dei nomi Azure Event Hubs esistente

Potrebbe essere disponibile un servizio esistente Azure Event Hubs a cui connettersi. È possibile concatenare una chiamata per annotare che il AzureEventHubsResource è una risorsa esistente:

var builder = DistributedApplication.CreateBuilder(args);

var existingEventHubsName = builder.AddParameter("existingEventHubsName");
var existingEventHubsResourceGroup = builder.AddParameter("existingEventHubsResourceGroup");

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                    .AsExisting(existingEventHubsName, existingEventHubsResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventHubs);

// After adding all resources, run the app...

Per altre informazioni sulla gestione delle Azure Event Hubs risorse come risorse esistenti, vedere Usare le risorse esistentiAzure.

Aggiungere un gruppo di consumatori di Hub di eventi

Per aggiungere un gruppo di consumatori, concatenare una chiamata a un IResourceBuilder<AzureEventHubsResource> all'API AddConsumerGroup.

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
var messages = eventHubs.AddHub("messages");
messages.AddConsumerGroup("messagesConsumer");

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

// After adding all resources, run the app...

Chiamando AddConsumerGroup, si configura la risorsa Hub Eventi messages in modo da avere un gruppo di consumatori denominato messagesConsumer. Il gruppo di consumer viene creato nello spazio dei nomi Azure Event Hubs rappresentato dal AzureEventHubsResource che hai aggiunto prima. Per altre informazioni, vedere Azure Event Hubs: Gruppi di consumatori.

Aggiungi la risorsa dell'emulatore Azure Event Hubs

L'integrazione dell'hosting AspireAzure Event Hubs supporta l'esecuzione delle risorse di Hub eventi come emulatore, localmente, basandosi sull'immagine del contenitore mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest. Ciò è utile per le situazioni in cui si vuole eseguire la risorsa di Hub eventi in locale a scopo di sviluppo e test, evitando la necessità di effettuare il provisioning di una risorsa Azure o connettersi a un server di Azure Event Hubs esistente.

Per eseguire la risorsa di Hub eventi come emulatore, chiamare il metodo RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator();

eventHubs.AddHub("messages");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(eventHubs);

// After adding all resources, run the app...

Il codice precedente configura una risorsa Azure Event Hubs per l'esecuzione in locale in un contenitore. Per altre informazioni, vedere Azure Event Hubs Emulatore.

Configurare il contenitore dell'emulatore di Event Hubs

Sono disponibili varie configurazioni per le risorse del contenitore, ad esempio è possibile configurare le porte del contenitore, i montaggi di associazione dati, i volumi di dati oppure fornire una configurazione olistica JSON che prevale su tutto.

Configurare la porta host del contenitore dell'emulatore di Event Hub

Per impostazione predefinita, il contenitore dell'emulatore di Hub eventi quando configurato da Aspireespone gli endpoint seguenti:

La porta su cui è in ascolto è dinamica per impostazione predefinita. All'avvio del contenitore, la porta viene mappata a una porta casuale sulla macchina host. Per configurare la porta dell'endpoint, concatenare le chiamate al generatore di risorse del contenitore fornito dal metodo RunAsEmulator e quindi il WithHostPort(IResourceBuilder<AzureEventHubsEmulatorResource>, Nullable<Int32>) come illustrato nell'esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithHostPort(7777);
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

Il codice precedente configura l'endpoint Azure esistente del container dell'emulatore di eventi emulator per l'ascolto sulla porta 7777. La porta del contenitore dell'emulatore di eventi Azure viene mappata alla porta host, come illustrato nella tabella seguente:

Aggiungere l'emulatore di Event Hubs con la quantità di dati

Per aggiungere un volume di dati alla risorsa dell'emulatore di Hub eventi, chiamare il metodo WithDataVolume nella risorsa dell'emulatore di Hub eventi:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataVolume();
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

Il volume di dati viene utilizzato per mantenere persistenti i dati dell'emulatore di Event Hubs al di fuori del ciclo di vita del suo contenitore. Il volume di dati viene montato sul percorso /data nel contenitore. Un nome viene generato in modo casuale, a meno che non si fornisca il parametro name. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai montaggi di binding, vedere Docker la documentazione: Volumi.

Aggiungere l'emulatore di Event Hubs con montaggio associato dei dati

Aggiungere un bind mount al contenitore dell'emulatore di Event Hubs, eseguire una concatenazione di chiamata all'API WithDataBindMount, come illustrato nell'esempio seguente.

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataBindMount("/path/to/data");
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati delle risorse dell'emulatore Azure Event Hubs tra i riavvii del contenitore. Il mount di associazione dati è montato nel percorso di /path/to/data sul computer host nel contenitore. Per altre informazioni sui montaggi di associazione dati, vedere la documentazione: Bind mounts.For more information on data bind mounts, see Docker docs: Bind mounts.

Configurare la configurazione JSON del contenitore emulatore di Event Hubs.

Il contenitore dell'emulatore di Event Hubs viene eseguito con un file config.json predefinito. È possibile eseguire l'override di questo file completamente o aggiornare la configurazione JSON con una rappresentazione JsonNode della configurazione.

Per fornire un file di configurazione JSON personalizzato, chiamare il metodo WithConfigurationFile(IResourceBuilder<AzureEventHubsEmulatorResource>, String):

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfigurationFile("./messaging/custom-config.json");
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

Il codice precedente configura il contenitore dell'emulatore di Hub eventi per l'uso di un file di configurazione personalizzato JSON disponibile in ./messaging/custom-config.json. Questa operazione verrà montata nel percorso /Eventhubs_Emulator/ConfigFiles/Config.json del contenitore, come file di sola lettura. Per eseguire invece l'override di proprietà specifiche nella configurazione predefinita, chiamare il metodo WithConfiguration(IResourceBuilder<AzureEventHubsEmulatorResource>, Action<JsonNode>):

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfiguration(
                               (JsonNode configuration) =>
                               {
                                   var userConfig = configuration["UserConfig"];
                                   var ns = userConfig["NamespaceConfig"][0];
                                   var firstEntity = ns["Entities"][0];
                                   
                                   firstEntity["PartitionCount"] = 5;
                               });
                       });

eventHubs.AddHub("messages");

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

// After adding all resources, run the app...

Il codice precedente recupera il nodo UserConfig dalla configurazione predefinita. Aggiorna quindi il PartitionCount della prima entità in 5.

Bicep generato attraverso il provisioning

Se non si ha familiarità con Bicep, si tratta di un linguaggio specifico del dominio per la definizione delle Azure risorse. Con Aspire non è necessario scrivere Bicep manualmente, invece le API di provisioning generano Bicep automaticamente. Quando pubblichi la tua app, il Bicep generato viene visualizzato insieme al file manifesto. Quando si aggiunge una risorsa Azure Event Hubs, viene generato il seguente Bicep:

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param sku string = 'Standard'

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' = {
  name: take('event_hubs-${uniqueString(resourceGroup().id)}', 256)
  ___location: ___location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'event-hubs'
  }
}

resource messages 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = {
  name: 'messages'
  parent: event_hubs
}

output eventHubsEndpoint string = event_hubs.properties.serviceBusEndpoint

output name string = event_hubs.name

Il Bicep precedente è un modulo che fornisce una risorsa Azure Event Hubs. Inoltre, le assegnazioni di ruolo vengono create per la Azure risorsa in un modulo separato:

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param event_hubs_outputs_name string

param principalType string

param principalId string

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' existing = {
  name: event_hubs_outputs_name
}

resource event_hubs_AzureEventHubsDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(event_hubs.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec')
    principalType: principalType
  }
  scope: event_hubs
}

Il Bicep generato è un punto di partenza e viene influenzato dalle modifiche apportate all'infrastruttura di provisioning in C#. Le personalizzazioni apportate direttamente al file Bicep verranno sovrascritte, quindi è necessario effettuare modifiche tramite le API di provisioning C# per garantire che vengano riflesse nei file generati.

Personalizzare l'infrastruttura di approvvigionamento

Tutte le risorse AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure, utilizzando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare il kind, consistencyPolicy, locationse altro ancora. L'esempio seguente illustra come personalizzare la risorsa AzureAzure Cosmos DB:

builder.AddAzureEventHubs("event-hubs")
    .ConfigureInfrastructure(infra =>
    {
        var eventHubs = infra.GetProvisionableResources()
                             .OfType<EventHubsNamespace>()
                             .Single();

        eventHubs.Sku = new EventHubsSku()
        {
            Name = EventHubsSkuName.Premium,
            Tier = EventHubsSkuTier.Premium,
            Capacity = 7,
        };
        eventHubs.PublicNetworkAccess = EventHubsPublicNetworkAccess.SecuredByPerimeter;
        eventHubs.Tags.Add("ExampleKey", "Example value");
    });

Il codice precedente:

• Concatena una chiamata all'API ConfigureInfrastructure:
  • Il parametro infra è un'istanza del tipo AzureResourceInfrastructure.
  • Le risorse provisionabili si recuperano chiamando il metodo GetProvisionableResources().
  • Viene recuperata la singola risorsa EventHubsNamespace.
  • La proprietà EventHubsNamespace.Sku viene assegnata a una nuova istanza di EventHubsSku con il nome e il livello Premium, e un Capacity di 7.
  • La proprietà PublicNetworkAccess viene assegnata a SecuredByPerimeter.
  • Un tag viene aggiunto alla risorsa di Hub eventi con una chiave di ExampleKey e un valore di Example value.

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa di Event Hubs. Per altre informazioni, vedere Azure.Provisioning.PostgreSql. Per altre informazioni, vedere Azure.Provisioning personalizzazione.

Verifica dell'integrità delle integrazioni di hosting

L'integrazione dell'hosting Azure Event Hubs aggiunge automaticamente una verifica dello stato per la risorsa Event Hubs. Il controllo di integrità verifica che l'Event Hubs sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto NuGet AspNetCore.HealthChecks.Messaging.EventHubs.

Client integrazione

Per iniziare a usare l'integrazione AspireAzure Event Hubs client, installare il pacchetto NuGet 📦AspireAzure.Messaging.EventHubs nel progetto che usa il client, ovvero il progetto per l'applicazione che utilizza il client di Event Hubs.

dotnet add package Aspire.Azure.Messaging.EventHubs

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

I tipi di client supportati dell'Hub eventi

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

I tipi di client provengono dall'SDK di Azure per .NET, come sono le classi di opzioni corrispondenti. Le classi di impostazioni vengono fornite da Aspire. Le classi di impostazioni vengono usate per configurare le istanze client.

Aggiungere un client produttore per Event Hubs

Nel file Program.cs del progetto che utilizza il client, invoca il metodo di estensione AddAzureEventHubProducerClient su qualsiasi IHostApplicationBuilder per registrare un EventHubProducerClient per l'uso attraverso il container di iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddAzureEventHubProducerClient(connectionName: "event-hubs");

Dopo aver aggiunto il EventHubProducerClient, puoi recuperare l'istanza del client usando la dependency injection. Ad esempio, per recuperare l'oggetto sorgente dati da un servizio di esempio, definiscilo come parametro del costruttore e assicurati che la classe ExampleService sia registrata con il contenitore di iniezione delle dipendenze.

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

Per altre informazioni, vedere:

• Azure. Documentazione di Messaging.EventHubs per esempi sull'uso di EventHubProducerClient.
• Iniezione delle dipendenze in .NET per informazioni dettagliate sull'iniezione delle dipendenze.

API aggiuntive da considerare

L'integrazione client fornisce API aggiuntive per configurare le istanze client. Quando è necessario registrare un client di Hub eventi, prendere in considerazione le API seguenti:

Tutte le API menzionate in precedenza includono parametri facoltativi per configurare le istanze client.

Aggiungere il client producer con chiave di Event Hub

In alcuni casi potrebbe essere necessario registrare più istanze di EventHubProducerClient con nomi di connessione diversi. Per registrare i client di Hub eventi con chiave, chiamare il metodo AddKeyedAzureServiceBusClient:

builder.AddKeyedAzureEventHubProducerClient(name: "messages");
builder.AddKeyedAzureEventHubProducerClient(name: "commands");

È quindi possibile recuperare le istanze client usando l'iniezione di dipendenze. Ad esempio, per recuperare i client da un servizio:

public class ExampleService(
    [KeyedService("messages")] EventHubProducerClient messagesClient,
    [KeyedService("commands")] EventHubProducerClient commandsClient)
{
    // Use clients...
}

Per altre informazioni, vedere Servizi con chiave in .NET.

API chiave aggiuntive da considerare

L'integrazione client fornisce API aggiuntive per configurare le istanze client con chiave. Quando è necessario registrare un client di Hub eventi con chiave, prendere in considerazione le API seguenti:

Tutte le API menzionate in precedenza includono parametri facoltativi per configurare le istanze client.

Configurazione

La libreria 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 utilizzano builder.AddAzureEventHubProducerClient() e altri client di Event Hubs 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(
    "event-hubs",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

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

Namespace completamente qualificato (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": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

Stringa di connessione

In alternativa, usare una stringa di connessione:

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

Utilizzare i fornitori di configurazione

La libreria di 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"
            }
          }
        }
      }
    }
  }
}

Per lo schema di integrazione Azure Event Hubs client completoJSON, vedere Aspire.Azure. Messaging.EventHubs/ConfigurationSchema.json.

Usare la configurazione denominata

La AspireAzure Event Hubs libreria supporta la configurazione denominata, che consente di configurare più istanze dello stesso tipo di client con impostazioni diverse. La configurazione denominata usa il nome della connessione come chiave nella sezione di configurazione client specifica.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "processor1": {
              "EventHubName": "MyHub1",
              "ClientOptions": {
                "Identifier": "PROCESSOR_1"
              }
            },
            "processor2": {
              "EventHubName": "MyHub2",
              "ClientOptions": {
                "Identifier": "PROCESSOR_2"
              }
            }
          }
        }
      }
    }
  }
}

In questo esempio, i nomi di connessione processor1 e processor2 possono essere usati quando si chiama AddAzureEventProcessorClient:

builder.AddAzureEventProcessorClient("processor1");
builder.AddAzureEventProcessorClient("processor2");

La configurazione denominata ha la precedenza sulla configurazione di primo livello. Se vengono specificati entrambi, le impostazioni della configurazione denominata sostituiscono le impostazioni di primo livello.

È 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(
    "event-hubs",
    configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions(
        options => options.Identifier = "PROCESSOR_ID"));

Osservabilità e telemetria

Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere Aspire Panoramica delle integrazioni. 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 AspireAzure Event Hubs usa le categorie di log seguenti:

• Azure.Core
• Azure.Identity

Tracciamento

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

• Azure.Messaging.EventHubs.*

Metriche

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

Vedere anche

• Azure Event Hubs
• Aspire Azure Panoramica delle integrazioni
• Aspire Integrazioni
• Aspire GitHub Repo