Azure Storage Queues client library for .NET

Server Version: 2019-02-02

Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

Source code | Package (NuGet) | API reference documentation | REST API documentation | Product documentation

Getting started

Install the package

Install the Azure Storage Queues client library for .NET with NuGet:

dotnet add package Azure.Storage.Queues --version 12.0.0-preview.4

Prerequisites

You need an Azure subscription and a Storage Account to use this package.

To create a new Storage Account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Key concepts

Common uses of Queue storage include:

  • Creating a backlog of work to process asynchronously
  • Passing messages between different parts of a distributed application

Examples

Enqueue messages

using Azure.Storage;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;

// Get a connection string to our Azure Storage account.  You can
// obtain your connection string from the Azure Portal (click
// Access Keys under Settings in the Portal Storage account blade)
// or using the Azure CLI with:
//
//     az storage account show-connection-string --name <account_name> --resource-group <resource_group>
//
// And you can provide the connection string to your application
// using an environment variable.
string connectionString = "<connection_string>";

// Get a reference to a queue named "sample-queue" and then create it
QueueClient queue = new QueueClient(connectionString, "sample-queue");
queue.Create();

// Add a message to our queue
queue.EnqueueMessage("Hello, Azure!");

Dequeue messages

// Get a connection string to our Azure Storage account.
string connectionString = "<connection_string>";

// Get a reference to a queue named "sample-queue" and then create it
QueueClient queue = new QueueClient(connectionString, "sample-queue");
queue.Create();

// Add several messages to the queue
queue.EnqueueMessage("first");
queue.EnqueueMessage("second");
queue.EnqueueMessage("third");

// Get the next 10 messages from the queue
foreach (DequeuedMessage message in queue.DequeueMessages(maxMessages: 10).Value)
{
    // "Process" the message
    Console.WriteLine(message.MessageText)

    // Let the service know we finished with the message and
    // it can be safely deleted.
    queue.DeleteMessage(message.MessageId, message.PopReceipt);
}

Async APIs

We fully support both synchronous and asynchronous APIs.

// Get a connection string to our Azure Storage account.
string connectionString = "<connection_string>";

// Get a reference to a queue named "sample-queue" and then create it
QueueClient queue = new QueueClient(connectionString, "sample-queue");
await queue.CreateAsync();

// Add a message to our queue
await queue.EnqueueMessageAsync("Hello, Azure!");

Authenticating with Azure.Identity

The Azure Identity library provides easy Azure Active Directory support for authentication.

using Azure.Identity;

// Create a QueueClient that will authenticate through Active Directory
Uri accountUri = new Uri("https://MYSTORAGEACCOUNT.blob.core.windows.net/");
QueueClient queue = new QueueClient(accountUri, new DefaultAzureCredential());

Learn more about enabling Azure Active Directory for authentication with Azure Storage in our documentation and our samples.

Troubleshooting

All Azure Storage Queue service operations will throw a RequestFailedException on failure with helpful ErrorCodes. Many of these errors are recoverable.

// Get a connection string to our Azure Storage account
string connectionString = "<connection_string>";

// Try to create a queue named "sample-queue" and avoid any potential race
// conditions that might arise by checking if the queue exists before creating
QueueClient queue = new QueueClient(connectionString, "sample-queue");
try
{
    queue.Create();
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == QueueErrorCode.QueueAlreadyExists)
{
    // Ignore any errors if the queue already exists
}

Next steps

Get started with our Queue samples:

  1. Hello World: Enqueue, Dequeue, Peek, and Update queue messages (or asynchronously)
  2. Auth: Authenticate with connection strings, shared keys, shared access signatures, and Azure Active Directory.

Contributing

See the Storage CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions