Lire en anglais

Partager via


Tutoriel : Utiliser des files d’attente Stockage File d’attente Azure dans .NET

Stockage File d’attente Azure implémente des files d’attente cloud pour permettre la communication entre les composants d’une application distribuée. Chaque file d’attente gère une liste de messages qui peuvent être ajoutés par un composant expéditeur et traités par un composant récepteur. Avec une file d’attente, votre application peut être mise à l’échelle immédiatement pour répondre à la demande. Cet article montre les étapes de base pour travailler avec une file d’attente Stockage File d’attente Azure.

Dans ce tutoriel, vous allez apprendre à :

  • Créer un compte Stockage Azure
  • Créer l’application
  • Ajouter des bibliothèques clientes Azure
  • Ajouter la prise en charge du code asynchrone
  • Créer une file d’attente
  • Insérer des messages dans une file d’attente
  • Enlever des messages d’une file d’attente
  • Supprimer une file d’attente vide
  • Vérifier les arguments de la ligne de commande
  • Générer et exécuter l’application

Prérequis

  • Procurez-vous votre copie gratuite de l’éditeur Visual Studio Code multiplateforme.
  • Téléchargez et installez le kit SDK .NET Core version 3.1 ou ultérieure.
  • Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Créer un compte de stockage Azure

  1. Commencez par créer un compte Stockage Azure.

    Pour obtenir un guide pas à pas de la création d’un compte de stockage, consultez Créer un compte de stockage. Il s’agit d’une étape distincte que vous effectuez après avoir créé un compte Azure gratuit dans les prérequis.

  2. Assurez-vous que votre compte utilisateur a reçu le rôle Contributeur aux données de file d’attente du stockage, limité au compte de stockage, au groupe de ressources parent ou à l'abonnement. Consultez Authentification auprès d’Azure AD.

Créer l’application

Créez une application .NET Core nommée QueueApp. Par souci pratique, cette application envoie et reçoit des messages via la file d’attente.

  1. Dans une fenêtre de console (telle que cmd, PowerShell ou Azure CLI), utilisez la commande dotnet new pour créer une application de console avec le nom QueueApp. Cette commande crée un projet C# « hello world » simple avec un seul fichier source nommé Program.cs.

    dotnet new console -n QueueApp
    
  2. Accédez au dossier QueueApp nouvellement créé et générez l’application pour vérifier que tout est en ordre.

    cd QueueApp
    
    dotnet build
    

    Vous obtenez normalement des résultats similaires à la sortie suivante :

    C:\Tutorials>dotnet new console -n QueueApp
    The template "Console Application" was created successfully.
    
    Processing post-creation actions...
    Running 'dotnet restore' on QueueApp\QueueApp.csproj...
      Restore completed in 155.63 ms for C:\Tutorials\QueueApp\QueueApp.csproj.
    
    Restore succeeded.
    
    C:\Tutorials>cd QueueApp
    
    C:\Tutorials\QueueApp>dotnet build
    Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
    Copyright (C) Microsoft Corporation. All rights reserved.
    
      Restore completed in 40.87 ms for C:\Tutorials\QueueApp\QueueApp.csproj.
      QueueApp -> C:\Tutorials\QueueApp\bin\Debug\netcoreapp3.1\QueueApp.dll
    
    Build succeeded.
        0 Warning(s)
        0 Error(s)
    
    Time Elapsed 00:00:02.40
    
    C:\Tutorials\QueueApp>_
    

Ajouter des bibliothèques clientes Azure

  1. Ajoutez les bibliothèques clientes du stockage Azure au projet à l’aide de la commande dotnet add package.

    Exécutez la commande suivante à partir du dossier du projet dans la fenêtre de console.

    dotnet add package Azure.Storage.Queues
    

Ajouter des instructions using

  1. Sur la ligne de commande dans le répertoire du projet, tapez code . pour ouvrir Visual Studio Code dans le répertoire actif. Laissez ouverte la fenêtre de ligne de commande. Il y aura d’autres commandes à exécuter plus tard. Si vous êtes invité à ajouter des ressources C# nécessaires pour générer et déboguer, cliquez sur le bouton Oui.

  2. Ouvrez le fichier source Program.cs et ajoutez les espaces de noms suivants juste après l’instruction using System;. Cette application utilise des types provenant de ces espaces de noms pour se connecter à Stockage Azure et pour utiliser des files d’attente.

    using System.Threading.Tasks;
    using Azure.Storage.Queues;
    using Azure.Storage.Queues.Models;
    
  3. Enregistrez le fichier Program.cs.

Ajouter la prise en charge du code asynchrone

Comme l’application utilise des ressources cloud, le code s’exécute de façon asynchrone.

  1. Mettez à jour la méthode Main pour qu’elle s’exécute de façon asynchrone. Remplacez void par une valeur de retour async Task.

    static async Task Main(string[] args)
    
  2. Enregistrez le fichier Program.cs.

Créer une file d’attente

Avant d’appeler des API Azure, vous devez vérifier que vous êtes authentifié avec le même compte Microsoft Entra auquel vous avez attribué le rôle. Une fois authentifié, vous pouvez créer et autoriser un objet QueueClientà l’aide deDefaultAzureCredential pour accéder aux données de file d’attente dans le compte de stockage. DefaultAzureCredential découvre et utilise automatiquement le compte avec lequel vous vous êtes connecté. Pour savoir comment vous connecter, puis créer un objet QueueClient, consultez Autoriser l’accès et créer un objet client.

Insérer des messages dans la file d’attente

Créez une méthode pour envoyer un message dans la file d’attente.

  1. Ajoutez la méthode InsertMessageAsync suivante dans votre classe Program.

    Une référence de file d’attente est passée à cette méthode. Si elle n’existe pas déjà, une nouvelle file d’attente est créée en appelant CreateIfNotExistsAsync. Ensuite, elle ajoute newMessage à la file d’attente en appelant SendMessageAsync.

    static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
    {
        if (null != await theQueue.CreateIfNotExistsAsync())
        {
            Console.WriteLine("The queue was created.");
        }
    
        await theQueue.SendMessageAsync(newMessage);
    }
    
  2. Facultatif : Par défaut, la durée de vie maximale d’un message est définie sur sept jours. Vous pouvez spécifier n’importe quel nombre positif pour la durée de vie du message. L’extrait de code suivant ajoute un message qui n’expire jamais.

    Pour ajouter un message qui n’expire pas, utilisez Timespan.FromSeconds(-1) dans votre appel à SendMessageAsync.

    await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
    
  3. Enregistrez le fichier .

Le format d’un message de file d’attente doit être compatible avec une demande XML utilisant l’encodage UTF-8. La taille maximale d’un message est de 64 Ko. Si un message contient des données binaires, encodez au format Base64 le message.

Enlever des messages d’une file d’attente

Créez une méthode pour récupérer un message de la file d’attente. Une fois que le message est effectivement reçu, il est important de le supprimer de la file d’attente pour qu’il ne soit pas traité plusieurs fois.

  1. Ajoutez une nouvelle méthode appelée RetrieveNextMessageAsync à votre classe Program.

    Cette méthode reçoit un message de la file d’attente en appelant ReceiveMessagesAsync, en passant 1 dans le premier paramètre pour ne récupérer que le message suivant dans la file d’attente. Une fois le message reçu, supprimez-le de la file d’attente en appelant DeleteMessageAsync.

    Quand un message est envoyé à la file d’attente avec une version du SDK antérieure à v12, il est automatiquement encodé en Base64. À compter de la version v12, cette fonctionnalité a été supprimée. Quand vous récupérez un message en utilisant le SDK v12, il n’est pas décodé automatiquement en base64. Vous devez décoder le contenu en Base64 vous-même.

    static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
    {
        if (await theQueue.ExistsAsync())
        {
            QueueProperties properties = await theQueue.GetPropertiesAsync();
    
            if (properties.ApproximateMessagesCount > 0)
            {
                QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
                string theMessage = retrievedMessage[0].Body.ToString();
                await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                return theMessage;
            }
    
            return null;
        }
    
        return null;
    }
    
  2. Enregistrez le fichier .

Supprimer une file d’attente vide

C’est une bonne pratique à la fin d’un projet que de déterminer si vous avez toujours besoin des ressources que vous avez créées. Les ressources laissées en cours d’exécution peuvent vous coûter de l’argent. Si la file d’attente existe mais qu’est vide, demandez à l’utilisateur s’il veut la supprimer.

  1. Développez la méthode RetrieveNextMessageAsync pour y inclure une invite de suppression de la file d’attente vide.

    static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
    {
        if (await theQueue.ExistsAsync())
        {
            QueueProperties properties = await theQueue.GetPropertiesAsync();
    
            if (properties.ApproximateMessagesCount > 0)
            {
                QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
                string theMessage = retrievedMessage[0].Body.ToString();
                await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                return theMessage;
            }
            else
            {
                Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
                string response = Console.ReadLine();
    
                if (response.ToUpper() == "Y")
                {
                    await theQueue.DeleteIfExistsAsync();
                    return "The queue was deleted.";
                }
                else
                {
                    return "The queue was not deleted.";
                }
            }
        }
        else
        {
            return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
        }
    }
    
  2. Enregistrez le fichier .

Vérifier les arguments de la ligne de commande

Si des arguments de ligne de commande sont passés dans l’application, supposons qu’il s’agisse d’un message à ajouter à la file d’attente. Joignez ensemble les arguments pour en faire une chaîne. Ajoutez cette chaîne à la file d’attente des messages en appelant la méthode InsertMessageAsync que nous avons ajoutée précédemment.

S’il n’y a pas d’arguments de ligne de commande, tentez une opération de récupération. Appelez la méthode RetrieveNextMessageAsync pour récupérer le message suivant dans la file d’attente.

Enfin, attendez une entrée utilisateur avant de quitter en appelant Console.ReadLine.

  1. Développez la méthode Main pour vérifier les arguments de la ligne de commande et attendre une entrée d’utilisateur. Dans cet extrait de code ci-dessous, assurez-vous de remplacer l’espace réservé {storageAccountName} par le nom de votre compte de stockage.

    static async Task Main(string[] args)
    {
       QueueClient queue = new QueueClient(
          new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
          new DefaultAzureCredential());
    
       if (args.Length > 0)
       {
          string value = String.Join(" ", args);
          await InsertMessageAsync(queue, value);
          Console.WriteLine($"Sent: {value}");
       }
       else
       {
          string value = await RetrieveNextMessageAsync(queue);
          Console.WriteLine($"Received: {value}");
       }
    
       Console.Write("Press Enter...");
       Console.ReadLine();
    }
    
  2. Enregistrez le fichier.

Code complet

Voici le code complet pour ce projet.

using System;
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using Azure.Identity;

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            QueueClient queue = new QueueClient(
               new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
               new DefaultAzureCredential());

            if (args.Length > 0)
            {
                string value = String.Join(" ", args);
                await InsertMessageAsync(queue, value);
                Console.WriteLine($"Sent: {value}");
            }
            else
            {
                string value = await RetrieveNextMessageAsync(queue);
                Console.WriteLine($"Received: {value}");
            }

            Console.Write("Press Enter...");
            Console.ReadLine();
        }

        static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
        {
            if (null != await theQueue.CreateIfNotExistsAsync())
            {
                Console.WriteLine("The queue was created.");
            }

            await theQueue.SendMessageAsync(newMessage);
        }

        static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
        {
            if (await theQueue.ExistsAsync())
            {
                QueueProperties properties = await theQueue.GetPropertiesAsync();

                if (properties.ApproximateMessagesCount > 0)
                {
                    QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
                    string theMessage = retrievedMessage[0].Body.ToString();
                    await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                    return theMessage;
                }
                else
                {
                    Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
                    string response = Console.ReadLine();

                    if (response.ToUpper() == "Y")
                    {
                        await theQueue.DeleteIfExistsAsync();
                        return "The queue was deleted.";
                    }
                    else
                    {
                        return "The queue was not deleted.";
                    }
                }
            }
            else
            {
                return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
            }
        }
    }
}

Générer et exécuter l’application

  1. À partir de la ligne de commande dans le répertoire du projet, exécutez la commande dotnet suivante pour générer le projet.

    dotnet build
    
  2. Une fois le projet correctement généré, exécutez la commande suivante pour ajouter le premier message à la file d’attente.

    dotnet run First queue message
    

    Cette sortie doit s’afficher :

    C:\Tutorials\QueueApp>dotnet run First queue message
    The queue was created.
    Sent: First queue message
    Press Enter..._
    
  3. Exécutez l’application sans argument de ligne de commande pour recevoir et supprimer le premier message de la file d’attente.

    dotnet run
    
  4. Continuer à exécuter l’application jusqu’à ce que tous les messages soient supprimés. Si vous l’exécutez une fois de plus, vous obtenez un message indiquant que la file d’attente est vide et une invite pour supprimer la file d’attente.

    C:\Tutorials\QueueApp>dotnet run First queue message
    The queue was created.
    Sent: First queue message
    Press Enter...
    
    C:\Tutorials\QueueApp>dotnet run Second queue message
    Sent: Second queue message
    Press Enter...
    
    C:\Tutorials\QueueApp>dotnet run Third queue message
    Sent: Third queue message
    Press Enter...
    
    C:\Tutorials\QueueApp>dotnet run
    Received: First queue message
    Press Enter...
    
    C:\Tutorials\QueueApp>dotnet run
    Received: Second queue message
    Press Enter...
    
    C:\Tutorials\QueueApp>dotnet run
    Received: Third queue message
    Press Enter...
    
    C:\Tutorials\QueueApp>dotnet run
    The queue is empty. Attempt to delete it? (Y/N) Y
    Received: The queue was deleted.
    Press Enter...
    
    C:\Tutorials\QueueApp>_
    

Étapes suivantes

Dans ce didacticiel, vous avez appris à :

  1. Créer une file d’attente
  2. Ajouter et supprimer des messages dans une file d’attente
  3. Supprimer une file d’attente Stockage File d’attente Azure

Pour plus d’informations, consultez les guides de démarrage rapide de Stockage File d’attente Azure.

Pour obtenir des exemples de code associés utilisant des Kits de développement logiciel (SDK) .NET version 11.x dépréciés, consultez l’article Exemples de code utilisant .NET version 11.x.