Partage via


Démarrage rapide : envoyer vers et recevoir des événements d’Azure Event Hubs avec .NET

Dans ce guide de démarrage rapide, vous allez apprendre à envoyer des événements à un Event Hub et à recevoir ces événements à partir de l’Event Hub à l’aide de la bibliothèque .NET Azure.Messaging.EventHubs.

Notes

Les guides de démarrage rapide vous permettent d’accélérer rapidement le service. Si vous êtes déjà familiarisé avec le service, vous pouvez consulter des exemples .NET pour Event Hubs dans notre référentiel SDK .NET sur GitHub : Exemples Event Hubs sur GitHub, Exemples de processeurs d’événements sur GitHub.

Prérequis

Si vous débutez avec Azure Event Hubs, consultez la vue d’ensemble d’Event Hubs avant de suivre ce guide de démarrage rapide.

Pour effectuer ce démarrage rapide, vous avez besoin de ce qui suit :

  • Abonnement Microsoft 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, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement MSDN quand vous créez un compte.
  • Microsoft Visual Studio 2022. La bibliothèque cliente Azure Event Hubs utilise les nouvelles fonctionnalités introduites dans C# 8.0. Vous pouvez toujours utiliser la bibliothèque avec les versions précédentes du langage C#, mais la nouvelle syntaxe n’est pas disponible. Pour utiliser la syntaxe complète, nous vous recommandons d’effectuer la compilation avec la version 3.0 ou une version ultérieure du kit SDK .NET Core et la version du langage latest. Si vous utilisez Visual Studio, notez que les versions antérieures à Visual Studio 2022 ne sont pas compatibles avec les outils nécessaires à la génération de projets C# 8.0. Visual Studio 2022, y compris l’édition Community gratuite, est téléchargeable ici.
  • Créez un espace de noms Event Hubs et un Event Hub. La première étape consiste à utiliser le portail Azure pour créer un espace de noms Event Hubs et un Event Hub dans l’espace de noms. Obtenez ensuite les informations de gestion nécessaires à votre application pour communiquer avec l’Event Hub. Pour créer un espace de noms et un Event Hub, consultez Démarrage rapide : créer un Event Hub avec le portail Azure.

Authentifier l’application sur Azure

Ce guide de démarrage rapide vous montre deux façons de vous connecter à Azure Event Hubs :

  • Sans mot de passe (authentification Microsoft Entra)
  • Connection string

La première option vous explique comment utiliser votre principal de sécurité dans Azure Active Directory et le contrôle d’accès en fonction du rôle (RBAC) pour vous connecter à un espace de noms Event Hubs. Vous n’avez pas à vous soucier d’avoir des chaînes de connexion codées en dur dans votre code, dans un fichier config ni dans un stockage sécurisé comme Azure Key Vault.

La deuxième option consiste à se servir d’une chaîne de connexion pour se connecter à un espace de noms Event Hubs. Si vous débutez avec Azure, vous trouverez peut-être l’option de chaîne de connexion plus facile à suivre. Nous vous recommandons d’utiliser l’option sans mot de passe dans les applications réelles et les environnements de production. Pour plus d’informations, consultez Authentification et autorisation. Pour en savoir plus sur l’authentification sans mot de passe, reportez-vous à la page de présentation.

Attribuer des rôles à votre utilisateur Microsoft Entra

Lors du développement localement, vous devez vérifier que le compte d’utilisateur qui se connecte à Azure Event Hubs dispose des autorisations appropriées. Vous aurez besoin du rôle Propriétaire de données Azure Event Hubs pour envoyer et recevoir des messages. Pour vous attribuer ce rôle, vous aurez besoin du rôle Administrateur de l’accès utilisateur ou d’un autre rôle qui inclut l’action Microsoft.Authorization/roleAssignments/write. Vous pouvez attribuer des rôles RBAC Azure à un utilisateur à l’aide du Portail Azure, Azure CLI ou Azure PowerShell. Découvrez les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue.

L’exemple suivant attribue le rôle Azure Event Hubs Data Owner à votre compte d’utilisateur, qui fournit un accès complet aux ressources Azure Event Hubs. Dans un scénario réel, suivez le principe des privilèges minimum pour accorder aux utilisateurs uniquement les autorisations minimales nécessaires à un environnement de production plus sécurisé.

Rôles intégrés Azure pour Azure Event Hubs

Pour Azure Event Hubs, la gestion des espaces de noms et de toutes les ressources associées via le portail Azure et l’API de gestion des ressources Azure est déjà protégée à l’aide du modèle RBAC Azure. Azure fournit les rôles Azure intégrés ci-dessous pour autoriser l’accès à un espace de noms Event Hubs :

Si vous souhaitez créer un rôle personnalisé, consultez Droits requis pour les opérations Service Bus.

Important

Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes. Dans de rares cas, cela peut prendre jusqu’à huit minutes. Si vous recevez des erreurs d’authentification lorsque vous exécutez votre code pour la première fois, patientez quelques instants et réessayez.

  1. Dans le portail Azure, recherchez votre espace de noms Event Hubs à l’aide de la barre de recherche principale ou de la navigation gauche.

  2. Dans la page vue d’ensemble, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.

  3. Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.

  4. Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.

    Capture d’écran montrant comment attribuer un rôle.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Azure Event Hubs Data Owner et sélectionnez le résultat correspondant. Ensuite, choisissez Suivant.

  6. Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.

  7. Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail utilisateur@domaine), puis choisissez Sélectionner en bas de la boîte de dialogue.

  8. Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Lancer Visual Studio et vous connecter à Azure

Vous pouvez autoriser l’accès à l’espace de noms Service Bus en procédant comme suit :

  1. Lancez Visual Studio. Si la fenêtre Démarrage s’affiche, sélectionnez le lien Continuer sans code dans le volet de droite.

  2. Sélectionnez le bouton Se connecter en haut à droite de Visual Studio.

    Capture d’écran montrant le bouton de connexion à Azure avec Visual Studio.

  3. Connectez-vous à l’aide du compte Microsoft Entra auquel vous avez attribué un rôle précédemment.

    Capture d’écran montrant la sélection de compte.

Envoyez des événements à l’Event Hub

Cette section montre comment créer une application console .NET Core pour envoyer des événements à un Event Hub que vous avez créé.

Création d’une application console

  1. Si Visual Studio 2022 est déjà ouvert, sélectionnez Fichier dans le menu, sélectionnez Nouveau, puis Projet. Sinon, lancez Visual Studio 2022 et sélectionnez Créer un projet si une fenêtre contextuelle s’affiche.

  2. Dans la boîte de dialogue Créer un projet, effectuez les étapes suivantes : Si vous ne voyez pas cette boîte de dialogue, sélectionnez Fichier dans le menu, sélectionnez Nouveau, puis Projet.

    1. Sélectionnez C# en guise de langage de programmation.

    2. Sélectionnez Console comme type de l’application.

    3. Sélectionnez Application console dans la liste des résultats.

    4. Ensuite, sélectionnez Suivant.

      Image représentant la boîte de dialogue Nouveau projet

  3. Entrez EventHubsSender comme nom de projet, EventHubsQuickStart comme nom de solution, puis sélectionnez Suivant.

    Image représentant la page permettant d’entrer le nom de la solution et celui du projet

  4. Sur la page Informations supplémentaires, sélectionnez Créer.

Ajouter les paquets NuGet au projet

  1. Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package à partir du menu.

  2. Exécutez les commandes suivantes pour installer les packages NuGet Azure.Messaging.EventHubs et Azure.Identity. Appuyez sur ENTRÉE pour exécuter la seconde commande.

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Identity
    

Écriture de code pour envoyer des événements au hub d’événements

  1. Remplacez le code existant dans le fichier Program.cs par l’exemple de code suivant. Ensuite, remplacez les valeurs d’espace réservé <EVENT_HUB_NAMESPACE> et <HUB_NAME> des paramètres EventHubProducerClient par les noms de votre espace de noms Event Hubs et du Event Hub Par exemple : "spehubns0309.servicebus.windows.net" et "spehub".

    Voici les étapes importantes du code :

    1. Crée un objet EventHubProducerClient à l’aide de l’espace de noms et du nom du hub d’événements.
    2. Appelle la méthode CreateBatchAsync sur l’objet EventHubProducerClient pour créer un objet EventDataBatch.
    3. Ajoutez des événements au lot à l’aide de la méthode EventDataBatch.TryAdd.
    4. Envoie le lot de messages à l’Event Hub à l’aide de la méthode EventHubProducerClient.SendAsync.
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Producer;
    using System.Text;
    
    // number of events to be sent to the event hub
    int numOfEvents = 3;
    
    // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when events are being published or read regularly.
    // TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
    EventHubProducerClient producerClient = new EventHubProducerClient(
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // Create a batch of events 
    using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();
    
    for (int i = 1; i <= numOfEvents; i++)
    {
        if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
        {
            // if it is too large for the batch
            throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
        }
    }
    
    try
    {
        // Use the producer client to send the batch of events to the event hub
        await producerClient.SendAsync(eventBatch);
        Console.WriteLine($"A batch of {numOfEvents} events has been published.");
        Console.ReadLine();
    }
    finally
    {
        await producerClient.DisposeAsync();
    }
    
  1. Générez le projet et vérifiez qu’il ne présente pas d’erreurs.

  2. Exécutez le programme et attendez le message de confirmation.

    A batch of 3 events has been published.
    

    Remarque

    Si vous obtenez une erreur « InvalidIssuer : L’émetteur de jeton n’est pas valide » lors de l’utilisation de l’authentification Microsoft Entra, cela peut être dû au fait que l’ID de locataire Entra utilisé est incorrect. Dans votre code, remplacez « new DefaultAzureCredential() » par « new DefaultAzureCredential(new DefaultAzureCredentialOptions {TenantId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}) » pour spécifier explicitement l’ID de locataire Entra.

    Important

    Si vous utilisez l’authentification sans mot de passe (contrôle d’accès en fonction du rôle d’Azure Active Directory), sélectionnez Outils, puis Options. Dans la fenêtre Options, développez Authentification par le service Azure, puis sélectionnez Sélection du compte. Vérifiez que vous utilisez le compte ajouté au rôle Propriétaire de données Azure Event Hubs sur l’espace de noms Event Hubs.

  3. Dans la page Espace de noms Event Hubs du portail Azure, vous voyez trois messages entrants dans le graphique Messages. Actualisez la page pour mettre à jour le graphique si nécessaire. Cela peut prendre quelques secondes pour indiquer que les messages ont été reçus.

    Image de la page du Portail Azure permettant de vérifier que le hub d’événements a reçu les événements

    Notes

    Pour obtenir le code source complet avec des remarques plus détaillées, consultez ce fichier sur GitHub

Recevez des événements de l’Event Hub

Cette section explique comment écrire une application console .NET Core qui reçoit des événements d’un hub d’événements à l’aide d’un processeur d’événements. Le processeur d’événements simplifie la réception des événements à partir des Event Hubs.

Créer un compte de stockage Azure et un conteneur d’objets blob

Dans ce guide de démarrage rapide, vous utilisez Stockage Azure comme magasin de points de contrôle. Suivez les étapes ci-dessous pour créer un compte Stockage Azure.

  1. Création d’un compte de stockage Azure
  2. Créer un conteneur d’objets blob
  3. Authentifiez-vous auprès du conteneur d’objets blob à l’aide de l’authentification Microsoft Entra ID (sans mot de passe) ou d’une chaîne de connexion à l’espace de noms.

Suivez les recommandations ci-dessous quand vous utilisez Stockage Blob Azure comme magasin de points de contrôle :

  • Utilisez un conteneur distinct pour chaque groupe de consommateurs. Vous pouvez utiliser le même compte de stockage, mais utiliser un conteneur par groupe.
  • N’utilisez pas le conteneur et le compte de stockage pour quoi que ce soit d’autre.
  • Le compte de stockage doit se trouver dans la même région que l’application déployée. Si l’application est locale, essayez de choisir la région la plus proche possible.

Sur la page Compte de stockage du Portail Azure, dans la section Service BLOB, vérifiez que les paramètres suivants sont désactivés.

  • Espace de noms hiérarchique
  • Suppression réversible de blob
  • Contrôle de version

Lors du développement local, assurez-vous que le compte d’utilisateur qui accède aux données blob dispose des autorisations appropriées. Vous aurez besoin du Contributeur aux données Blob de stockage pour lire et écrire des données blob. Pour vous attribuer ce rôle, vous aurez besoin du rôle Administrateur de l’accès utilisateur ou d’un autre rôle qui inclut l’action Microsoft.Authorization/roleAssignments/write. Vous pouvez attribuer des rôles RBAC Azure à un utilisateur à l’aide du Portail Azure, Azure CLI ou Azure PowerShell. Vous pouvez en savoir plus sur les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue .

Dans ce scénario, vous allez attribuer des autorisations à votre compte d’utilisateur, étendues au compte de stockage, pour suivre le Principe des privilèges minimum. Cette pratique offre aux utilisateurs uniquement les autorisations minimales nécessaires et crée des environnements de production plus sécurisés.

L’exemple suivant affecte le rôle Contributeur aux données Blob du stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données d’objet blob dans votre compte de stockage.

Important

Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes, mais dans de rares cas, cela peut prendre jusqu’à huit minutes. Si vous recevez des erreurs d’authentification lorsque vous exécutez votre code pour la première fois, patientez quelques instants et réessayez.

  1. Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.

  2. Dans la page vue d’ensemble du compte de stockage, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.

  3. Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.

  4. Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.

    Capture d’écran montrant comment affecter un rôle de compte de stockage.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données Blob du stockage, sélectionnez le résultat correspondant, puis choisissez Suivant.

  6. Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.

  7. Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail utilisateur@domaine), puis choisissez Sélectionner en bas de la boîte de dialogue.

  8. Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Créer un projet pour le récepteur

  1. Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur la solution EventHubQuickStart, pointez sur Ajouter, puis sélectionnez Nouveau projet.
  2. Sélectionnez Application console, puis Suivant.
  3. Entrez EventHubsReceiver pour Nom du projet, puis sélectionnez Créer.
  4. Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur EventHubsReceiver, puis sélectionnez Définir comme projet de démarrage.

Ajouter les paquets NuGet au projet

  1. Cliquez sur Outils>Gestionnaire de package NuGet>Console du Gestionnaire de package à partir du menu.

  2. Dans la fenêtre Console du gestionnaire de package, vérifiez que EventHubsReceiver est sélectionné pour le Projet par défaut. Si ce n’est pas le cas, utilisez la liste déroulante pour sélectionner EventHubsReceiver.

  3. Exécutez la commande suivante pour installer les packages NuGet Azure.Messaging.EventHubs et Azure.Identity : Appuyez sur ENTRÉE pour exécuter la dernière commande.

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Messaging.EventHubs.Processor
    Install-Package Azure.Identity
    

Mettez à jour le code

Remplacez le contenu du fichier Program.cs par le code suivant :

  1. Remplacez le code existant dans le fichier Program.cs par l’exemple de code suivant. Remplacez ensuite les valeurs d’espace réservé <STORAGE_ACCOUNT_NAME> et <BLOB_CONTAINER_NAME> pour l’URI BlobContainerClient. Remplacez également les valeurs d’espace réservé <EVENT_HUB_NAMESPACE> et <HUB_NAME> pour EventProcessorClient.

    Voici les étapes importantes du code :

    1. Crée un objet EventProcessorClient à l’aide de l’espace de noms et du nom des Event Hubs. Vous devez créer un objet BlobContainerClient pour le conteneur dans le stockage Azure que vous avez créé précédemment.
    2. Spécifie des gestionnaires pour les événements ProcessEventAsync et ProcessErrorAsync de l’objet EventProcessorClient.
    3. Démarre le traitement des événements en appelant StartProcessingAsync sur l’objet EventProcessorClient.
    4. Arrête le traitement des événements après 30 secondes en appelant StopProcessingAsync sur l’objet EventProcessorClient.
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Consumer;
    using Azure.Messaging.EventHubs.Processor;
    using Azure.Storage.Blobs;
    using System.Text;
    
    // Create a blob container client that the event processor will use
    // TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTAINER_NAME> with actual names
    BlobContainerClient storageClient = new BlobContainerClient(
        new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
        new DefaultAzureCredential());
    
    // Create an event processor client to process events in the event hub
    // TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
    var processor = new EventProcessorClient(
        storageClient,
        EventHubConsumerClient.DefaultConsumerGroupName,
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // Register handlers for processing events and handling errors
    processor.ProcessEventAsync += ProcessEventHandler;
    processor.ProcessErrorAsync += ProcessErrorHandler;
    
    // Start the processing
    await processor.StartProcessingAsync();
    
    // Wait for 30 seconds for the events to be processed
    await Task.Delay(TimeSpan.FromSeconds(30));
    
    // Stop the processing
    await processor.StopProcessingAsync();
    
    Task ProcessEventHandler(ProcessEventArgs eventArgs)
    {
        // Write the body of the event to the console window
        Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
    Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
    {
        // Write details about the error to the console window
        Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
        Console.WriteLine(eventArgs.Exception.Message);
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
  1. Générez le projet et vérifiez qu’il ne présente pas d’erreurs.

    Notes

    Pour obtenir le code source complet avec des remarques plus détaillées, consultez ce fichier sur GitHub.

  2. Exécutez l’application réceptrice.

  3. Vous devriez voir un message indiquant que les événements ont été reçus. Appuyez sur Entrée une fois qu’un message d’événement reçu s’affiche.

    Received event: Event 1
    Received event: Event 2
    Received event: Event 3    
    

    Ces événements sont les trois événements que vous avez envoyés au hub d’événements en exécutant le programme émetteur.

  4. Dans le portail Azure, vous pouvez vérifier qu’il existe trois messages sortants, qu’Event Hubs a envoyés à l’application de réception. Actualisez la page pour mettre à jour le graphique. Cela peut prendre quelques secondes pour indiquer que les messages ont été reçus.

    Image de la page du portail Azure pour vérifier que le hub d'événements a envoyé des événements à l'application réceptrice

Validation de schéma pour les applications basées sur le Kit de développement logiciel (SDK) Event Hubs

Vous pouvez utiliser Azure Schema Registry pour effectuer la validation de schéma lorsque vous diffusez des données avec vos applications basées sur le SDK Event Hubs. Azure Schema Registry of Event Hubs fournit un référentiel centralisé pour la gestion des schémas et vous pouvez connecter en toute transparence vos applications nouvelles ou existantes à Schema Registry.

Pour plus d’informations, consultez Valider des schémas avec le Kit de développement logiciel (SDK) Event Hubs.

Exemples et référence

Ce guide de démarrage rapide fournit des instructions pas à pas pour implémenter un scénario qui consiste à envoyer un lot d’évènements à un Event Hub, puis à les recevoir. Pour plus d’exemples, sélectionnez les liens suivants.

Pour obtenir des informations de référence complètes sur la bibliothèque .NET, consultez notre documentation du SDK.

Nettoyer les ressources

Supprimez le groupe de ressources qui a l’espace de noms Event Hubs ou supprimez uniquement l’espace de noms si vous souhaitez conserver le groupe de ressources.

Consultez le tutoriel suivant :