Tutorial: Work with Azure Queue Storage queues in .NET

Article
09/06/2024

Azure Queue Storage implements cloud-based queues to enable communication between components of a distributed application. Each queue maintains a list of messages that can be added by a sender component and processed by a receiver component. With a queue, your application can scale immediately to meet demand. This article shows the basic steps for working with an Azure Queue Storage queue.

In this tutorial, you learn how to:

Create an Azure Storage account
Create the app
Add the Azure client libraries
Add support for asynchronous code
Create a queue
Insert messages into a queue
Dequeue messages
Delete an empty queue
Check for command-line arguments
Build and run the app

Prerequisites

Get your free copy of the cross platform Visual Studio Code editor.
Download and install the .NET Core SDK version 3.1 or later.
If you don't have a current Azure subscription, create a trial account before you begin.

Create an Azure Storage account

First, create an Azure Storage account.

For a step-by-step guide to creating a storage account, see Create a storage account. This is a separate step you perform after creating a trial Azure account in the prerequisites.
Make sure that your user account has been assigned the Storage Queue Data Contributor role, scoped to the storage account, parent resource group, or subscription. See Authenticate to Azure.

Create the app

Create a .NET Core application named QueueApp. For simplicity, this app will both send and receive messages through the queue.

In a console window (such as cmd, PowerShell, or Azure CLI), use the dotnet new command to create a new console app with the name QueueApp. This command creates a simple "hello world" C# project with a single source file named Program.cs.
```
dotnet new console -n QueueApp
```

Switch to the newly created QueueApp folder and build the app to verify that all is well.

cd QueueApp

dotnet build

You should see results similar to the following output:

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

Add the Azure client libraries

Add the Azure Storage client libraries to the project by using the dotnet add package command.

Run the following command from the project folder in the console window.
```
dotnet add package Azure.Storage.Queues
```

Add using statements

From the command line in the project directory, type code . to open Visual Studio Code in the current directory. Keep the command-line window open. There will be more commands to run later. If you're prompted to add C# assets required to build and debug, click the Yes button.
Open the Program.cs source file and add the following namespaces right after the using System; statement. This app uses types from these namespaces to connect to Azure Storage and work with queues.
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
Save the Program.cs file.

Add support for asynchronous code

Since the app uses cloud resources, the code runs asynchronously.

Update the Main method to run asynchronously. Replace void with an async Task return value.
```
static async Task Main(string[] args)
```
Save the Program.cs file.

Create a queue

Before making any calls into Azure APIs, you must make sure you're authenticated with the same Microsoft Entra account you assigned the role to. Once authenticated, you can create and authorize a QueueClient object by using DefaultAzureCredential to access queue data in the storage account. DefaultAzureCredential automatically discovers and uses the account you signed into. To learn how to sign in and then create a QueueClient object, see Authorize access and create a client object.

Insert messages into the queue

Create a new method to send a message into the queue.

Add the following InsertMessageAsync method to your Program class.

This method is passed a queue reference. A new queue is created, if it doesn't already exist, by calling CreateIfNotExistsAsync. Then, it adds the newMessage to the queue by calling SendMessageAsync.

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

    await theQueue.SendMessageAsync(newMessage);
 }

Optional: By default, the maximum time-to-live for a message is set to seven days. You can specify any positive number for the message time-to-live. The following code snippet adds a message that never expires.

To add a message that doesn't expire, use Timespan.FromSeconds(-1) in your call to SendMessageAsync.
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
Save the file.

A queue message must be in a format compatible with an XML request using UTF-8 encoding. A message may be up to 64 KB in size. If a message contains binary data, Base64-encode the message.

Dequeue messages

Create a new method to retrieve a message from the queue. Once the message is successfully received, it's important to delete it from the queue so it isn't processed more than once.

Add a new method called RetrieveNextMessageAsync to your Program class.

This method receives a message from the queue by calling ReceiveMessagesAsync, passing 1 in the first parameter to retrieve only the next message in the queue. After the message is received, delete it from the queue by calling DeleteMessageAsync.

When a message is sent to the queue with a version of the SDK prior to v12, it is automatically Base64-encoded. Starting with v12, that functionality was removed. When you retrieve a message by using the v12 SDK, it is not automatically Base64-decoded. You must explicitly Base64-decode the contents yourself.
```
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].MessageText;
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }

        return null;
    }

    return null;
}
```
Save the file.

Delete an empty queue

It's a best practice at the end of a project to identify whether you still need the resources you created. Resources left running can cost you money. If the queue exists but is empty, ask the user if they would like to delete it.

Expand the RetrieveNextMessageAsync method to include a prompt to delete the empty queue.

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

Save the file.

Check for command-line arguments

If there are any command-line arguments passed into the app, assume they're a message to be added to the queue. Join the arguments together to make a string. Add this string to the message queue by calling the InsertMessageAsync method we added earlier.

If there are no command-line arguments, attempt a retrieve operation. Call the RetrieveNextMessageAsync method to retrieve the next message in the queue.

Finally, wait for user input before exiting by calling Console.ReadLine.

Expand the Main method to check for command-line arguments and wait for user input. In the code snippet below, make sure to replace the {storageAccountName} placeholder with the name of your storage account.

static async Task Main(string[] args)
{
   QueueClient queue = new QueueClient(
      new Uri($"https://{storageAccountName}.queue.core.chinacloudapi.cn/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();
}

Save the file.

Complete code

Here is the complete code listing for this project.

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

Build and run the app

From the command line in the project directory, run the following dotnet command to build the project.
```
dotnet build
```

After the project builds successfully, run the following command to add the first message to the queue.

dotnet run First queue message

You should see this output:

C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter..._

Run the app with no command-line arguments to receive and remove the first message in the queue.
```
dotnet run
```

Continue to run the app until all the messages are removed. If you run it one more time, you'll get a message that the queue is empty and a prompt to delete the queue.

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

Next steps

In this tutorial, you learned how to:

Create a queue
Add and remove messages from a queue
Delete an Azure Queue Storage queue

Check out the Azure Queue Storage quickstarts for more information.

Queues quickstart for the portal

For related code samples using deprecated .NET version 11.x SDKs, see Code samples using .NET version 11.x.