教學課程：在 .NET 中使用 Azure 佇列儲存體佇列

發行項
08/08/2024

Azure 佇列儲存體可實作雲端式佇列，使分散式應用程式的元件之間可進行通訊。每個佇列都會維護一份可由傳送端元件新增、且可由接收端元件處理的訊息清單。透過佇列，您的應用程式將可立即進行調整以因應需求。本文說明使用 Azure 佇列儲存體佇列的基本步驟。

在本教學課程中，您會了解如何：

建立 Azure 儲存體帳戶
建立應用程式
新增 Azure 用戶端程式庫
新增非同步程式碼的支援
建立佇列
將訊息插入佇列中
清除佇列中的訊息
刪除空的佇列
檢查命令列引數
建置並執行應用程式

必要條件

取得免費的跨平台 Visual Studio Code 編輯器。
下載並安裝 .NET Core SDK 3.1 版或更新版本。
如果您還沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

建立 Azure 儲存體帳戶

首先，請建立 Azure 儲存體帳戶。

如需建立儲存體帳戶的逐步指南，請參閱建立儲存體帳戶。這是您在必要條件中建立免費的 Azure 帳戶之後所執行的個別步驟。
請確定您的使用者帳戶已獲指派記憶體佇列數據參與者角色，範圍設定為記憶體帳戶、父資源群組或訂用帳戶。請參閱向 Azure 驗證。

建立應用程式

建立名為 QueueApp 的 .NET Core 應用程式。為了方便說明，此應用程式將可透過佇列傳送和接收訊息。

在主控台視窗中 (例如 CMD、PowerShell 或 Azure CLI)，使用 dotnet new 命令建立名為 QueueApp 的新主控台應用程式。此命令會建立簡單的 "hello world" C# 專案，內含名為 Program.cs 的單一來源檔案。
```
dotnet new console -n QueueApp
```

切換至新建立的 QueueApp 資料夾，然後建置應用程式來確認一切正常。

cd QueueApp

dotnet build

您應該會看到類似下面輸出的結果：

C:\Tutorials>dotnet new console -n QueueApp
The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on QueueApp\QueueApp.csproj...
  Restore completed in 155.63 ms for C:\Tutorials\QueueApp\QueueApp.csproj.

Restore succeeded.

C:\Tutorials>cd QueueApp

C:\Tutorials\QueueApp>dotnet build
Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 40.87 ms for C:\Tutorials\QueueApp\QueueApp.csproj.
  QueueApp -> C:\Tutorials\QueueApp\bin\Debug\netcoreapp3.1\QueueApp.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:02.40

C:\Tutorials\QueueApp>_

新增 Azure 用戶端程式庫

使用 dotnet add package 命令，將 Azure 儲存體用戶端程式庫新增至專案。

從主控台視窗中的專案資料夾執行下列命令。
```
dotnet add package Azure.Storage.Queues
```

新增 using 陳述式

從專案目錄中的命令列輸入 code .，以在目前的目錄中開啟 Visual Studio Code。將命令列視窗保持開啟。稍後將會執行更多命令。如果系統提示您新增建置和偵錯所需的 C# 資產，請按一下 [是] 按鈕。
開啟 Program.cs 來源檔案，並緊接在 using System; 陳述式後面新增下列命名空間。此應用程式會使用這些命名空間中的類型連線至 Azure 儲存體，並使用佇列。
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
儲存Program.cs檔案。

新增非同步程式碼的支援

由於應用程式使用雲端資源，因此程式碼會以非同步方式執行。

更新 Main 方法，以非同步方式執行。將 void 取代為 async Task 傳回值。
```
static async Task Main(string[] args)
```
儲存Program.cs檔案。

建立佇列

在對 Azure API 進行任何呼叫之前，您必須確定您已使用您指派角色的相同Microsoft Entra 帳戶進行驗證。驗證之後，您可以使用來存取記憶體帳戶中的佇列數據，來建立和授權 QueueClient 物件 DefaultAzureCredential 。 DefaultAzureCredential 會自動探索並使用您登入的帳戶。若要瞭解如何登入，然後建立 QueueClient 物件，請參閱授權存取權及建立客戶端物件。

將訊息插入佇列中

建立將訊息傳送至佇列中的新方法。

將下列 InsertMessageAsync 方法新增至您的 Program 類別。

已傳遞佇列參考給這個方法。藉由呼叫 CreateIfNotExistsAsync，建立新的佇列 (如果尚未存在)。然後該佇列會呼叫 SendMessageAsync，將 newMessage 新增至佇列。
```
static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
{
    if (null != await theQueue.CreateIfNotExistsAsync())
    {
        Console.WriteLine("The queue was created.");
    }

    await theQueue.SendMessageAsync(newMessage);
}
```
選擇性： 根據預設，訊息的存留時間上限會設為 7 天。您可以指定任何正數的訊息存留時間。下列程式碼片段會新增「永不」過期的訊息。

若要新增不會過期的訊息，請在 SendMessageAsync 的呼叫中使用 Timespan.FromSeconds(-1)。
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
儲存檔案。

佇列訊息的格式必須與使用 UTF-8 編碼的 XML 要求相容。一則訊息的大小可能高達 64 KB。如果訊息包含二進位資料，則將訊息編碼為 Base64。

清除佇列中的訊息

建立新方法已從佇列中擷取訊息。在成功接收訊息後，務必要從佇列中刪除該訊息，以免受到多次處理。

將稱為 RetrieveNextMessageAsync 的新方法新增至您的 Program 類別。

此方法會藉由呼叫 ReceiveMessagesAsync，在第一個參數中傳遞 1 僅擷取佇列中的下一則訊息，以接收佇列中的訊息。收到訊息後，請呼叫 DeleteMessageAsync 以從佇列中刪除該訊息。

當使用 v12 之前的 SDK 版本將訊息傳送至佇列時，會自動以 Base64 編碼。從 v12 開始，已移除該功能。使用 v12 SDK 來擷取訊息時，不會自動進行 Base64 解碼。您必須自行明確地對內容進行 Base64 解碼。

static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
{
    if (await theQueue.ExistsAsync())
    {
        QueueProperties properties = await theQueue.GetPropertiesAsync();

        if (properties.ApproximateMessagesCount > 0)
        {
            QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
            string theMessage = retrievedMessage[0].Body.ToString();
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }

        return null;
    }

    return null;
}

儲存檔案。

刪除空的佇列

在專案結束後確認您是否還需要您建立的資源，是最佳做法。資源若繼續執行，將需付費。如果佇列存在，但是空的，請詢問使用者是否要加以刪除。

展開 RetrieveNextMessageAsync 方法，以納入刪除空佇列的提示。

static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
{
    if (await theQueue.ExistsAsync())
    {
        QueueProperties properties = await theQueue.GetPropertiesAsync();

        if (properties.ApproximateMessagesCount > 0)
        {
            QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
            string theMessage = retrievedMessage[0].Body.ToString();
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }
        else
        {
            Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
            string response = Console.ReadLine();

            if (response.ToUpper() == "Y")
            {
                await theQueue.DeleteIfExistsAsync();
                return "The queue was deleted.";
            }
            else
            {
                return "The queue was not deleted.";
            }
        }
    }
    else
    {
        return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
    }
}

儲存檔案。

檢查命令列引數

如果在應用程式中傳入了任何命令列引數，請假設它們是要新增至佇列的訊息。引數聯結在一起，組成字串。藉由呼叫我們先前新增的 InsertMessageAsync 方法，將此字串新增至訊息佇列。

如果沒有任何命令列引數，請嘗試擷取作業。呼叫 RetrieveNextMessageAsync 方以擷取佇列中的下一則訊息。

最後，等到使用者輸入後，再呼叫 Console.ReadLine 結束。

展開 Main 方法以檢查命令列引數，並等候使用者輸入。在下列代碼段中，請務必將 {storageAccountName} 佔位元取代為您的記憶體帳戶名稱。

static async Task Main(string[] args)
{
   QueueClient queue = new QueueClient(
      new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
      new DefaultAzureCredential());

   if (args.Length > 0)
   {
      string value = String.Join(" ", args);
      await InsertMessageAsync(queue, value);
      Console.WriteLine($"Sent: {value}");
   }
   else
   {
      string value = await RetrieveNextMessageAsync(queue);
      Console.WriteLine($"Received: {value}");
   }

   Console.Write("Press Enter...");
   Console.ReadLine();
}

儲存檔案。

完整程式碼

以下列出此專案的完整程式碼。

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

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            QueueClient queue = new QueueClient(
               new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
               new DefaultAzureCredential());

            if (args.Length > 0)
            {
                string value = String.Join(" ", args);
                await InsertMessageAsync(queue, value);
                Console.WriteLine($"Sent: {value}");
            }
            else
            {
                string value = await RetrieveNextMessageAsync(queue);
                Console.WriteLine($"Received: {value}");
            }

            Console.Write("Press Enter...");
            Console.ReadLine();
        }

        static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
        {
            if (null != await theQueue.CreateIfNotExistsAsync())
            {
                Console.WriteLine("The queue was created.");
            }

            await theQueue.SendMessageAsync(newMessage);
        }

        static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
        {
            if (await theQueue.ExistsAsync())
            {
                QueueProperties properties = await theQueue.GetPropertiesAsync();

                if (properties.ApproximateMessagesCount > 0)
                {
                    QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
                    string theMessage = retrievedMessage[0].Body.ToString();
                    await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                    return theMessage;
                }
                else
                {
                    Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
                    string response = Console.ReadLine();

                    if (response.ToUpper() == "Y")
                    {
                        await theQueue.DeleteIfExistsAsync();
                        return "The queue was deleted.";
                    }
                    else
                    {
                        return "The queue was not deleted.";
                    }
                }
            }
            else
            {
                return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
            }
        }
    }
}

建置並執行應用程式

從專案目錄中的命令列執行下列 dotnet 命令，以建置專案。
```
dotnet build
```

專案成功建置後，請執行下列命令，將第一個訊息新增至佇列。

dotnet run First queue message

您應該會看見下列輸出：

C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter..._

執行未使用命令列引數的應用程式，以接收和移除佇列中的第一個訊息。
```
dotnet run
```

繼續執行應用程式，直到所有訊息皆移除。如果您再執行一次，應該會出現佇列空白的訊息，以及刪除佇列的提示。

C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run Second queue message
Sent: Second queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run Third queue message
Sent: Third queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: First queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: Second queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: Third queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
The queue is empty. Attempt to delete it? (Y/N) Y
Received: The queue was deleted.
Press Enter...

C:\Tutorials\QueueApp>_

下一步

在本教學課程中，您已了解如何：

建立佇列
從佇列新增和移除訊息
刪除 Azure 佇列儲存體佇列

如需詳細資訊，請參閱 Azure 佇列儲存體快速入門。

入口網站的佇列快速入門

如需使用已淘汰 .NET 11.x 版 SDK 的相關程式碼範例，請參閱使用 .NET 11.x 版的程式碼範例。

共用方式為

教學課程：在 .NET 中使用 Azure 佇列儲存體佇列

必要條件

建立 Azure 儲存體帳戶

建立應用程式

新增 Azure 用戶端程式庫

新增 using 陳述式

新增非同步程式碼的支援

建立佇列

將訊息插入佇列中

清除佇列中的訊息

刪除空的佇列

檢查命令列引數

完整程式碼

建置並執行應用程式

下一步

意見反應

其他資源

共用方式為

教學課程：在 .NET 中使用 Azure 佇列儲存體佇列

必要條件

建立 Azure 儲存體帳戶

建立 應用程式

新增 Azure 用戶端程式庫

新增 using 陳述式

新增非同步程式碼的支援

建立佇列

將訊息插入佇列中

清除佇列中的訊息

刪除空的佇列

檢查命令列引數

完整程式碼

建置並執行應用程式

下一步

意見反應

其他資源

建立應用程式