bibliothèque cliente Azure Event Hubs pour .NET - version 5.9.3
Azure Event Hubs est un service de publication-abonnement hautement évolutif qui peut ingérer des millions d’événements par seconde et les diffuser en continu vers plusieurs consommateurs. Cela vous permet de traiter et d’analyser les énormes quantités de données produites par vos appareils et applications connectés. Une fois qu’Event Hubs a collecté les données, vous pouvez les récupérer, les transformer et les stocker à l’aide de n’importe quel fournisseur d’analyse en temps réel ou avec des adaptateurs de traitement par lots/stockage. Si vous souhaitez en savoir plus sur Azure Event Hubs, vous pouvez consulter : Qu’est-ce qu’Event Hubs?
La bibliothèque de client Azure Event Hubs permet de publier et de consommer des événements Azure Event Hubs et peut être utilisée pour :
Émettre des données de télémétrie sur votre application à des fins décisionnelles et de diagnostic.
Publier des faits à propos de l’état de votre application que les parties intéressées peuvent observer et utiliser comme déclencheur d’une action.
Observer les opérations et les interactions intéressantes qui se produisent au sein de votre entreprise ou d’un autre écosystème, ce qui permet aux systèmes faiblement couplés d’interagir sans qu’il soit nécessaire de les lier ensemble.
Recevoir les événements d’un ou de plusieurs serveurs de publication, les transformer pour qu’ils répondent mieux aux besoins de votre écosystème, puis publier les événements transformés dans un nouveau flux à l’attention des consommateurs.
| Code sourcePackage (NuGet) | Documentation de référence sur les | API | Documentation produitGuide | de migrationGuide de résolution des problèmes
Prise en main
Prérequis
Abonnement Azure : Pour utiliser les services Azure, y compris Azure Event Hubs, vous avez besoin d’un abonnement. Si vous n’avez pas de compte Azure existant, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement Visual Studio lorsque vous créez un compte.
Espace de noms Event Hubs avec un hub d’événements : Pour interagir avec Azure Event Hubs, vous devez également disposer d’un espace de noms et d’event Hub. Si vous n’êtes pas familiarisé avec la création de ressources Azure, vous pouvez suivre le guide pas à pas pour créer un Event Hub à l’aide du Portail Azure. Vous y trouverez également des instructions détaillées sur l’utilisation des modèles Azure CLI, Azure PowerShell ou Azure Resource Manager (ARM) pour créer un hub d’événements.
C# 8.0 : La bibliothèque cliente Azure Event Hubs utilise les nouvelles fonctionnalités introduites dans C# 8.0. Pour tirer parti de la syntaxe C# 8.0, il est recommandé de compiler à l’aide du KIT de développement logiciel (SDK) .NET Core 3.0 ou version ultérieure avec une version linguistique de
latest.Les utilisateurs de Visual Studio qui souhaitent tirer pleinement parti de la syntaxe C# 8.0 devront utiliser Visual Studio 2019 ou version ultérieure. Visual Studio 2019, y compris l’édition Community gratuite, est téléchargeable ici. Les utilisateurs de Visual Studio 2017 peuvent tirer parti de la syntaxe C# 8 en utilisant le package NuGet Microsoft.Net.Compilers et en définissant la version du langage, bien que l’expérience de modification ne soit pas idéale.
Vous pouvez toujours utiliser la bibliothèque avec les versions précédentes du langage C#, mais vous devez gérer manuellement les membres asynchrones énumérables et asynchrones jetables plutôt que de tirer parti de la nouvelle syntaxe. Vous pouvez toujours cibler n’importe quelle version du framework prise en charge par votre SDK .NET Core, y compris les versions antérieures de .NET Core ou du .NET Framework. Pour plus d’informations, consultez : comment spécifier des frameworks cibles.
Remarque importante : Pour générer ou exécuter les exemples et les exemples sans modification, l’utilisation de C# 11.0 est nécessaire. Vous pouvez toujours exécuter les exemples si vous décidez de les modifier pour d’autres versions de langage. Un exemple de cette opération est disponible dans l’exemple : Versions de langue antérieures.
Pour créer rapidement un ensemble de ressources Event Hubs de base dans Azure et recevoir une chaîne de connexion pour celles-ci, vous pouvez déployer notre exemple de modèle en cliquant sur :
Installer le package
Installez la bibliothèque cliente Azure Event Hubs pour .NET avec NuGet :
dotnet add package Azure.Messaging.EventHubs
Authentifier le client
Pour que la bibliothèque cliente Event Hubs interagisse avec un hub d’événements, elle doit comprendre comment se connecter et autoriser avec elle. Le moyen le plus simple consiste à utiliser une chaîne de connexion, qui est créée automatiquement lors de la création d’un espace de noms Event Hubs. Si vous n’êtes pas familiarisé avec l’utilisation des chaînes de connexion avec Event Hubs, vous pouvez suivre le guide pas à pas pour obtenir une chaîne de connexion Event Hubs.
Une fois que vous avez une chaîne de connexion, tous les types de clients Event Hubs peuvent être créés avec elle :
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends. This example disposes
// after the immediate scope for simplicity.
await using var producer = new EventHubProducerClient(connectionString, eventHubName);
Pour obtenir des exemples d’authentification des clients Event Hubs avec des types d’informations d’identification, consultez Utilisation d’un principal Azure Active Directory (AAD) ou l’exemple Identité et informations d’identification d’accès partagé .
Pour obtenir des exemples d’authentification des clients Event Hubs pour une application ASP.NET Core, consultez Inscription avec ASP.NET Core injection de dépendances.
Concepts clés
Un client Event Hub représente l’interface principale pour les développeurs qui interagissent avec la bibliothèque cliente Event Hubs. Il existe plusieurs clients Event Hub différents, chacun étant dédié à une utilisation spécifique d’Event Hubs, par exemple la publication ou la consommation d’événements.
Un producteur Event Hub est un type de client qui sert de source de données de télémétrie, d’informations de diagnostic, de journaux d’utilisation ou d’autres données de journal, dans le cadre d’une solution d’appareil intégrée, d’une application pour appareil mobile, d’un jeu exécuté sur une console ou un autre appareil, d’une solution d’entreprise basée sur un client ou un serveur, ou d’un site web.
Un consommateur Event Hub est un type de client qui lit des informations issues du hub d’événements et permet leur traitement : agrégation, calcul et filtrage complexes, ou encore distribution ou stockage des informations brutes ou transformées. Les consommateurs Event Hub correspondent souvent à des composants d’infrastructure de plateforme robustes à grande échelle intégrant des fonctionnalités d’analytique, par exemple Azure Stream Analytics, Apache Spark ou Apache Storm.
Une partition constitue une séquence ordonnée d’événements conservée dans un hub d’événements. Les partitions représentent un moyen d’organiser les données associé au parallélisme requis par les consommateurs d’événements. Azure Event Hubs assure la diffusion de messages suivant un modèle de consommateur partitionné dans lequel chaque consommateur ne lit qu’un sous-ensemble spécifique, ou partition, du flux de message. Les événements les plus récents sont ajoutés à la fin de cette séquence. Le nombre de partitions est spécifié lors de la création du hub d’événements. Il n’est pas modifiable.
Un groupe de consommateurs constitue une vue de tout un hub d’événements. Les groupes de consommateurs permettent à plusieurs applications consommatrices de disposer chacune d’une vue distincte du flux d’événements, et de lire le flux séparément, à son propre rythme et à partir de sa propre position. Il peut y avoir au maximum cinq lecteurs simultanés sur une partition par groupe de consommateurs. Toutefois, il est recommandé de se limiter à un seul consommateur actif pour une association donnée entre une partition et un groupe de consommateurs. Chaque lecteur actif reçoit tous les événements de sa partition. Si plusieurs lecteurs se trouvent sur la même partition, ils reçoivent des événements en double.
Pour plus de concepts et une discussion plus approfondie, consultez Fonctionnalités Event Hubs.
Durée de vie du client
Chacun des types de clients Event Hubs peut être mis en cache et utilisé en tant que singleton pendant la durée de vie de l’application, ce qui est recommandé lorsque des événements sont publiés ou lus régulièrement. Les clients sont responsables de la gestion efficace de l’utilisation du réseau, du processeur et de la mémoire, en travaillant pour maintenir une utilisation faible pendant les périodes d’inactivité. L’appel CloseAsync d’un client ou DisposeAsync sur un client est nécessaire pour s’assurer que les ressources réseau et autres objets non managés sont correctement nettoyés.
Sécurité des threads
Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.
Les types de modèle de données, tels que EventData et EventDataBatch ne sont pas thread-safe. Ils ne doivent pas être partagés entre les threads ni utilisés simultanément avec les méthodes clientes.
Concepts supplémentaires
Options clientes | Gestion des défaillances | Diagnostics | Moqueur
Exemples
Inspection d’un hub d’événements
De nombreuses opérations liées aux hubs d’événements ont lieu dans l’étendue d’une partition spécifique. Étant donné que les partitions sont détenues par le hub d’événements, leurs noms sont assignés au moment de la création. Pour connaître les partitions disponibles, vous devez interroger le hub d’événements avec l’un des clients Event Hub. EventHubProducerClient est illustré dans ces exemples, mais le concept et la forme sont communs à tous les clients.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends. This example disposes
// after the immediate scope for simplicity.
await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
string[] partitionIds = await producer.GetPartitionIdsAsync();
}
Publication d’événements sur un hub d’événements
Pour publier des événements, vous devez créer un EventHubProducerClient. Les producteurs publient des événements par lots et peuvent demander une partition spécifique, ou autoriser le service Event Hubs à décider sur quelle partition les événements doivent être publiés. Il est recommandé d’utiliser le routage automatique lorsque la publication d’événements doit être hautement disponible ou lorsque les données d’événement doivent être distribuées uniformément entre les partitions. Notre exemple tire parti du routage automatique.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends. This example disposes
// after the immediate scope for simplicity.
await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
using EventDataBatch eventBatch = await producer.CreateBatchAsync();
if ((!eventBatch.TryAdd(new EventData("First"))) ||
(!eventBatch.TryAdd(new EventData("Second"))))
{
throw new ApplicationException("Not all events could be added to the batch!");
}
await producer.SendAsync(eventBatch);
}
Lecture d’événements issus d’un hub d’événements
Pour pouvoir lire des événements issus d’un hub d’événements, vous devez créer un EventHubConsumerClient pour un groupe de consommateurs donné. Un hub d’événements fournit lors de sa création un groupe de consommateurs par défaut qui peut être utilisé pour commencer à explorer Event Hubs. Dans cet exemple, nous allons nous attacher à lire tous les événements publiés sur le hub d’événements avec un itérateur.
Note: Il est important de noter que cette approche de la consommation vise à améliorer l’expérience d’exploration de la bibliothèque de client Event Hubs et du prototypage. Il est recommandé de ne pas l’utiliser dans les scénarios de production. Pour une utilisation en production, nous vous recommandons d’utiliser le client de processeur d’événements, car il offre une expérience plus robuste et plus performante.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;
// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends. This example disposes
// after the immediate scope for simplicity.
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.
}
}
Lecture d’événements issus d’une partition de hub d’événements
Pour lire les événements d’une partition Event Hub, vous devez créer un EventHubConsumerClient pour un groupe de consommateurs donné. Un hub d’événements fournit lors de sa création un groupe de consommateurs par défaut qui peut être utilisé pour commencer à explorer Event Hubs. Pour lire à partir d’une partition spécifique, le consommateur doit également spécifier où, dans le flux d’événements, commencer à recevoir les événements ; dans notre exemple, nous allons nous concentrer sur la lecture de tous les événements publiés pour la première partition du hub d’événements.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;
// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends. This example disposes
// after the immediate scope for simplicity.
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.
}
}
Traitement des événements avec un client de processeur d’événements
Pour la majorité des scénarios de production, il est recommandé d’utiliser le client de processeur d’événements pour la lecture et le traitement des événements. Le processeur est destiné à fournir une expérience robuste pour le traitement des événements sur toutes les partitions d’un Event Hub de manière performante et tolérante aux pannes tout en fournissant un moyen de conserver son état. Les clients du processeur d’événements sont également capables de travailler en collaboration dans le contexte d’un groupe de consommateurs pour un hub d’événements donné, où ils gèrent automatiquement la distribution et l’équilibrage du travail à mesure que des instances deviennent disponibles ou indisponibles pour le groupe.
Étant donné que EventProcessorClient présente une dépendance vis-à-vis d’objets blob Stockage Azure pour la persistance de son état, vous devez fournir pour le processeur un BlobContainerClient configuré pour le compte de stockage et le conteneur à utiliser.
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;
}
Pour plus d’informations, consultez le FICHIER README du client Event Processor et les exemples associés.
Utilisation d’un principal Active Directory avec les clients Event Hub
La bibliothèque Azure Identity fournit une prise en charge de l’authentification Azure Active Directory (AAD) qui peut être utilisée pour les bibliothèques clientes Azure, y compris Event Hubs.
Pour utiliser un principal Active Directory, l’une des informations d’identification disponibles à partir de la Azure.Identity bibliothèque est spécifiée lors de la création du client Event Hubs. En outre, l’espace de noms complet Event Hubs et le nom du hub d’événements souhaité sont fournis à la place de la chaîne de connexion Event Hubs. EventHubProducerClient est illustré dans ces exemples, mais le concept et la forme sont communs à tous les clients.
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();
// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends. This example disposes
// after the immediate scope for simplicity.
await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
using EventDataBatch eventBatch = await producer.CreateBatchAsync();
if ((!eventBatch.TryAdd(new EventData("First"))) ||
(!eventBatch.TryAdd(new EventData("Second"))))
{
throw new ApplicationException("Not all events could be added to the batch!");
}
await producer.SendAsync(eventBatch);
}
Lorsque vous utilisez Azure Active Directory, un rôle qui autorise l’accès à Event Hubs doit être attribué à votre principal, tel que le Azure Event Hubs Data Owner rôle. Pour plus d’informations sur l’utilisation de l’autorisation Azure Active Directory avec Event Hubs, consultez la documentation associée.
Inscription avec ASP.NET Core injection de dépendances
Pour injecter l’un des clients Event Hubs en tant que dépendance dans une application ASP.NET Core, installez l’intégration de la bibliothèque cliente Azure pour ASP.NET Core package.
dotnet add package Microsoft.Extensions.Azure
Après l’installation, inscrivez les types de clients Event Hubs souhaités dans la Startup.ConfigureServices méthode :
public void ConfigureServices(IServiceCollection services)
{
services.AddAzureClients(builder =>
{
builder.AddEventHubProducerClient(Configuration.GetConnectionString("EventHubs"));
});
services.AddControllers();
}
Pour utiliser le code précédent, ajoutez ceci à la configuration de votre application :
{
"ConnectionStrings": {
"EventHubs": "<connection_string>"
}
}
Pour les applications qui préfèrent utiliser des informations d’identification partagées Azure.Identity pour leurs clients, l’inscription est légèrement différente :
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
public void ConfigureServices(IServiceCollection services)
{
services.AddAzureClients(builder =>
{
// This will register the EventHubProducerClient using the default credential.
builder.AddEventHubProducerClientWithNamespace(fullyQualifiedNamespace);
// By default, DefaultAzureCredential is used, which is likely desired for most
// scenarios. If you need to restrict to a specific credential instance, you could
// register that instance as the default credential instead.
builder.UseCredential(new ManagedIdentityCredential());
});
services.AddControllers();
}
Pour plus d’informations, consultez Injection de dépendances avec le Kit de développement logiciel (SDK) Azure pour .NET.
Dépannage
Pour obtenir des informations détaillées sur la résolution des problèmes, reportez-vous au Guide de résolution des problèmes d’Event Hubs.
Journalisation et diagnostics
La bibliothèque cliente Event Hubs est entièrement instrumentée pour la journalisation des informations à différents niveaux de détail à l’aide du .NET EventSource pour émettre des informations. La journalisation est effectuée pour chaque opération et suit le modèle de marquage du point de départ de l’opération, de son achèvement et de toutes les exceptions rencontrées. Des informations supplémentaires susceptibles d’offrir des insights sont également enregistrées dans le contexte de l’opération associée.
Les journaux du client Event Hubs sont disponibles pour n’importe qui EventListener en choisissant la source nommée « Azure-Messaging-EventHubs » ou en optant pour toutes les sources qui ont la caractéristique « AzureEventSource ». Pour faciliter la capture des journaux à partir des bibliothèques clientes Azure, la Azure.Core bibliothèque utilisée par Event Hubs offre un AzureEventSourceListener. Pour plus d’informations, consultez Capture des journaux Event Hubs à l’aide d’AzureEventSourceListener.
La bibliothèque cliente Event Hubs est également instrumentée pour le suivi distribué à l’aide d’Application Insights ou d’OpenTelemetry. Pour plus d’informations, consultez l’exemple Diagnostics Azure.Core.
Étapes suivantes
Au-delà des scénarios d’introduction abordés, la bibliothèque cliente Azure Event Hubs offre une prise en charge de scénarios supplémentaires pour vous aider à tirer parti de l’ensemble de fonctionnalités complet du service Azure Event Hubs. Pour vous aider à explorer certains de ces scénarios, la bibliothèque cliente Event Hubs propose un projet d’exemples pour servir d’illustration pour des scénarios courants. Pour plus d’informations, consultez les exemples README .
Contribution
Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.
Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.
Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.
Pour plus d’informations, consultez notre guide de contribution .
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour