Prise en main des rubriques et abonnements Azure Service Bus (.NET)

Ce guide de démarrage rapide montre comment envoyer des messages à une rubrique Service Bus et recevoir des messages d’un abonnement à cette rubrique en utilisant la bibliothèque .NET Azure.Messaging.ServiceBus.

Dans ce guide de démarrage rapide, vous allez effectuer les étapes suivantes :

1. Créer un espace de noms Service Bus à l’aide du Portail Azure.
2. Créer une rubrique Service Bus à l’aide du Portail Azure.
3. Créer un abonnement Service Bus vers cette rubrique à l’aide du Portail Azure.
4. Écrivez une application de console .NET pour envoyer un ensemble de messages à la rubrique.
5. Écrivez une application de console .NET pour recevoir ces messages de l’abonnement.

Prérequis

Si vous débutez avec le service, consultez Vue d’ensemble de Service Bus avant de suivre ce démarrage rapide.

• Abonnement Azure. Pour utiliser des services Azure, dont Azure Service Bus, vous avez besoin d’un abonnement. Si vous n’avez pas de compte Azure existant, vous pouvez demander un essai gratuit.
• Visual Studio 2022. L’exemple d’application utilise les nouvelles fonctionnalités introduites dans C# 10. Vous pouvez toujours utiliser la bibliothèque cliente Service Bus avec les versions antérieures du langage C#, mais la syntaxe peut varier. Pour utiliser la dernière syntaxe, nous vous recommandons d’installer .NET 6.0 ou une version supérieure et de définir la version du langage sur latest. Si vous utilisez Visual Studio, les versions antérieures à Visual Studio 2022 ne sont pas compatibles avec les outils nécessaires à la génération de projets C# 10.

Créer un espace de noms dans le Portail Azure

Pour commencer à utiliser des entités de messagerie Service Bus dans Azure, vous devez d’abord créer un espace de noms avec un nom unique dans Azure. Un espace de noms fournit un conteneur d’étendue pour les ressources du Service Bus (files d’attente, thèmes, etc.) au sein de votre application.

Pour créer un espace de noms :

1. Connectez-vous au portail Azure.

2. Accédez à la page Tous les services.

3. Dans la barre de navigation gauche, sélectionnez Intégration dans la liste des catégories, pointez avec la souris sur Service Bus, puis sélectionnez le bouton + dans la vignette Service Bus.

   

4. Dans l’étiquette De base de la page Créer un espace de noms, suivez ces étapes :

   1. Pour l’option Abonnement, choisissez un abonnement Azure dans lequel créer l’espace de noms.

   2. Pour l’option Groupe de ressources, choisissez un groupe de ressources existant dans lequel l’espace de noms sera utilisé, ou créez-en un nouveau.

   3. Entrez un nom pour l’espace de noms. Le nom de l’espace de noms doit respecter les conventions de nommage suivantes :

      • Le nom doit être unique dans tout Azure. Le système vérifie immédiatement si le nom est disponible.
      • Le nom doit inclure entre 6 et 50 caractères.
      • Le nom ne peut contenir que des lettres, des chiffres et des traits d’union (« - »).
      • Le nom doit commencer par une lettre, et se terminer par une lettre ou un chiffre.
      • Le nom ne se termine ni par « -sb » ni par « -mgmt ».

   4. Pour l’option Emplacement, choisissez la région dans laquelle héberger votre espace de noms.

   5. Pour le Niveau tarifaire, sélectionnez le SKU (De base, Standard ou Premium) destiné à l’espace de noms. Pour ce guide de démarrage rapide, sélectionnez Standard.

      Important

      Si vous voulez utiliser des rubriques et des abonnements, choisissez Standard ou Premium. Les rubriques/abonnements ne sont pas pris en charge dans le niveau tarifaire De base.

      Si vous avez sélectionné le SKU Premium, précisez le nombre d’unité de messagerie. Le niveau Premium isole les ressources au niveau du processeur et de la mémoire, ce qui permet d’exécuter chaque charge de travail de manière isolée. Ce conteneur de ressources est appelé unité de messagerie. Un espace de noms Premium a au moins une unité de messagerie. Vous pouvez sélectionner 1, 2, 4, 8 ou 16 unités de messagerie pour chaque espace de noms Service Bus Premium. Pour plus d’informations, consultez Messagerie Service Bus Premium.

   6. Au bas de la page, sélectionnez Examiner et créer.

      

   7. Dans la page Vérifier + créer, passez en revue les paramètres, puis sélectionnez Créer.

5. Une fois le déploiement de la ressource réussi, sélectionnez Accéder à la ressource dans la page de déploiement.

   

6. Vous voyez la page d’accueil de votre espace de noms Service Bus.

   

Créer une rubrique à l’aide du Portail Azure

1. Dans la page Espace de noms Service Bus, sélectionnez Rubriques dans le menu de gauche.

2. Sélectionnez + Rubrique dans la barre d’outils.

3. Entrez un nom pour la rubrique. Conservez les valeurs par défaut des autres options.

4. Cliquez sur Créer.

   

Créer un abonnement à la rubrique

1. Sélectionnez la rubrique que vous avez créée dans la section précédente.

   

2. Dans la page Rubrique Service Bus, dans la barre d’outils, sélectionnez + Abonnement.

   

3. Dans la page Créer un abonnement, procédez comme suit :

   1. Entrez S1 pour le nom de l’abonnement.

   2. Entrez 3 pour Nombre maximal de remises.

   3. Ensuite, sélectionnez Créer pour créer l’abonnement.

      

Authentifier l’application sur Azure

Ce guide de démarrage pratique vous montre deux façons de vous connecter à Azure Service Bus : sans mot de passe et avec une chaîne de connexion.

La première option vous explique comment utiliser votre principal de sécurité dans Microsoft Entra ID et le contrôle d’accès en fonction du rôle (RBAC) pour vous connecter à un espace de noms Service Bus. Vous n’avez pas à vous soucier d’avoir une chaîne de connexion codée 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 Service Bus. Si vous débutez avec Azure, vous trouverez peut-être l’option 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.

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.

   

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

   

Envoyez des messages à la rubrique

Cette section montre comment créer une application console .NET pour envoyer des messages à une rubrique Service Bus.

Création d’une application console

1. Dans Visual Studio, sélectionnez le menu Fichier - >Nouveau - >Projet.
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.

      

3. Entrez TopicSender comme nom de projet, ServiceBusTopicQuickStart comme nom de solution, puis sélectionnez Suivant.
4. Dans la page Informations supplémentaires, sélectionnez Créer pour créer la solution et le projet.

Ajouter les paquets NuGet au projet

Ajouter du code pour envoyer des messages à la rubrique

1. Remplacez le contenu de Program.cs par le code suivant. Les étapes importantes sont décrites dans cette section, et vous trouverez des informations supplémentaires dans les commentaires de code.

   • Sans mot de passe
   • Chaîne de connexion

   1. Crée un objet ServiceBusClient à l’aide de l’objetDefaultAzureCredential. DefaultAzureCredential détecte et utilise automatiquement les informations d’identification de votre connexion Visual Studio pour vous authentifier auprès d’Azure Service Bus.
   2. Utilise la méthode CreateSender sur l’objet ServiceBusClient pour créer un objet ServiceBusSender pour la rubrique Service Bus spécifique.
   3. Crée un objet ServiceBusMessageBatch à l’aide de ServiceBusSender.CreateMessageBatchAsync.
   4. Ajoutez des messages au lot à l’aide de ServiceBusMessageBatch.TryAddMessage.
   5. Envoie le lot de messages à la rubrique Service Bus avec la méthode ServiceBusSender.SendMessagesAsync.

   Important

   Remplacez les valeurs d’espace réservé (<NAMESPACE-NAME> et <TOPIC-NAME>) dans l’extrait de code par les noms de votre espace de noms et de votre rubrique Service Bus.

   using System.Threading.Tasks;
   using Azure.Messaging.ServiceBus;
   using Azure.Identity;
   
   // the client that owns the connection and can be used to create senders and receivers
   ServiceBusClient client;
   
   // the sender used to publish messages to the topic
   ServiceBusSender sender;
   
   // number of messages to be sent to the topic
   const int numOfMessages = 3;
   
   // The Service Bus client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when messages are being published or read
   // regularly.
   
   //TODO: Replace the "<NAMESPACE-NAME>" and "<TOPIC-NAME>" placeholders.
   client = new ServiceBusClient(
       "<NAMESPACE-NAME>.servicebus.windows.net",
       new DefaultAzureCredential());
   sender = client.CreateSender("<TOPIC-NAME>");
   
   // create a batch 
   using ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();
   
   for (int i = 1; i <= numOfMessages; i++)
   {
       // try adding a message to the batch
       if (!messageBatch.TryAddMessage(new ServiceBusMessage($"Message {i}")))
       {
           // if it is too large for the batch
           throw new Exception($"The message {i} is too large to fit in the batch.");
       }
   }
   
   try
   {
       // Use the producer client to send the batch of messages to the Service Bus topic
       await sender.SendMessagesAsync(messageBatch);
       Console.WriteLine($"A batch of {numOfMessages} messages has been published to the topic.");
   }
   finally
   {
       // Calling DisposeAsync on client types is required to ensure that network
       // resources and other unmanaged objects are properly cleaned up.
       await sender.DisposeAsync();
       await client.DisposeAsync();
   }
   
   Console.WriteLine("Press any key to end the application");
   Console.ReadKey();
   

2. Générez le projet et vérifiez qu’il ne présente pas d’erreurs.

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

   A batch of 3 messages has been published to the topic
   

   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, il 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.

4. Dans le portail Azure, procédez comme suit :

   1. Accédez à votre espace de noms Service Bus.

   2. Dans la page Vue d’ensemble, dans le volet central inférieur, basculez vers l’onglet Rubriques, puis sélectionnez la rubrique Service Bus. Dans l’exemple suivant, il s’agit de mytopic.

      

   3. Dans la page Rubrique Service Bus, dans le graphique Messages de la section inférieure Métriques, vous pouvez voir trois messages entrants pour la rubrique. Si vous ne voyez pas cette valeur, attendez quelques minutes, puis actualisez la page pour voir le graphique mis à jour.

      

   4. Sélectionnez l’abonnement dans le volet inférieur. Dans l’exemple suivant, il s’agit de S1. Dans la page Abonnement Service Bus, vous voyez que Nombre de messages actifs a pour valeur 3. L’abonnement a reçu les trois messages que vous avez envoyés à la rubrique, mais aucun destinataire ne les a encore sélectionnés.

      

Réception des messages d’un abonnement

Dans cette section, vous créez une application console .NET qui reçoit les messages de l’abonnement à la rubrique Service Bus.

Créer un projet pour le récepteur

1. Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur la solution ServiceBusTopicQuickStart, pointez sur Ajouter, puis sélectionnez Nouveau projet.
2. Sélectionnez Application console, puis Suivant.
3. Entrez SubscriptionReceiver comme Nom du projet, puis sélectionnez Suivant.
4. Sur la page Informations supplémentaires, sélectionnez Créer.
5. Dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit sur SubscriptionReceiver, puis sélectionnez Définir comme projet de démarrage.

Ajouter les paquets NuGet au projet

Ajouter du code pour recevoir des messages de l’abonnement

Dans cette section, vous ajoutez du code pour récupérer les messages de l’abonnement.

1. Remplacez le contenu existant de Program.cs par les propriétés et méthodes suivantes :

   • Sans mot de passe
   • Chaîne de connexion

   using System.Threading.Tasks;
   using Azure.Messaging.ServiceBus;
   using Azure.Identity;
   
   // the client that owns the connection and can be used to create senders and receivers
   ServiceBusClient client;
   
   // the processor that reads and processes messages from the subscription
   ServiceBusProcessor processor;    
   
   // handle received messages
   async Task MessageHandler(ProcessMessageEventArgs args)
   {
       string body = args.Message.Body.ToString();
       Console.WriteLine($"Received: {body} from subscription.");
   
       // complete the message. messages is deleted from the subscription. 
       await args.CompleteMessageAsync(args.Message);
   }
   
   // handle any errors when receiving messages
   Task ErrorHandler(ProcessErrorEventArgs args)
   {
       Console.WriteLine(args.Exception.ToString());
       return Task.CompletedTask;
   }
   

2. Ajoutez le code suivant à la fin de Program.cs.

   • Sans mot de passe
   • Chaîne de connexion

   • Crée un objet ServiceBusClient à l’aide de l’objetDefaultAzureCredential. DefaultAzureCredential détecte et utilise automatiquement les informations d’identification de votre connexion Visual Studio pour vous authentifier auprès d’Azure Service Bus.
   • Appelle la méthode CreateProcessor sur l'objet ServiceBusClient pour créer un objet ServiceBusProcessor pour la rubrique Service Bus spécifiée.
   • Spécifie des gestionnaires pour les événements ProcessMessageAsync et ProcessErrorAsync de l’objet ServiceBusProcessor.
   • Démarre le traitement des messages en appelant StartProcessingAsync sur l' objet ServiceBusProcessor.
   • Lorsque l’utilisateur appuie sur une clé pour terminer le traitement, il appelle StopProcessingAsync sur l' objet ServiceBusProcessor.

   Important

   Remplacez les valeurs d’espace réservé (<NAMESPACE-NAME>, <TOPIC-NAME> et <SUBSCRIPTION-NAME>) dans l’extrait de code par les noms de votre espace de noms, de votre rubrique et de votre abonnement Service Bus.

   Pour plus d'informations, consultez les commentaires du code.

   // The Service Bus client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when messages are being published or read
   // regularly.
   //
   // Create the clients that we'll use for sending and processing messages.
   // TODO: Replace the <NAMESPACE-NAME> placeholder
   client = new ServiceBusClient(
       "<NAMESPACE-NAME>.servicebus.windows.net",
       new DefaultAzureCredential());
   
   // create a processor that we can use to process the messages
   // TODO: Replace the <TOPIC-NAME> and <SUBSCRIPTION-NAME> placeholders
   processor = client.CreateProcessor("<TOPIC-NAME>", "<SUBSCRIPTION-NAME>", new ServiceBusProcessorOptions());
   
   try
   {
       // add handler to process messages
       processor.ProcessMessageAsync += MessageHandler;
   
       // add handler to process any errors
       processor.ProcessErrorAsync += ErrorHandler;
   
       // start processing 
       await processor.StartProcessingAsync();
   
       Console.WriteLine("Wait for a minute and then press any key to end the processing");
       Console.ReadKey();
   
       // stop processing 
       Console.WriteLine("\nStopping the receiver...");
       await processor.StopProcessingAsync();
       Console.WriteLine("Stopped receiving messages");
   }
   finally
   {
       // Calling DisposeAsync on client types is required to ensure that network
       // resources and other unmanaged objects are properly cleaned up.
       await processor.DisposeAsync();
       await client.DisposeAsync();
   }
   

3. Voici à quoi doit ressembler votre fichier Program.cs :

   • Sans mot de passe
   • Chaîne de connexion

   using System;
   using System.Threading.Tasks;
   using Azure.Messaging.ServiceBus;
   using Azure.Identity;
   
   // the client that owns the connection and can be used to create senders and receivers
   ServiceBusClient client;
   
   // the processor that reads and processes messages from the subscription
   ServiceBusProcessor processor;
   
   // handle received messages
   async Task MessageHandler(ProcessMessageEventArgs args)
   {
       string body = args.Message.Body.ToString();
       Console.WriteLine($"Received: {body} from subscription.");
   
       // complete the message. messages is deleted from the subscription. 
       await args.CompleteMessageAsync(args.Message);
   }
   
   // handle any errors when receiving messages
   Task ErrorHandler(ProcessErrorEventArgs args)
   {
       Console.WriteLine(args.Exception.ToString());
       return Task.CompletedTask;
   }
   
   // The Service Bus client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when messages are being published or read
   // regularly.
   //
   // Create the clients that we'll use for sending and processing messages.
   // TODO: Replace the <NAMESPACE-NAME> placeholder
   client = new ServiceBusClient(
       "<NAMESPACE-NAME>.servicebus.windows.net",
       new DefaultAzureCredential());
   
   // create a processor that we can use to process the messages
   // TODO: Replace the <TOPIC-NAME> and <SUBSCRIPTION-NAME> placeholders
   processor = client.CreateProcessor("<TOPIC-NAME>", "<SUBSCRIPTION-NAME>", new ServiceBusProcessorOptions());
   
   try
   {
       // add handler to process messages
       processor.ProcessMessageAsync += MessageHandler;
   
       // add handler to process any errors
       processor.ProcessErrorAsync += ErrorHandler;
   
       // start processing 
       await processor.StartProcessingAsync();
   
       Console.WriteLine("Wait for a minute and then press any key to end the processing");
       Console.ReadKey();
   
       // stop processing 
       Console.WriteLine("\nStopping the receiver...");
       await processor.StopProcessingAsync();
       Console.WriteLine("Stopped receiving messages");
   }
   finally
   {
       // Calling DisposeAsync on client types is required to ensure that network
       // resources and other unmanaged objects are properly cleaned up.
       await processor.DisposeAsync();
       await client.DisposeAsync();
   }
   

4. Générez le projet et vérifiez qu’il ne présente pas d’erreurs.

5. Exécutez l’application réceptrice. Vous devriez voir les messages reçus. Appuyez sur n’importe quelle touche pour arrêter le récepteur et l’application.

   Wait for a minute and then press any key to end the processing
   Received: Message 1 from subscription: S1
   Received: Message 2 from subscription: S1
   Received: Message 3 from subscription: S1
   
   Stopping the receiver...
   Stopped receiving messages
   

6. Vérifiez à nouveau le portail.

   • Dans la page Rubrique Service Bus, dans le graphique Messages, vous voyez trois messages entrants et trois messages sortants. Si vous ne voyez pas ces valeurs, attendez quelques minutes et actualisez la page pour voir une mise à jour du graphique.

     

   • Dans la page Abonnement Service Bus, vous voyez que Nombre de messages actifs est égal à zéro. Cela est dû au fait qu’un destinataire a reçu des messages de cet abonnement et a terminé les messages.

     

Étapes suivantes

Consultez la documentation et les exemples suivants :

• Bibliothèque de client Azure Service Bus pour .NET – Fichier Lisez-moi
• Échantillons .NET pour Azure Service Bus sur GitHub
• Informations de référence sur l’API .NET