Краткое руководство. Клиентская библиотека хранилища очередей Azure для .NET

Начало работы с клиентской библиотекой хранилища очередей Azure для .NET. Хранилище очередей Azure — это служба хранения большого количества сообщений для последующего извлечения и обработки. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач.

Справочная документация по API | исходный код библиотеки | пакет (NuGet) | примеры

Использование клиентской библиотеки хранилища очередей Azure для .NET:

• Создать очередь
• Добавление сообщений в очередь
• Просмотр сообщений из очереди
• Обновление сообщений в очереди
• Получение длины очереди
• Получение сообщений из очереди
• Удаление сообщений из очереди
• Удаление очереди

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Текущий пакет SDK для .NET для операционной системы. Обязательно получите пакет SDK, а не среду выполнения.

Установка

В этом разделе описывается подготовка проекта для работы с клиентской библиотекой хранилища очередей Azure для .NET.

Создание проекта

Создание приложения .NET с именем QueuesQuickstart.

1. В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем QueuesQuickstart. Эта команда создает простой проект C# hello world с одним исходным файлом с именем Program.cs.

   dotnet new console -n QueuesQuickstart
   

2. Перейдите в только что созданный каталог QueuesQuickstart.

   cd QueuesQuickstart
   

Установка пакетов

Оставаясь в каталоге приложения, установите пакет клиентской библиотеки Хранилища очередей Azure для .NET с помощью команды dotnet add package.

dotnet add package Azure.Storage.Queues

Пакет клиентской библиотеки удостоверений Azure также необходим для бессерверных подключений к службам Azure.

dotnet add package Azure.Identity

Настройка платформы приложения

1. Открытие проекта в выбранном редакторе
2. Откройте файл Program.cs
3. Обновите существующий код, чтобы он соответствовал следующему:

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

Аутентификация в Azure

Запросы приложений к большинству служб Azure должны быть авторизованы. DefaultAzureCredential Использование класса, предоставленного клиентской библиотекой удостоверений Azure, является рекомендуемым подходом для реализации бессерверных подключений к службам Azure в коде.

Вы также можете авторизовать запросы к службам Azure с помощью паролей, строка подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля. Оба варианта показаны в следующем примере.

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

Объектная модель

Служба Хранилище очередей Azure предназначена для хранения большого количества произвольных сообщений. Максимальный размер сообщения в очереди составляет 64 КБ. Очередь может содержать миллионы сообщений вплоть до лимита всей емкости учетной записи хранения. Очереди обычно используются для создания списка невыполненных заданий для асинхронной обработки. В Хранилище очередей предлагается три типа ресурсов:

• Учетная запись хранения. Доступ к службе хранилища Azure всегда осуществляется с помощью учетной записи хранения. Дополнительные сведения об учетных записях хранения см. в обзоре учетной записи хранения.
• Очередь. Очередь содержит набор сообщений. Все сообщения должны находиться в очереди. Обратите внимание: имя очереди должно содержать только строчные символы. Дополнительные сведения см. в статье о присвоении имен очередям и метаданным.
• Сообщение. Сообщение в любом формате размером до 64 КБ. Сообщение может оставаться в очереди не более 7 дней. Начиная с версии 2017-07-29, максимальный срок жизни может быть задан любым положительным числом или значением -1, свидетельствующим о том, что срок жизни сообщения неограничен. Если этот параметр не указан, срок жизни по умолчанию составляет семь дней.

На следующей схеме показана связь между этими ресурсами.

Используйте следующие классы .NET для взаимодействия с этими ресурсами:

• QueueServiceClient: QueueServiceClient позволяет управлять всеми очередями в учетной записи хранения.
• QueueClient: класс QueueClient позволяет управлять отдельной очередью и сообщениями в ней.
• QueueMessage: класс QueueMessage представляет отдельные объекты, которые возвращаются при вызове ReceiveMessages для очереди.

Примеры кода

В этих примерах фрагментов кода показано, как выполнять следующие действия с помощью клиентской библиотеки Хранилища очередей Azure для .NET:

• Авторизация доступа и создание клиентского объекта
• Создание очереди
• Добавление сообщений в очередь
• Просмотр сообщений из очереди
• Обновление сообщений в очереди
• Получение длины очереди
• Получение сообщений из очереди
• Удаление сообщений из очереди
• Удаление очереди

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

Создать очередь

QueueClient С помощью объекта вызовите CreateAsync метод для создания очереди в учетной записи хранения.

Добавьте этот код в конец метода Program.cs :

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

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

Добавление сообщений в очередь

Приведенный ниже фрагмент кода асинхронно добавляет сообщения в очередь, вызывая метод SendMessageAsync. Он также сохраняет SendReceipt, возвращенный вызовом SendMessageAsync. Это подтверждение используется для обновления сообщения далее в коде программы.

Добавьте этот код в конец файла 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");

Просмотр сообщений из очереди

Чтобы просмотреть сообщения в очереди, вызовите метод PeekMessagesAsync. Этот метод извлекает одно или несколько сообщений из начала очереди, не изменяя видимость этих сообщений.

Добавьте этот код в конец файла 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}");
}

Обновление сообщений в очереди

Чтобы обновить содержимое сообщения, вызовите метод UpdateMessageAsync. Этот метод позволяет изменить время видимости сообщения и его содержимое. Содержимое сообщение должно иметь формат строки в кодировке UTF-8 длиной не более 64 КБ. Вместе с новым содержимым сообщения передайте значения из SendReceipt, сохраненного ранее в коде программы. Значения SendReceipt указывают, какое сообщение следует обновить.

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

Получение длины очереди

Вы можете узнать приблизительное количество сообщений в очереди. Метод GetProperties возвращает свойства очереди, включая число сообщений. Свойство ApproximateMessagesCount указывает приблизительное количество сообщений в очереди. Это число не ниже фактического количества сообщений в очереди, но может быть выше.

Добавьте этот код в конец файла 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}");

Получение сообщений из очереди

Чтобы скачать ранее добавленные сообщения, вызовите метод ReceiveMessagesAsync.

Добавьте этот код в конец файла Program.cs :

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

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

При необходимости можно указать значение, maxMessagesкоторое является числом сообщений, извлекаемых из очереди. Значение по умолчанию — 1 сообщение, а максимальное — 32 сообщения. Можно также указать значение, visibilityTimeoutкоторое скрывает сообщения от других операций за период ожидания. Значение по умолчанию — 30 секунд.

Удаление сообщений из очереди

Удалите сообщения из очереди после их обработки. В нашем примере обработка сводится к выводу сообщения в консоль.

Перед обработкой и удалением сообщений приложение ожидает ввода от пользователя, вызывая метод Console.ReadLine. Перед удалением ресурсов убедитесь на портале Azure, что они были правильно созданы. Все сообщения, которые явно не удалены, в конечном итоге становятся видимыми в очереди еще раз, чтобы еще один шанс обработать их.

Добавьте этот код в конец файла 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);
}

Удаление очереди

Следующий код очищает созданные приложением ресурсы, удаляя очередь с помощью метода DeleteAsync.

Добавьте этот код в конец файла 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");

Выполнение кода

Это приложение создает три сообщения и добавляет их в очередь Azure. Затем код получает список сообщений, извлекает и удаляет их, и наконец удаляет саму очередь.

В окне консоли перейдите к каталогу приложения, выполните его сборку и запустите его.

dotnet build

dotnet run

Вы должны увидеть выходные данные приложения, как показано ниже.

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

Когда приложение приостановится перед получением сообщений, проверьте учетную запись хранения на портале Azure. Убедитесь, что сообщения находятся в очереди.

Нажмите клавишу Enter, чтобы получить и удалить сообщения. При появлении запроса снова нажмите клавишу Enter, чтобы удалить очередь и завершить демонстрацию.

Следующие шаги

Из этого краткого руководства вы узнали, как создавать очередь и добавлять в нее сообщения из асинхронного кода на .NET. Затем вы изучили процессы вставки, просмотра, получения и удаления сообщений. Наконец, вы узнали, как удалить очередь сообщений.

Руководства, примеры, краткие руководства и другую документацию можно найти здесь:

• Дополнительные примеры кода, использующие устаревшие пакеты SDK для .NET версии 11.x, см. в примерах кода с помощью .NET версии 11.x.
• Чтобы узнать больше, ознакомьтесь с библиотеками службы хранилища Azure для .NET.
• Дополнительные примеры приложений для клиентской библиотеки Хранилища очередей Azure для .NET см. здесь.
• Дополнительные сведения о .NET Core см. в статье Get started with .NET in 10 minutes (Быстрое начало работы с .NET).