Hub eventi di Azure libreria client per .NET - versione 5.8.1

Articolo
04/03/2023

Hub eventi di Azure è un servizio pubblica-sottoscrizione altamente scalabile che può inserire milioni di eventi al secondo e trasmetterli a più consumer. In questo modo è possibile elaborare e analizzare le grandi quantità di dati prodotti dai dispositivi e dalle applicazioni connesse. Dopo aver raccolto i dati, è possibile recuperare, trasformare e archiviarlo usando qualsiasi provider di analisi in tempo reale o con adattatori di batch/archiviazione. Per altre informazioni su Hub eventi di Azure, è possibile esaminare: Informazioni su Hub eventi.

La libreria client di Hub eventi di Azure consente la pubblicazione e l'utilizzo di eventi di Hub eventi di Azure eventi e può essere usata per:

Generare dati di telemetria relativi all'applicazione per finalità di business intelligence e di diagnostica.
Pubblicare informazioni sullo stato dell'applicazione che le parti interessate possono osservare e usare come trigger per intraprendere azioni.
Osservare operazioni e interazioni interessanti che si verificano all'interno dell'azienda o di un altro ecosistema, consentendo ai sistemi ad accoppiamento debole di interagire senza la necessità di associarli tra loro.
Ricevere eventi da uno o più server di pubblicazione, trasformarli per soddisfare meglio le esigenze dell'ecosistema e quindi pubblicare gli eventi trasformati in un nuovo flusso che i consumer possono osservare.

Introduzione

Prerequisiti

Sottoscrizione di Azure: Per usare i servizi di Azure, inclusi Hub eventi di Azure, è necessaria una sottoscrizione. Se non si dispone di un account Azure esistente, è possibile iscriversi per una versione di valutazione gratuita o usare i vantaggi della sottoscrizione di Visual Studio quando si crea un account.
Spazio dei nomi hub eventi con un hub eventi: Per interagire con Hub eventi di Azure, è anche necessario disporre di uno spazio dei nomi e dell'hub eventi. Se non si ha familiarità con la creazione di risorse di Azure, è possibile seguire la guida dettagliata per la creazione di un hub eventi usando l'portale di Azure. È anche possibile trovare istruzioni dettagliate per l'uso dell'interfaccia della riga di comando di Azure, Azure PowerShell o modelli di Azure Resource Manager (ARM) per creare un hub eventi.
C# 8.0: La libreria client Hub eventi di Azure usa nuove funzionalità introdotte in C# 8.0. Per sfruttare la sintassi C# 8.0, è consigliabile compilare usando .NET Core SDK 3.0 o versione successiva con una versione del linguaggio di latest.

Gli utenti di Visual Studio che desiderano sfruttare al meglio la sintassi C# 8.0 dovranno usare Visual Studio 2019 o versione successiva. Visual Studio 2019, inclusa l'edizione Community gratuita, può essere scaricato qui. Gli utenti di Visual Studio 2017 possono sfruttare la sintassi C# 8 usando il pacchetto NuGet Microsoft.Net.Compilers e impostando la versione del linguaggio, anche se l'esperienza di modifica potrebbe non essere ideale.

È comunque possibile usare la libreria con le versioni precedenti del linguaggio C#, ma sarà necessario gestire i membri enumerabili asincroni e asincroni manualmente anziché trarre vantaggio dalla nuova sintassi. È comunque possibile usare qualsiasi versione del framework supportata da .NET Core SDK, incluse le versioni precedenti di .NET Core o .NET Framework. Per altre informazioni, vedere: come specificare i framework di destinazione.
Nota importante: Per compilare o eseguire gli esempi e gli esempi senza modifiche, è necessario usare C# 11.0. È comunque possibile eseguire gli esempi se si decide di modificarli per altre versioni della lingua. Un esempio di questa operazione è disponibile nell'esempio: Versioni precedenti del linguaggio.

Per creare rapidamente un set di risorse di Hub eventi in Azure e per ricevere una stringa di connessione, è possibile distribuire il modello di esempio facendo clic su:

Installare il pacchetto

Installare la libreria client Hub eventi di Azure per .NET con NuGet:

dotnet add package Azure.Messaging.EventHubs

Autenticare il client

Per la libreria client di Hub eventi per interagire con un hub eventi, sarà necessario comprendere come connettersi e autorizzarlo. Il modo più semplice per farlo consiste nell'usare una stringa di connessione, creata automaticamente durante la creazione di uno spazio dei nomi di Hub eventi. Se non si ha familiarità con l'uso delle stringhe di connessione con Hub eventi, è possibile seguire la guida dettagliata per ottenere una stringa di connessione di Hub eventi.

Concetti chiave

Un client di Hub eventi è l'interfaccia principale per gli sviluppatori che interagiscono con la libreria client di Hub eventi. Sono disponibili diversi client dell'hub eventi, ognuno dedicato a un uso specifico di Hub eventi, ad esempio la pubblicazione o l'utilizzo di eventi.
Un producer di Hub eventi è un tipo di client che funge da origine dati di telemetria, informazioni di diagnostica, log di utilizzo o altri dati di log, come parte di una soluzione per dispositivi integrati, un'applicazione per dispositivi mobili, un titolo di gioco in esecuzione in una console o in un altro dispositivo, una soluzione aziendale basata su client o server o un sito Web.
Un consumer di Hub eventi è un tipo di client che legge le informazioni provenienti dall'hub eventi e ne consente l'elaborazione. L'elaborazione può comportare aggregazioni, calcoli complessi e applicazione di filtri. L'elaborazione può anche comportare la distribuzione o l'archiviazione delle informazioni in modo non elaborato o trasformato. I consumer di Hub eventi sono spesso parti di infrastruttura di piattaforma affidabili e su larga scala con funzionalità di analisi predefinite, ad esempio Analisi di flusso di Azure, Apache Spark o Apache Storm.
Una partizione è una sequenza ordinata di eventi che viene mantenuta in un hub eventi. Le partizioni sono un mezzo di organizzazione dei dati associato al parallelismo richiesto dai consumer di eventi. Hub eventi di Azure fornisce il flusso dei messaggi tramite un modello di consumer partizionato in cui ogni consumer legge solo un subset specifico, o partizione, del flusso di messaggi. Man mano che arrivano, i nuovi eventi vengono aggiunti alla fine di questa sequenza. Il numero di partizioni viene specificato al momento della creazione di un hub eventi e non può essere modificato.
Un gruppo di consumer è una visualizzazione di un intero hub eventi. I gruppi di consumer consentono a più applicazioni consumer di avere ognuna una vista separata del flusso di eventi e di leggere il flusso in modo indipendente, in base al proprio ritmo e dalla propria posizione. In una partizione possono esistere al massimo cinque lettori simultanei per gruppo di consumer. È tuttavia consigliabile che sia presente un solo consumer attivo in una specifica partizione e associazione di gruppi di consumer. Ogni lettore attivo riceve tutti gli eventi dalla partizione; se sono presenti più lettori nella stessa partizione, riceveranno eventi duplicati.

Per altri concetti e discussioni più approfondite, vedere: Funzionalità di Hub eventi.

Durata client

Ogni tipo di client hub eventi è sicuro per memorizzare nella cache e usare come singleton per la durata dell'applicazione, che è consigliabile quando gli eventi vengono pubblicati o letti regolarmente. I client sono responsabili della gestione efficiente della rete, della CPU e dell'uso della memoria, lavorando per mantenere l'utilizzo basso durante periodi di inattività. CloseAsync È necessario chiamare o DisposeAsync in un client per assicurarsi che le risorse di rete e altri oggetti non gestiti vengano puliti correttamente.

Thread safety

Si garantisce che tutti i metodi di istanza client siano thread-safe e indipendenti tra loro (linee guida). Ciò garantisce che la raccomandazione di riutilizzare le istanze client sia sempre sicura, anche tra thread.

I tipi di modello di dati, ad EventData esempio e EventDataBatch non sono thread-safe. Non devono essere condivisi tra thread né usati simultaneamente con i metodi client.

Concetti aggiuntivi

Opzioni | client Gestione degli errori | Diagnostica | Beffardo

Esempio

Ispezionare un hub eventi

Molte operazioni dell'hub eventi vengono eseguite nell'ambito di una partizione specifica. Poiché le partizioni sono di proprietà dell'hub eventi, i nomi vengono assegnati al momento della creazione. Per conoscere le partizioni disponibili, eseguire query nell'hub eventi usando uno dei client dell'hub eventi. A scopo illustrativo, in questi esempi viene dimostrato EventHubProducerClient, ma il concetto e la forma sono comuni nei client.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    string[] partitionIds = await producer.GetPartitionIdsAsync();
}

Pubblicare eventi in un hub eventi

Per pubblicare eventi, è necessario creare un oggetto EventHubProducerClient. I producer pubblicano gli eventi in batch e possono richiedere una partizione specifica o consentire al servizio Hub eventi di decidere in quali eventi di partizione pubblicare. È consigliabile usare il routing automatico quando la pubblicazione di eventi deve essere a disponibilità elevata o quando i dati degli eventi devono essere distribuiti uniformemente tra le partizioni. L'esempio sfrutta il routing automatico.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Leggere gli eventi provenienti da un hub eventi

Per leggere gli eventi da un hub eventi, è necessario creare un oggetto EventHubConsumerClient per un determinato gruppo di consumer. Quando viene creato un hub eventi, include un gruppo di consumer predefinito che può essere usato per iniziare a esplorare gli hub eventi. L'esempio è incentrato sulla lettura di tutti gli eventi pubblicati nell'hub eventi usando un iteratore.

Nota: È importante notare che questo approccio all'utilizzo è destinato a migliorare l'esperienza di esplorazione della libreria client e della prototipazione di Hub eventi. È consigliabile non usarlo negli scenari di produzione. Per l'uso in produzione, è consigliabile usare il client processore di eventi, che offre un'esperienza più affidabile e con migliori prestazioni.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync(cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the Event Hub.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Leggere gli eventi provenienti da una partizione dell'hub eventi

Per leggere gli eventi per una partizione di Hub eventi, è necessario creare un oggetto EventHubConsumerClient per un determinato gruppo di consumer. Quando viene creato un hub eventi, include un gruppo di consumer predefinito che può essere usato per iniziare a esplorare gli hub eventi. Per leggere da una partizione specifica, il consumer dovrà anche specificare dove nel flusso di eventi iniziare a ricevere eventi; nell'esempio si concentra sulla lettura di tutti gli eventi pubblicati per la prima partizione dell'hub eventi.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    EventPosition startingPosition = EventPosition.Earliest;
    string partitionId = (await consumer.GetPartitionIdsAsync()).First();

    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsFromPartitionAsync(partitionId, startingPosition, cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the partition.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Elaborare eventi usando un client processore di eventi

Per la maggior parte degli scenari di produzione, è consigliabile usare il client del processore di eventi per la lettura e l'elaborazione degli eventi. Il processore è destinato a offrire un'esperienza affidabile per l'elaborazione di eventi in tutte le partizioni di un hub eventi in modo efficiente e a tolleranza di errore, fornendo un mezzo per mantenere lo stato. I client del processore di eventi sono anche in grado di lavorare in modo cooperativo nel contesto di un gruppo di consumer per un determinato hub eventi, in cui gestiranno automaticamente la distribuzione e il bilanciamento del lavoro come istanze diventano disponibili o non disponibili per il gruppo.

Poiché l'oggetto EventProcessorClient ha una dipendenza dai BLOB di Archiviazione di Azure per la persistenza dello stato, sarà necessario specificare un oggetto BlobContainerClient per il processore, configurato per l'account di archiviazione e il contenitore da usare.

var cancellationSource = new CancellationTokenSource();
cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";

var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";

Task processEventHandler(ProcessEventArgs eventArgs) => Task.CompletedTask;
Task processErrorHandler(ProcessErrorEventArgs eventArgs) => Task.CompletedTask;

var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);

processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;

await processor.StartProcessingAsync();

try
{
    // The processor performs its work in the background; block until cancellation
    // to allow processing to take place.

    await Task.Delay(Timeout.Infinite, cancellationSource.Token);
}
catch (TaskCanceledException)
{
    // This is expected when the delay is canceled.
}

try
{
    await processor.StopProcessingAsync();
}
finally
{
    // To prevent leaks, the handlers should be removed when processing is complete.

    processor.ProcessEventAsync -= processEventHandler;
    processor.ProcessErrorAsync -= processErrorHandler;
}

Altri dettagli sono disponibili nel readME client del processore di eventi e negli esempi di supporto.

Uso di un'entità Active Directory con i client hub eventi

La libreria di identità di Azure offre il supporto di autenticazione di Azure Active Directory che può essere usato per le librerie client di Azure, inclusi Hub eventi.

Per usare un'entità Active Directory, viene specificata una delle credenziali disponibili dalla libreria durante la creazione del Azure.Identity client hub eventi. Inoltre, lo spazio dei nomi hub eventi completo e il nome dell'hub eventi desiderato vengono forniti al posto della stringa di connessione di Hub eventi. A scopo illustrativo, in questi esempi viene dimostrato EventHubProducerClient, ma il concetto e la forma sono comuni nei client.

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();

await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Quando si usa Azure Active Directory, all'entità deve essere assegnato un ruolo che consente l'accesso a Hub eventi, ad esempio il Azure Event Hubs Data Owner ruolo . Per altre informazioni sull'uso dell'autorizzazione di Azure Active Directory con Hub eventi, vedere la documentazione associata.

Risoluzione dei problemi

Per informazioni dettagliate sulla risoluzione dei problemi, vedere la Guida alla risoluzione dei problemi di Hub eventi.

Registrazione e diagnostica

La libreria client di Hub eventi è completamente instrumentata per la registrazione delle informazioni a vari livelli di dettaglio usando .NET EventSource per generare informazioni. La registrazione viene eseguita per ogni operazione e segue il modello di contrassegno del punto iniziale dell'operazione, il completamento e le eccezioni rilevate. Nel contesto dell'operazione associata vengono registrate anche informazioni aggiuntive che possono offrire informazioni dettagliate.

I log client di Hub eventi sono disponibili per qualsiasi EventListener consenso esplicito nell'origine denominata "Azure-Messaging-EventHubs" o acconsentire esplicitamente a tutte le origini con il tratto "AzureEventSource". Per semplificare l'acquisizione dei log dalle librerie client di Azure, la Azure.Core libreria usata da Hub eventi offre un oggetto AzureEventSourceListener. Altre informazioni sono disponibili in Acquisizione dei log di Hub eventi tramite AzureEventSourceListener.

La libreria client di Hub eventi viene instrumentata anche per la traccia distribuita usando Application Insights o OpenTelemetry. Altre informazioni sono disponibili nell'esempio di Diagnostica di Azure.Core.

Passaggi successivi

Oltre agli scenari introduttivi illustrati, la libreria client Hub eventi di Azure offre supporto per scenari aggiuntivi per sfruttare il set completo di funzionalità del servizio Hub eventi di Azure. Per esplorare alcuni di questi scenari, la libreria client di Hub eventi offre un progetto di esempi da usare come illustrazione per scenari comuni. Per informazioni dettagliate, vedere il file README degli esempi.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Per altre informazioni, vedere la guida per i contributi .

Impression