適用于 .NET 的 Azure 儲存體佇列用戶端程式庫 - 12.13.1 版

發行項
04/03/2023

伺服器版本：2021-02-12、2020-12-06、2020-10-02、 2020-08-04、2020-06-12、2020-04-08、2020-02-10、2019-12-12、2019-07-07 和 2019-02-02

Azure 佇列儲存體是一項儲存大量訊息的服務，全球任何地方都可利用 HTTP 或 HTTPS 並透過驗證的呼叫來存取這些訊息。單一佇列訊息的大小上限為 64 KB，而一個佇列可以包含數百萬個訊息，以儲存體帳戶的總容量為限。

| 原始程式碼套件 (NuGet) | API 參考檔 | REST API 檔 | 產品檔

開始使用

安裝套件

使用 NuGet安裝適用于 .NET 的 Azure 儲存體佇列用戶端程式庫：

dotnet add package Azure.Storage.Queues

必要條件

您需要 Azure 訂用帳戶和儲存體帳戶才能使用此套件。

若要建立新的儲存體帳戶，您可以使用Azure 入口網站、Azure PowerShell或Azure CLI。以下是使用 Azure CLI 的範例：

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

驗證用戶端

若要與 Azure 佇列儲存體服務互動，您必須建立 QueueClient 類別的實例。 Azure 身分識別程式庫可讓您輕鬆地新增 Azure Active Directory 支援，以使用其對應的 Azure 服務驗證 Azure SDK 用戶端。

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

在我們的檔和範例中，深入瞭解如何啟用 Azure Active Directory 以向 Azure 儲存體進行驗證。

重要概念

佇列儲存體的一般用途包括：

建立積存的工作供非同步處理
在分散式應用程式的不同部分之間傳遞訊息

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

範例

傳送訊息

// We'll need a connection string to your 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>
//
// You would normally provide the connection string to your
// application using an environment variable.
string connectionString = "<connection_string>";

// Name of the queue we'll send messages to
string queueName = "sample-queue";

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

// Send a message to our queue
queue.SendMessage("Hello, Azure!");

接收訊息

// We'll need a connection string to your Azure Storage account.
string connectionString = "<connection_string>";

// Name of an existing queue we'll operate on
string queueName = "sample-queue";

// Get a reference to a queue and then fill it with messages
QueueClient queue = new QueueClient(connectionString, queueName);
queue.SendMessage("first");
queue.SendMessage("second");
queue.SendMessage("third");

// Get the next messages from the queue
foreach (QueueMessage message in queue.ReceiveMessages(maxMessages: 10).Value)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.Body}");

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

非同步 API

我們完全支援同步和非同步 API。

// We'll need a connection string to your Azure Storage account.
string connectionString = "<connection_string>";

// Name of the queue we'll send messages to
string queueName = "sample-queue";

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

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

訊息編碼

此版本的程式庫預設不會編碼訊息。 V11 和舊版以及Azure Functions預設會使用 base64 編碼的訊息。因此，建議在 Interop 案例中使用此功能。

QueueClientOptions queueClientOptions = new QueueClientOptions()
{
    MessageEncoding = QueueMessageEncoding.Base64
};

QueueClient queueClient = new QueueClient(connectionString, queueName, queueClientOptions);

疑難排解

所有 Azure 儲存體佇列服務作業都會在失敗時擲回RequestFailedException，但很有説明ErrorCode 。這些錯誤有許多是可復原的。

// We'll need a connection string to your Azure Storage account.
string connectionString = "<connection_string>";

// Name of an existing queue we'll operate on
string queueName = "sample-queue";

try
{
    // Try to create a queue that already exists
    QueueClient queue = new QueueClient(connectionString, queueName);
    queue.Create();
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == QueueErrorCode.QueueAlreadyExists)
{
    // Ignore any errors if the queue already exists
}

下一步

開始使用佇列範例：

Hello World：排入佇列、清除佇列、查看和更新佇列訊息， (或以非同步方式)
驗證：使用連接字串、共用金鑰、共用存取簽章和 Azure Active Directory 進行驗證。

參與

如需建置、測試和參與此程式庫的詳細資訊，請參閱儲存體 CONTRIBUTING.md 。

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請造訪 cla.microsoft.com。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數

共用方式為