快速入門：適用於 .NET 的 Azure 佇列儲存體用戶端程式庫

發行項
03/25/2024

開始使用適用於 .NET 的 Azure 佇列儲存體用戶端程式庫。 Azure 佇列儲存體是用來儲存大量訊息的服務，以便日後擷取和處理。請遵循下列步驟來安裝套件，並試用基本工作的程式碼範例。

API 參考文件 | 程式庫來源程式碼 | 套件 (NuGet) | 範例

使用適用於 .NET 的 Azure 佇列儲存體用戶端程式庫：

建立佇列
將訊息新增至佇列
窺視佇列中的訊息
更新佇列中的訊息
取得佇列長度
從佇列接收訊息
刪除佇列中的訊息
刪除佇列

必要條件

Azure 訂用帳戶 - 建立免費帳戶
Azure 儲存體帳戶 - 建立儲存體帳戶
您作業系統目前的 .NET SDK。請務必取得 SDK，而不是執行階段。

設定

本節會引導您準備專案以搭配適用於 .NET 的 Azure 佇列儲存體用戶端程式庫使用。

建立專案

建立名為 QueuesQuickstart 的 .NET 應用程式。

在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 QueuesQuickstart 的新主控台應用程式。此命令會建立簡單的 "Hello World" C# 專案，內含名稱為 program.cs 的單一原始程式檔。
```
dotnet new console -n QueuesQuickstart
```
切換至新建立的 QueuesQuickstart 目錄。
```
cd QueuesQuickstart
```

安裝套件

若您仍在應用程式目錄中，請使用 dotnet add package 命令安裝適用於 .NET 套件的 Azure 佇列儲存體用戶端程式庫。

dotnet add package Azure.Storage.Queues

需要 Azure 身分識別用戶端程式庫套件才能對 Azure 服務進行無密碼連線。

dotnet add package Azure.Identity

設定應用程式架構

在您選擇的編輯器中開啟專案
開啟 Program.cs 檔案
更新現有的程式碼以符合下列專案：

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 服務的應用程式要求都必須獲得授權。在程式碼中實作對 Azure 服務的無密碼連線時，建議使用 Azure 身分識別用戶端程式庫提供的 DefaultAzureCredential 類別。

您也可以直接使用密碼、連接字串或其他認證來授權對 Azure 服務的要求。不過，應該謹慎使用此方法。開發人員必須盡可能避免在不安全的地方公開祕密。能夠取得密碼或祕密金鑰存取的任何人都可以進行驗證。 DefaultAzureCredential 提供優於帳戶金鑰的管理和安全性優點，允許無密碼驗證。下列範例示範這兩個選項。

無密碼 (建議)
連接字串

DefaultAzureCredential 是適用於 .NET 的 Azure 身分識別用戶端程式庫所提供的類別。如需深入了解 DefaultAzureCredential，請參閱 DefaultAzureCredential 概觀。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應該使用哪個方法。此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。

例如，您的應用程式可以在本機開發時使用 Visual Studio Code 登入認證進行驗證，然後在部署至 Azure 之後，使用受控識別。此轉移不需要變更程式碼。

在本機開發時，請確定存取佇列資料的使用者帳戶具有正確的權限。您需要儲存體佇列資料參與者角色，才能讀取和寫入佇列資料。若要指派此角色給您自己，您需要被指派使用者存取管理員角色，或另一個包含 Microsoft.Authorization/roleAssignments/write 動作的角色。您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell，將 Azure RBAC 角色指派給使用者。您可以在範圍概觀頁面上深入了解角色指派的可用範圍。

在此案例中，您會將權限指派給使用者帳戶 (以儲存體帳戶為範圍)，以遵循最低權限原則。此做法只為使用者提供所需的最低權限，並建立更安全的實際執行環境。

下列範例將儲存體佇列資料參與者角色指派給使用者帳戶，為儲存體帳戶中的佇列資料提供讀取和寫入存取權。

重要

在大部分情況下，角色指派在 Azure 中傳播只需要一兩分鐘，但在罕見情況下，可能需要長達八分鐘。如果您第一次執行程式碼時收到驗證錯誤，請稍候片刻再試一次。

在 Azure 入口網站中，使用主要搜尋列或左側導覽找出您的儲存體帳戶。
在儲存體帳戶概觀頁面上，從左側功能表中選取 [存取控制 (IAM)]。
在 [存取控制 (IAM)] 頁面上，選取 [角色指派] 索引標籤。
從頂端功能表選取 [+ 新增]，然後從產生的下拉功能表中選取 [新增角色指派]。

顯示如何指派角色的螢幕快照。

使用搜尋方塊，從結果篩選出所需的角色。在此範例中，搜尋儲存體佇列資料參與者，接著選取相符的結果，然後選擇下一步。
在 [存取權指派對象為] 下，選取 [使用者、群組或服務主體]，然後選擇 [+ 選取成員]。
在對話方塊中，搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址)，然後在對話方塊底部選擇 [選取]。
選取 [檢閱 + 指派] 以移至最終頁面，然後再次選取 [檢閱 + 指派] 以完成此程序。

若要使用 Azure CLI 在資源層級指派角色，您必須先使用 az storage account show 命令擷取資源識別碼。您可以使用 --query 參數來篩選輸出屬性。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

複製上述命令的輸出 Id。接著，您可以使用 Azure CLI 的 az role 命令來指派角色。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

若要使用 Azure PowerShell 在資源層級指派角色，您必須先使用 Get-AzResource 命令擷取資源識別碼。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

複製上述命令輸出的 Id 值。接著，您可以在 PowerShell 中使用 New-AzRoleAssignment 命令來指派角色。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

從 Azure 入口網站複製您的認證

當應用程式範例向 Azure 儲存體發出要求時，該要求必須獲得授權。若要對要求授權，請以連接字串的形式將儲存體帳戶認證新增至應用程式。若要檢視您的儲存體帳戶認證，請遵循下列步驟：

登入 Azure 入口網站。
找出您的儲存體帳戶。
在 [儲存體帳戶] 功能表窗格的 [安全性 + 網路] 下方，選取 [存取金鑰]。在此處，您可以檢視帳戶存取金鑰，和每個金鑰的完整連接字串。
在 [存取金鑰] 窗格中，選取 [顯示金鑰]。
在 [金鑰 1] 區段中，找出連接字串值。選取 [複製到剪貼簿] 圖示以複製連接字串。在下一小節中，您會將該連接字串值新增至環境變數。

設定儲存體連接字串

在複製連接字串後，請在執行應用程式的本機電腦上，將該字串寫入至新的環境變數中。若要設定環境變數，請開啟主控台視窗，並遵循您的作業系統所適用的指示。將 <yourconnectionstring> 用實際的連接字串取代。

Windows
Linux 和 macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

在 Windows 中新增環境變數之後，您必須啟動新的命令視窗執行個體。

重新啟動程式

新增環境變數之後，請重新啟動任何需要讀取環境變數的執行中程式。例如，請先重新啟動您的開發環境或編輯器，然後再繼續。

重要

應該謹慎使用帳戶存取金鑰。如果帳戶存取金鑰遺失或意外放在不安全的地方，您的服務可能變得易受攻擊。任何擁有存取金鑰的人都可以授權執行目標為儲存體帳戶的要求，而且可實質存取所有資料。 DefaultAzureCredential 會提供增強的安全性功能和權益，建議用來管理對 Azure 服務的授權。

物件模型

Azure 佇列儲存體是用來儲存大量訊息的服務。一則佇列訊息的大小可能高達 64 KB。一則佇列可包含數百則訊息，最高為儲存體帳戶的容量總計限制。佇列通常用來建立工作待辦項目，以非同步處理。佇列儲存體提供三種類型資源：

儲存體帳戶：已透過儲存體帳戶完成所有 Azure 儲存體的存取。如需儲存體帳戶的詳細資訊，請參閱儲存體帳戶概觀
佇列：佇列包含一組訊息。所有訊息都必須在佇列中。請注意，佇列名稱必須全部小寫。如需為佇列命名的詳細資訊，請參閱為佇列和中繼資料命名。
訊息：大小上限為 64 KB 的訊息 (任何格式)。訊息可保留在佇列中的時間上限為 7 天。在 2017-07-29 版或更新版本中，存留時間上限可以是任何正數或 -1 (表示訊息不會過期)。如果省略此參數，則預設存留時間為七天。

下圖顯示資源之間的關係。

佇列記憶體架構的圖表

使用下列 .NET 類別與這些資源互動：

QueueServiceClient：QueueServiceClient可讓您管理儲存體帳戶中的所有佇列。
QueueClient：QueueClient類別可讓您管理和操作個別佇列及其訊息。
QueueMessage：QueueMessage類別代表在佇列上呼叫ReceiveMessages時所傳回的個別物件。

程式碼範例

這些範例程式碼片段會示範如何使用適用於 .NET 的 Azure 佇列儲存體用戶端程式庫執行下列動作：

授權存取並建立用戶端物件
建立佇列
將訊息新增至佇列
窺視佇列中的訊息
更新佇列中的訊息
取得佇列長度
從佇列接收訊息
刪除佇列中的訊息
刪除佇列

無密碼 (建議)
連接字串

授權存取並建立用戶端物件

若為本機開發，請確定使用您指派角色的相同 Microsoft Entra 帳戶進行驗證。您可以透過 Azure CLI 或 Azure PowerShell 這類熱門開發工具來進行驗證。您可以用來驗證的開發工具會因語言而異。

使用下列命令透過 Azure CLI 登入 Azure：

az login

必須安裝 Azure CLI，才能透過 Visual Studio Code 使用 DefaultAzureCredential。

在 Visual Studio Code 的主功能表上，瀏覽至 [終端機] > [新增終端機]。

使用下列命令透過 Azure CLI 登入 Azure：

az login

使用 PowerShell 透過下列命令登入 Azure：

Connect-AzAccount

驗證之後，即可使用 DefaultAzureCredential 來建立和授權 QueueClient 物件，以存取記憶體帳戶中的佇列資料。 DefaultAzureCredential 會自動探索並使用您在上一個步驟中用來登入的帳戶。

若要使用 DefaultAzureCredential 授權，請確定您已新增 Azure 身分識別套件，如安裝套件中所述。此外，請務必在 Program.cs 檔案中新增 Azure.Identity 命名空間的 using 指示詞：

using Azure.Identity;

接下來，決定佇列的名稱，並使用 DefaultAzureCredential 進行授權，建立 QueueClient 類別的執行個體。我們會使用此用戶端物件來建立並與儲存體帳戶中的佇列資源互動。

重要

佇列名稱只能包含小寫字母、數字和連字號，且必須以字母或數字開頭。每個連字號前後都必須緊接非連字號的字元。名稱長度也必須為 3 到 63 個字元。如需詳細資訊，請參閱為佇列和中繼資料命名。

將下列程式代碼新增至 Program.cs 檔案的結尾。請務必取代 <storage-account-name> 預留位置值：

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

取得連接字串和建立用戶端

以下程式碼會擷取儲存體帳戶的連接字串。連接字串會儲存在設定儲存體連接字串一節中建立的環境變數。

將此程式碼新增至 Program.cs 檔案的結尾：

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

決定佇列的名稱，並使用連接字串進行授權，建立 QueueClient 類別的執行個體。我們會使用此用戶端物件來建立並與儲存體帳戶中的佇列資源互動。

重要

將此程式碼新增至 Program.cs 檔案的結尾：

// 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 類別傳送的訊息，必須採用可以包含在以 UTF-8 編碼的 XML 要求中的格式。您可以選擇性地將 MessageEncoding 選項設定為 Base64 來處理不符合規範的訊息。

建立佇列

使用 QueueClient 物件，呼叫 CreateAsync 方法以在儲存體帳戶中建立佇列。

將此程式碼新增至 Program.cs 方法的結尾：

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

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

將訊息新增至佇列

下列程式碼片段會藉由呼叫 SendMessageAsync 方法，以非同步方式將訊息新增至佇列。其也會儲存從 SendMessageAsync 呼叫傳回的 SendReceipt。回條可用來在稍後的程式中更新訊息。

將此程式碼新增至 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 方法來更新訊息的內容。此方法可以變更訊息的可見度逾時和內容。訊息內容必須是大小上限為 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");

取得佇列長度

您可估計佇列中的訊息數目。 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 程式碼建立佇列，並將訊息新增至其中。然後您會了解如何窺視、擷取和刪除訊息。最後，您會了解如何刪除訊息佇列。

如需教學課程、範例、快速入門及其他文件，請瀏覽：

適用於 .NET 和 .NET Core 開發人員的 Azure

如需使用已淘汰 .NET 11.x 版 SDK 的相關程式碼範例，請參閱使用 .NET 11.x 版的程式碼範例。
若要深入了解，請參閱適用於 .NET 的 Azure 儲存體程式庫。
如需更多 Azure 佇列儲存體範例應用程式，請參閱適用於 .NET 的 Azure 佇列儲存體用戶端程式庫範例。
若要深入了解 .NET Core，請參閱在 10 分鐘內開始使用 .NET。

共用方式為

快速入門：適用於 .NET 的 Azure 佇列儲存體用戶端程式庫

必要條件

設定

建立專案

安裝套件

設定應用程式架構

向 Azure 驗證

從 Azure 入口網站複製您的認證

設定儲存體連接字串

重新啟動程式

物件模型

程式碼範例

授權存取並建立用戶端物件

取得連接字串和建立用戶端

建立佇列

將訊息新增至佇列

窺視佇列中的訊息

更新佇列中的訊息

取得佇列長度

從佇列接收訊息

刪除佇列中的訊息

刪除佇列

執行程式碼

下一步

意見反應

其他資源