Edit

Share via

Quickstart: Azure Queue Storage client library for .NET

  • Article

Get started with the Azure Queue Storage client library for .NET. Azure Queue Storage is a service for storing large numbers of messages for later retrieval and processing. Follow these steps to install the package and try out example code for basic tasks.

API reference documentation | Library source code | Package (NuGet) | Samples

Use the Azure Queue Storage client library for .NET to:

  • Create a queue
  • Add messages to a queue
  • Peek at messages in a queue
  • Update a message in a queue
  • Get the queue length
  • Receive messages from a queue
  • Delete messages from a queue
  • Delete a queue

Prerequisites

Setting up

This section walks you through preparing a project to work with the Azure Queue Storage client library for .NET.

Create the project

Create a .NET application named QueuesQuickstart.

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

    dotnet new console -n QueuesQuickstart

  2. Switch to the newly created QueuesQuickstart directory.

    cd QueuesQuickstart

Install the packages

While still in the application directory, install the Azure Queue Storage client library for .NET package by using the dotnet add package command.

dotnet add package Azure.Storage.Queues

The Azure Identity client library package is also needed for passwordless connections to Azure services.

dotnet add package Azure.Identity

Set up the app framework

  1. Open the project in your editor of choice
  2. Open the Program.cs file
  3. Update the existing code to match the following:
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

Authenticate to Azure

Application requests to most Azure services must be authorized. Using the DefaultAzureCredential class provided by the Azure Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code.

You can also authorize requests to Azure services using passwords, connection strings, or other credentials directly. However, this approach should be used with caution. Developers must be diligent to never expose these secrets in an unsecure location. Anyone who gains access to the password or secret key is able to authenticate. DefaultAzureCredential offers improved management and security benefits over the account key to allow passwordless authentication. Both options are demonstrated in the following example.

DefaultAzureCredential is a class provided by the Azure Identity client library for .NET. To learn more about DefaultAzureCredential, see the DefaultAzureCredential overview. DefaultAzureCredential supports multiple authentication methods and determines which method should be used at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.

For example, your app can authenticate using your Visual Studio sign-in credentials when developing locally, and then use a managed identity once it has been deployed to Azure. No code changes are required for this transition.

When developing locally, make sure that the user account that is accessing the queue data has the correct permissions. You'll need Storage Queue Data Contributor to read and write queue data. To assign yourself this role, you'll need to be assigned the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. You can learn more about the available scopes for role assignments on the scope overview page.

In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow the Principle of Least Privilege. This practice gives users only the minimum permissions needed and creates more secure production environments.

The following example will assign the Storage Queue Data Contributor role to your user account, which provides both read and write access to queue data in your storage account.

Important

In most cases it will take a minute or two for the role assignment to propagate in Azure, but in rare cases it may take up to eight minutes. If you receive authentication errors when you first run your code, wait a few moments and try again.

  1. In the Azure portal, locate your storage account using the main search bar or left navigation.

  2. On the storage account overview page, select Access control (IAM) from the left-hand menu.

  3. On the Access control (IAM) page, select the Role assignments tab.

  4. Select + Add from the top menu and then Add role assignment from the resulting drop-down menu.

A screenshot showing how to assign a role.

  1. Use the search box to filter the results to the desired role. For this example, search for Storage Queue Data Contributor and select the matching result and then choose Next.

  2. Under Assign access to, select User, group, or service principal, and then choose + Select members.

  3. In the dialog, search for your Microsoft Entra username (usually your user@domain email address) and then choose Select at the bottom of the dialog.

  4. Select Review + assign to go to the final page, and then Review + assign again to complete the process.

Object model

Azure Queue Storage is a service for storing large numbers of messages. A queue message can be up to 64 KB in size. A queue may contain millions of messages, up to the total capacity limit of a storage account. Queues are commonly used to create a backlog of work to process asynchronously. Queue Storage offers three types of resources:

  • Storage account: All access to Azure Storage is done through a storage account. For more information about storage accounts, see Storage account overview
  • Queue: A queue contains a set of messages. All messages must be in a queue. Note that the queue name must be all lowercase. For information on naming queues, see Naming Queues and Metadata.
  • Message: A message, in any format, of up to 64 KB. A message can remain in the queue for a maximum of 7 days. For version 2017-07-29 or later, the maximum time-to-live can be any positive number, or -1 indicating that the message doesn't expire. If this parameter is omitted, the default time-to-live is seven days.

The following diagram shows the relationship between these resources.

Diagram of Queue storage architecture

Use the following .NET classes to interact with these resources:

  • QueueServiceClient: The QueueServiceClient allows you to manage the all queues in your storage account.
  • QueueClient: The QueueClient class allows you to manage and manipulate an individual queue and its messages.
  • QueueMessage: The QueueMessage class represents the individual objects returned when calling ReceiveMessages on a queue.

Code examples

These example code snippets show you how to perform the following actions with the Azure Queue Storage client library for .NET:

Authorize access and create a client object

For local development, make sure you're authenticated with the same Microsoft Entra account you assigned the role to. You can authenticate via popular development tools, such as the Azure CLI or Azure PowerShell. The development tools with which you can authenticate vary across languages.

Sign-in to Azure through the Azure CLI using the following command:

az login

Once authenticated, you can create and authorize a QueueClient object using DefaultAzureCredential to access queue data in the storage account. DefaultAzureCredential automatically discovers and uses the account you signed in with in the previous step.

To authorize using DefaultAzureCredential, make sure you've added the Azure.Identity package, as described in Install the packages. Also, be sure to add a using directive for the Azure.Identity namespace in the Program.cs file:

using Azure.Identity;

Next, decide on a name for the queue and create an instance of the QueueClient class, using DefaultAzureCredential for authorization. We use this client object to create and interact with the queue resource in the storage account.

Important

Queue names may only contain lowercase letters, numbers, and hyphens, and must begin with a letter or a number. Each hyphen must be preceded and followed by a non-hyphen character. The name must also be between 3 and 63 characters long. For more information, see Naming queues and metadata.

Add the following code to the end of the Program.cs file. Make sure to replace the <storage-account-name> placeholder value:

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

Note

Messages sent using the QueueClient class must be in a format that can be included in an XML request with UTF-8 encoding. You can optionally set the MessageEncoding option to Base64 to handle non-compliant messages.

Create a queue

Using the QueueClient object, call the CreateAsync method to create the queue in your storage account.

Add this code to the end of the Program.cs method:

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

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

Add messages to a queue

The following code snippet asynchronously adds messages to queue by calling the SendMessageAsync method. It also saves a SendReceipt returned from a SendMessageAsync call. The receipt is used to update the message later in the program.

Add this code to the end of the Program.cs file:

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");

Peek at messages in a queue

Peek at the messages in the queue by calling the PeekMessagesAsync method. This method retrieves one or more messages from the front of the queue but doesn't alter the visibility of the message.

Add this code to the end of the Program.cs file:

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

Update a message in a queue

Update the contents of a message by calling the UpdateMessageAsync method. This method can change a message's visibility timeout and contents. The message content must be a UTF-8 encoded string that is up to 64 KB in size. Along with the new content for the message, pass in the values from the SendReceipt that was saved earlier in the code. The SendReceipt values identify which message to update.

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");

Get the queue length

You can get an estimate of the number of messages in a queue. The GetProperties method returns queue properties including the message count. The ApproximateMessagesCount property contains the approximate number of messages in the queue. This number isn't lower than the actual number of messages in the queue, but could be higher.

Add this code to the end of the Program.cs file:

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

Receive messages from a queue

Download previously added messages by calling the ReceiveMessagesAsync method.

Add this code to the end of the Program.cs file:

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

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

You can optionally specify a value for maxMessages, which is the number of messages to retrieve from the queue. The default is 1 message and the maximum is 32 messages. You can also specify a value for visibilityTimeout, which hides the messages from other operations for the timeout period. The default is 30 seconds.

Delete messages from a queue

Delete messages from the queue after they've been processed. In this case, processing is just displaying the message on the console.

The app pauses for user input by calling Console.ReadLine before it processes and deletes the messages. Verify in your Azure portal that the resources were created correctly, before they're deleted. Any messages not explicitly deleted eventually become visible in the queue again for another chance to process them.

Add this code to the end of the Program.cs file:

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

Delete a queue

The following code cleans up the resources the app created by deleting the queue using the DeleteAsync method.

Add this code to the end of the Program.cs file:

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");

Run the code

This app creates and adds three messages to an Azure queue. The code lists the messages in the queue, then retrieves and deletes them, before finally deleting the queue.

In your console window, navigate to your application directory, then build and run the application.

dotnet build

dotnet run

The output of the app is similar to the following example:

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

When the app pauses before receiving messages, check your storage account in the Azure portal. Verify the messages are in the queue.

Press the Enter key to receive and delete the messages. When prompted, press the Enter key again to delete the queue and finish the demo.

Next steps

In this quickstart, you learned how to create a queue and add messages to it using asynchronous .NET code. Then you learned to peek, retrieve, and delete messages. Finally, you learned how to delete a message queue.

For tutorials, samples, quick starts and other documentation, visit:

Azure for .NET and .NET Core developers