Démarrage rapide : bibliothèque cliente Stockage File d’attente Azure pour .NET

Familiarisez-vous avec la bibliothèque de client Storage File d’attente Azure pour .NET. Le Stockage File d’attente Azure est un service permettant de stocker un grand nombre de messages dans le but de les récupérer et de les traiter plus tard. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (NuGet) | Exemples

Utilisez la bibliothèque de client Stockage File d’attente Azure pour .NET afin d’effectuer les opérations suivantes :

• Créer une file d’attente
• Ajouter des messages à une file d’attente
• Afficher un aperçu des messages d’une file d’attente
• Mettre à jour un message dans une file d’attente
• Obtention de la longueur de la file d'attente
• Recevoir les messages d’une file d’attente
• Supprimer des messages d’une file d’attente
• Suppression d'une file d'attente

Prérequis

• Abonnement Azure : créez-en un gratuitement
• Compte de stockage Azure : créez un compte de stockage
• Dernière version du SDK .NET pour votre système d’exploitation. Veillez à disposer du Kit de développement logiciel (SDK), et non du runtime.

Configuration

Cette section vous guide tout au long de la préparation d’un projet à utiliser avec la bibliothèque de client Stockage File d’attente Azure pour .NET.

Créer le projet

Créer une application .NET nommée QueuesQuickstart.

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

   dotnet new console -n QueuesQuickstart
   

2. Basculez vers le répertoire QueuesQuickstart nouvellement créé.

   cd QueuesQuickstart
   

Installer les packages

Alors que vous êtes toujours dans le répertoire de l’application, installez le package de la bibliothèque de client Stockage File d’attente Azure pour .NET à l’aide de la commande dotnet add package.

dotnet add package Azure.Storage.Queues

Le package de bibliothèque de client Azure Identity est également nécessaire pour les connexions sans mot de passe aux services Azure.

dotnet add package Azure.Identity

Configurer le framework d’application

1. Ouvrez le projet dans l’éditeur de votre choix
2. Ouvrez le fichier Program.cs
3. Mettez à jour le code existant pour le faire correspondre à l’élément suivant :

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

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

Authentification auprès d’Azure

Les requêtes d’application vers les Services Azure doivent être autorisées. L’utilisation de la classe DefaultAzureCredential fournie par la bibliothèque de client Azure Identity est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code.

Vous pouvez également autoriser directement les requêtes adressées aux services Azure à l’aide de mots de passe, de chaînes de connexion ou d’autres informations d’identification. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer les secrets dans un emplacement non sécurisé. Toute personne ayant accès au mot de passe ou à la clé secrète est en mesure de s’authentifier. DefaultAzureCredential offre des avantages améliorés en matière de gestion et de sécurité par rapport à la clé de compte pour autoriser l’authentification sans mot de passe. Les deux options sont illustrées dans l’exemple suivant.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Modèle objet

Stockage File d’attente Azure est un service permettant de stocker un grand nombre de messages. La taille maximale d’un message de file d’attente est de 64 Ko. Une file d’attente peut contenir des millions de messages, dans la limite de la capacité totale d’un compte de stockage. Les files d’attente sont couramment utilisées pour créer un backlog de travail à traiter de façon asynchrone. Le Stockage File d’attente offre trois types de ressources :

• Compte de stockage : Tous les accès à Azure Storage passent par un compte de stockage. Pour plus d’informations sur les comptes de stockage, consultez Vue d’ensemble des comptes de stockage.
• File d’attente : une file d’attente contient un ensemble de messages. Tous les messages doivent être dans une file d’attente. Notez que le nom de la file d’attente doit être en minuscules. Pour plus d'informations sur l’affectation de noms à des files d’attente, consultez Affectation de noms pour les files d'attente et les métadonnées.
• Message : message dans n’importe quel format d’une taille maximale de 64 Ko. Un message peut rester dans la file d’attente pendant un maximum de 7 jours. Pour les versions du 29 juillet 2017 ou ultérieures, la durée de vie maximale peut être n’importe quel nombre positif, ou -1 indiquant que le message n’expire pas. Si ce paramètre est omis, la valeur par défaut de la durée de vie est de sept jours.

Le diagramme suivant montre la relation entre ces ressources.

Utilisez les classes .NET suivantes pour interagir avec ces ressources :

• QueueServiceClient : QueueServiceClient vous permet de gérer toutes les files d’attente de votre compte de stockage.
• QueueClient : la classe QueueClient vous permet de gérer et de manipuler une file d’attente individuelle et ses messages.
• QueueMessage : la classe QueueMessage représente les objets individuels retournés lors de l’appel de ReceiveMessages dans une file d’attente.

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les actions suivantes avec la bibliothèque de client Stockage File d’attente Azure pour .NET :

• Autoriser l’accès et créer un objet client
• Créer une file d’attente
• Ajouter des messages à une file d’attente
• Afficher un aperçu des messages d’une file d’attente
• Mettre à jour un message dans une file d’attente
• Obtention de la longueur de la file d'attente
• Recevoir les messages d’une file d’attente
• Supprimer des messages d’une file d’attente
• Supprimer une file d’attente

az login

az login

Connect-AzAccount

using Azure.Identity;

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable called
// AZURE_STORAGE_CONNECTION_STRING on the machine running the application.
// If the environment variable is created after the application is launched
// in a console or with Visual Studio, the shell or application needs to be
// closed and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

// Create a unique name for the queue
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(connectionString, queueName);

Créer une file d’attente

Avec l’objet QueueClient, appelez la méthode CreateAsync pour créer la file d’attente dans votre compte de stockage.

Ajoutez ce code à la fin de la méthode Program.cs :

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

Ajouter des messages à une file d’attente

L’extrait de code suivant ajoute de façon asynchrone des messages à la file d’attente en appelant la méthode SendMessageAsync. Il enregistre également un SendReceipt retourné à partir d’un appel de SendMessageAsync. La réception est utilisée pour mettre à jour le message ultérieurement dans le programme.

Ajoutez ce code à la fin du fichier Program.cs :

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

Afficher un aperçu des messages d’une file d’attente

Affichez un aperçu des messages de la file d’attente en appelant la méthode PeekMessagesAsync. Cette méthode récupère un ou plusieurs messages du début de la file d’attente, mais ne modifie pas la visibilité du message.

Ajoutez ce code à la fin du fichier Program.cs :

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

Mettre à jour un message dans une file d’attente

Mettez à jour le contenu d’un message en appelant la méthode UpdateMessageAsync. Cette méthode peut changer le contenu et le délai d’expiration de la visibilité d’un message. Le contenu du message doit être une chaîne encodée en UTF-8 d’une taille maximale de 64 Ko. Avec le nouveau contenu du message, transmettez les valeurs du SendReceipt qui a été enregistré dans le code. Les valeurs SendReceipt identifient le message à mettre à jour.

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

Obtention de la longueur de la file d'attente

Vous pouvez obtenir une estimation du nombre de messages dans une file d'attente. La méthode GetProperties retourne les propriétés de file d’attente, y compris le nombre de messages. La propriété ApproximateMessagesCount contient le nombre approximatif de messages dans la file d’attente. Ce nombre n’est pas inférieur au nombre de messages réel dans la file d’attente, mais il peut être supérieur.

Ajoutez ce code à la fin du fichier Program.cs :

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

Réception des messages d'une file d'attente

Téléchargez les messages ajoutés en appelant la méthode ReceiveMessagesAsync.

Ajoutez ce code à la fin du fichier Program.cs :

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

Vous pouvez éventuellement spécifier une valeur pour maxMessages, qui correspond au nombre de messages à récupérer dans la file d’attente. La valeur par défaut est de 1 message et la valeur maximale est de 32 messages. Vous pouvez également spécifier une valeur pour visibilityTimeout, qui masque les messages aux autres opérations pendant la période d’expiration. La valeur par défaut est 30 secondes.

Supprimer des messages d’une file d’attente

Supprimez les messages de la file d’attente une fois qu’ils ont été traités. Dans ce cas, le traitement affiche simplement le message sur la console.

Avant de traiter et de supprimer les messages, l’application s’interrompt dans l’attente d’une entrée de l’utilisateur en appelant Console.ReadLine. Vérifiez dans votre portail Azure que les ressources ont été créées correctement avant d’être supprimées. Les messages qui ne sont pas supprimés explicitement redeviennent visibles dans la file d’attente et peuvent éventuellement être de nouveau traités.

Ajoutez ce code à la fin du fichier Program.cs :

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

Suppression d'une file d'attente

Le code suivant nettoie les ressources créées par l’application en supprimant la file d’attente avec la méthode DeleteAsync.

Ajoutez ce code à la fin du fichier Program.cs :

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

Exécuter le code

Cette application crée trois messages et les ajoute à une file d’attente Azure. Le code liste les messages dans la file d’attente, puis les récupère et les supprime avant de supprimer la file d’attente.

Dans la fenêtre de votre console, accédez au répertoire de l’application, puis générez et exécutez l’application.

dotnet build

dotnet run

La sortie de l’application ressemble à l’exemple suivant :

Azure Queue Storage client library - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

Quand l’application s’interrompt avant de recevoir des messages, vérifiez votre compte de stockage dans le portail Azure. Vérifiez que les messages se trouvent dans la file d’attente.

Appuyez sur la touche Enter pour recevoir et supprimer les messages. Quand vous y êtes invité, réappuyez sur la touche Enter pour supprimer la file d’attente et terminer la démonstration.

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez appris à créer une file d’attente et à y ajouter des messages à l’aide de code .NET asynchrone. Ensuite, vous avez appris à afficher un aperçu des messages, à les récupérer et à les supprimer. Enfin, vous avez appris à supprimer une file d’attente de messages.

Pour obtenir des tutoriels, des exemples, des guides de démarrage rapide et autres documentations, visitez :

• 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.
• Pour plus d’informations, consultez les bibliothèques Stockage Azure pour .NET.
• Pour d’autres exemples d’applications Stockage File d’attente Azure, consultez Exemples de bibliothèques de client Stockage File d’attente Azure pour .NET.
• Pour en savoir plus sur .NET Core, consultez Prise en main de .NET en 10 minutes.