Tutorial: Work with Azure Queue Storage queues in .NET

Article
04/27/2023

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 free 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 free Azure account in the prerequisites.

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 get your credentials from the Azure portal.

Copy your credentials from the Azure portal

When the sample application makes a request to Azure Storage, it must be authorized. To authorize a request, add your storage account credentials to the application as a connection string. To view your storage account credentials, follow these steps:

Sign in to the Azure portal.
Locate your storage account.
In the storage account menu pane, under Security + networking, select Access keys. Here, you can view the account access keys and the complete connection string for each key.
In the Access keys pane, select Show keys.
In the key1 section, locate the Connection string value. Select the Copy to clipboard icon to copy the connection string. You'll add the connection string value to an environment variable in the next section.

Configure your storage connection string

After you copy the connection string, write it to a new environment variable on the local machine running the application. To set the environment variable, open a console window, and follow the instructions for your operating system. Replace <yourconnectionstring> with your actual connection string.

Windows
Linux and macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

After you add the environment variable in Windows, you must start a new instance of the command window.

Restart programs

After you add the environment variable, restart any running programs that will need to read the environment variable. For example, restart your development environment or editor before you continue.

Add the connection string to the app

Add the connection string into the app so it can access the storage account.

Switch back to Visual Studio Code.
In the Main method, replace the Console.WriteLine("Hello, World"); code with the following line that gets the connection string from the environment variable.
```
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
```
Add the following code to Main to create a queue object, which is later passed into the send and receive methods.
```
QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
```
Save the file.

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].Body.ToString();
            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].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.";
    }
}

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.

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

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;

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

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.