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

Article
04/28/2023

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

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.

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.

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
```

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

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

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.
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;
```
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.

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)
```
Enregistrez le fichier Program.cs.

Créer une file d’attente

Avant d’effectuer des appels dans les API Azure, vous devez obtenir vos informations d’identification à partir du portail Azure.

Copier vos informations d’identification depuis le portail Azure

Lorsque l’exemple d’application effectue une requête auprès du stockage Azure, il doit être autorisé. Pour autoriser une demande, ajoutez les informations d’identification de votre compte de stockage à l’application sous la forme d’une chaîne de connexion. Pour afficher les informations d’identification de votre compte de stockage, effectuez les étapes suivantes :

Connectez-vous au portail Azure.
Recherchez votre compte de stockage.
Dans le volet de menu du compte de stockage, sous Sécurité + réseau, sélectionnez Clés d’accès. Ici, vous pouvez afficher les clés d’accès du compte et la chaîne de connexion complète pour chaque clé.
Dans le volet Clés d’accès, sélectionnez Afficher les clés.
Dans la section clé1, recherchez la valeur Chaîne de connexion. Sélectionnez l’icône Copier dans le Presse-papiers pour copier la chaîne de connexion. Vous ajouterez la valeur de chaîne de connexion à une variable d’environnement dans la section suivante.

Configurer votre chaîne de connexion de stockage

Après avoir copié la chaîne de connexion, écrivez-la dans une variable d’environnement sur l’ordinateur local exécutant l’application. Pour définir la variable d’environnement, ouvrez une fenêtre de console et suivez les instructions pour votre système d’exploitation. Remplacez <yourconnectionstring> par votre chaîne de connexion.

Windows
Linux et macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Après avoir ajouté la variable d’environnement dans Windows, vous devez démarrer une nouvelle instance de la fenêtre de commande.

Redémarrer des programmes

Après avoir ajouté la variable d’environnement, redémarrez tous les programmes en cours d’exécution qui devront la lire. Par exemple, redémarrez l’environnement ou l’éditeur de développement avant de continuer.

Ajouter la chaîne de connexion à l’application

Ajoutez la chaîne de connexion à l’application afin qu’elle puisse accéder au compte de stockage.

Revenez à Visual Studio Code.
Dans la méthode Main, remplacez le code Console.WriteLine("Hello, World"); par la ligne suivante qui récupère la chaîne de connexion de la variable d’environnement.
```
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
```
Ajoutez le code suivant à Main pour créer un objet de file d’attente, qui sera passé plus tard dans les méthodes d’envoi et de réception.
```
QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
```
Enregistrez le fichier .

Insérer des messages dans la file d’attente

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

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);
}
```
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);
```
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.

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;
}
```
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.

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.";
    }
}

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.

Développez la méthode Main pour vérifier les arguments de la ligne de commande et attendre une entrée d’utilisateur.

static async Task Main(string[] args)
{
    string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

    QueueClient queue = new QueueClient(connectionString, "mystoragequeue");

    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();
}

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;

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

            QueueClient queue = new QueueClient(connectionString, "mystoragequeue");

            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

À 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
```
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..._
```
Exécutez l’application sans argument de ligne de commande pour recevoir et supprimer le premier message de la file d’attente.
```
dotnet run
```

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 à :

Créer une file d’attente
Ajouter et supprimer des messages dans une file d’attente
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.

Démarrage rapide des files d’attente pour le portail

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.