快速入门:适用于 .NET 的 Azure 队列存储客户端库 v12

适用于 .NET 的 Azure 队列存储客户端库版本 12 入门。 Azure 队列存储是一项可存储大量消息供以后检索和处理的服务。 请按照以下步骤安装包并试用基本任务的示例代码。

使用适用于 .NET 的 Azure 队列存储客户端库 v12 完成以下操作:

  • 创建队列
  • 向队列添加消息
  • 查看队列中的消息
  • 更新队列中的消息
  • 从队列接收消息
  • 从队列中删除消息
  • 删除队列

其他资源:

先决条件

设置

本部分逐步指导如何准备一个项目,使其与适用于 .NET 的 Azure 队列存储客户端库 v12 配合使用。

创建项目

创建名为 QueuesQuickstartV12 的 .NET Core 应用程序。

  1. 在控制台窗口(例如 cmd、PowerShell 或 Bash)中,使用 dotnet new 命令创建名为 QueuesQuickstartV12 的新控制台应用。 此命令将创建简单的“hello world”C# 项目,其中包含一个名为 Program.cs 的源文件。

    dotnet new console -n QueuesQuickstartV12
    
  2. 切换到新创建的 QueuesQuickstartV12 目录。

    cd QueuesQuickstartV12
    

安装包

同样在应用程序目录中,使用 dotnet add package 命令安装适用于 .NET 包的 Azure 队列存储客户端库。

dotnet add package Azure.Storage.Queues

设置应用框架

从项目目录中执行以下操作:

  1. 在编辑器中打开 Program.cs 文件
  2. 删除 Console.WriteLine("Hello, World"); 语句
  3. 添加 using 指令
  4. 更新 Main 方法声明以支持异步代码

代码如下:

using Azure;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

namespace QueuesQuickstartV12
{
    class Program
    {
        static async Task Main(string[] args)
        {
        }
    }
}

从 Azure 门户复制凭据

当示例应用程序向 Azure 存储发出请求时,必须对其进行授权。 若要对请求进行授权,请将存储帐户凭据以连接字符串形式添加到应用程序中。 按照以下步骤查看存储帐户凭据:

  1. 登录 Azure 门户

  2. 找到自己的存储帐户。

  3. 在存储帐户概述的“设置”部分,选择“访问密钥”。 在这里,可以查看你的帐户访问密钥以及每个密钥的完整连接字符串。

  4. 找到“密钥 1”下面的“连接字符串”值,选择“复制”按钮复制该连接字符串。 下一步需将此连接字符串值添加到某个环境变量。

    显示如何从 Azure 门户复制连接字符串的屏幕截图

配置存储连接字符串

复制连接字符串以后,请将其写入运行应用程序的本地计算机的新环境变量中。 若要设置环境变量,请打开控制台窗口,并遵照适用于操作系统的说明。 将 <yourconnectionstring> 替换为实际的连接字符串。

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中添加环境变量后,必须启动命令窗口的新实例。

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

重新启动程序

添加环境变量后,重启需要读取环境变量的任何正在运行的程序。 例如,重启开发环境或编辑器,然后再继续。

对象模型

Azure 队列存储是一项可存储大量消息的服务。 队列消息大小最大可为 64 KB。 一个队列可以包含数百万条消息,直至达到存储帐户的总容量限值。 队列通常用于创建要异步处理的积压工作 (backlog)。 队列存储提供了三种类型的资源:

  • 存储帐户
  • 存储帐户中的队列
  • 队列中的消息

以下图示显示了这些资源之间的关系。

队列存储体系结构的图示

使用以下 .NET 类与这些资源进行交互:

代码示例

这些示例代码片段演示如何使用适用于 .NET 的 Azure 队列存储客户端库执行以下操作:

获取连接字符串

以下代码检索存储帐户的连接字符串。 连接字符串存储在配置存储连接字符串部分创建的环境变量中。

Main 方法内添加此代码:

Console.WriteLine("Azure Queue Storage client library v12 - .NET quickstart sample\n");

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

创建队列

确定新队列的名称。 以下代码将 GUID 值追加到队列名称,确保其独一无二。

重要

队列名称只能包含小写字母、数字和连字符,并且必须以字母或数字开头。 每个连字符的前后必须为非连字符字符。 名称的长度还必须介于 3 到 63 个字符之间。 有关详细信息,请参阅命名队列和元数据

创建 QueueClient 类的实例。 然后,通过调用 CreateAsync 方法,在存储帐户中创建队列。

将此代码添加到 Main 方法的末尾:

// Create a unique name for the queue
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();

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

// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClient(connectionString, queueName);

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

向队列添加消息

以下代码片段通过调用 SendMessageAsync 方法,以异步方式将消息添加到队列。 它还保存从 SendMessageAsync 调用返回的 SendReceipt。 收据用于在稍后的程序中更新消息。

将此代码添加到 Main 方法的末尾:

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 方法,查看队列中的消息。 此方法从队列前面检索一条或多条消息,但不更改消息的可见性。

将此代码添加到 Main 方法的末尾:

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 方法来更新消息的内容。 此方法可以更改消息的可见性超时和内容。 消息内容必须是最大为 64 KB 的 UTF-8 编码字符串。 除了该消息的新内容,还会传入代码中之前保存的 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");

从队列接收消息

通过调用 ReceiveMessagesAsync 方法,下载以前添加的消息。

将此代码添加到 Main 方法的末尾:

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

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

删除队列中的消息

在处理完消息后,将消息从队列中删除。 在这种情况下,处理只是在控制台上显示消息。

在处理和删除消息之前,应用会调用 Console.ReadLine 以暂停并等待用户输入。 在删除资源之前,请先在 Azure 门户中验证资源已正确创建。 未显式删除的任何消息都将在队列中再次变为可见,以方便再一次进行处理。

将此代码添加到 Main 方法的末尾:

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 方法来删除队列,以便清除该应用所创建的资源。

将此代码添加到 Main 方法的末尾:

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 v12 - .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 代码创建队列并向其添加消息。 然后,你了解如何查看、检索和删除消息。 最后,你还了解了如何删除消息队列。

有关教程、示例、快速入门和其他文档,请访问: