クイックスタート: .NET 用 Azure Queue Storage クライアント ライブラリ v12Quickstart: Azure Queue Storage client library v12 for .NET

.NET 用 Azure Queue Storage クライアント ライブラリ バージョン 12 を使用してみましょう。Get started with the Azure Queue Storage client library version 12 for .NET. Azure Queue Storage は、後で取得して処理するために多数のメッセージを格納するためのサービスです。Azure Queue Storage is a service for storing large numbers of messages for later retrieval and processing. 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。Follow these steps to install the package and try out example code for basic tasks.

.NET 用 Azure Queue Storage クライアント ライブラリ v12 を使用すると、以下のことができます。Use the Azure Queue Storage client library v12 for .NET to:

  • キューを作成するCreate a queue
  • メッセージをキューに追加するAdd messages to a queue
  • キュー内のメッセージを表示するPeek at messages in a queue
  • キュー内のメッセージを更新するUpdate a message in a queue
  • キューからメッセージを受信するReceive messages from a queue
  • キューからメッセージを削除するDelete messages from a queue
  • キューを削除するDelete a queue

その他のリソース:Additional resources:

前提条件Prerequisites

設定Setting up

このセクションでは、.NET 用 Azure Queue Storage クライアント ライブラリ v12 を操作するためのプロジェクトの準備について説明します。This section walks you through preparing a project to work with the Azure Queue Storage client library v12 for .NET.

プロジェクトを作成するCreate the project

QueuesQuickstartV12 という名前の .NET Core アプリケーションを作成します。Create a .NET Core application named QueuesQuickstartV12.

  1. コンソール ウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、QueuesQuickstartV12 という名前で新しいコンソール アプリを作成します。In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name QueuesQuickstartV12. このコマンドにより、1 つのソース ファイル (Program.cs) を使用する単純な "hello world" C# プロジェクトが作成されます。This command creates a simple "hello world" C# project with a single source file named Program.cs.

    dotnet new console -n QueuesQuickstartV12
    
  2. 新しく作成した QueuesQuickstartV12 ディレクトリに切り替えます。Switch to the newly created QueuesQuickstartV12 directory.

    cd QueuesQuickstartV12
    

パッケージをインストールするInstall the package

まだアプリケーション ディレクトリにいる間に、dotnet add package コマンドを使用して、.NET 用の Azure Queue Storage クライアント ライブラリ パッケージをインストールします。While still in the application directory, install the Azure Queue Storage client library for .NET package by using the dotnet add package command.

dotnet add package Azure.Storage.Queues

アプリのフレームワークを設定するSet up the app framework

プロジェクト ディレクトリで次の操作を行います。From the project directory:

  1. エディターで Program.cs ファイルを開きますOpen the Program.cs file in your editor
  2. Console.WriteLine("Hello, World"); ステートメントを削除しますRemove the Console.WriteLine("Hello, World"); statement
  3. using ディレクティブを追加しますAdd using directives
  4. 非同期コードをサポートするように Main メソッドの宣言を更新しますUpdate the Main method declaration to support async code

コードは次のとおりです。Here's the code:

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 Portal で資格情報をコピーするCopy your credentials from the Azure portal

サンプル アプリケーションから Azure Storage に対して要求を実行するときは、承認されている必要があります。When the sample application makes a request to Azure Storage, it must be authorized. 要求を承認するには、ストレージ アカウントの資格情報を接続文字列としてアプリケーションに追加します。To authorize a request, add your storage account credentials to the application as a connection string. 次の手順に従って、ストレージ アカウントの資格情報を表示します。View your storage account credentials by following these steps:

  1. Azure portal にサインインします。Sign in to the Azure portal.

  2. 自分のストレージ アカウントを探します。Locate your storage account.

  3. ストレージ アカウントの概要の [設定] セクションで、 [アクセス キー] を選択します。In the Settings section of the storage account overview, select Access keys. ここでは、アカウント アクセス キーと各キーの完全な接続文字列を表示できます。Here, you can view your account access keys and the complete connection string for each key.

  4. [Key1][接続文字列] の値を見つけ、 [コピー] ボタンを選択して接続文字列をコピーします。Find the Connection string value under key1, and select the Copy button to copy the connection string. すぐ後の手順で、接続文字列の値を環境変数に追加します。You will add the connection string value to an environment variable in the next step.

    Azure portal から接続文字列をコピーする方法を示すスクリーンショット

ストレージ接続文字列の構成Configure your storage connection string

接続文字列をコピーした後、アプリケーションを実行しているローカル マシンの新しい環境変数にそれを書き込みます。After you have copied your connection string, write it to a new environment variable on the local machine running the application. 環境変数を設定するには、コンソール ウィンドウを開いて、お使いのオペレーティング システムの手順に従います。To set the environment variable, open a console window, and follow the instructions for your operating system. <yourconnectionstring> は、実際の接続文字列に置き換えてください。Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Windows で環境変数を追加した後、コマンド ウィンドウの新しいインスタンスを開始する必要があります。After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

プログラムの再起動Restart programs

環境変数を追加した後、環境変数の読み取りを必要とする実行中のプログラムをすべて再起動します。After you add the environment variable, restart any running programs that will need to read the environment variable. たとえば、続行する前に、ご使用の開発環境またはエディターを再起動します。For example, restart your development environment or editor before continuing.

オブジェクト モデルObject model

Azure Queue storage は、多数のメッセージを格納するためのサービスです。Azure Queue Storage is a service for storing large numbers of messages. キュー メッセージの許容される最大サイズは 64 KB です。A queue message can be up to 64 KB in size. キューには、ストレージ アカウントの総容量の上限を超えない限り、数百万のメッセージを含めることができます。A queue may contain millions of messages, up to the total capacity limit of a storage account. キューは通常、非同期的な処理用に作業のバックログを作成するために使用されます。Queues are commonly used to create a backlog of work to process asynchronously. Queue Storage には、次の 3 種類のリソースがあります。Queue Storage offers three types of resources:

  • ストレージ アカウントThe storage account
  • ストレージ アカウント内のキューA queue in the storage account
  • キュー内のメッセージMessages within the queue

次の図に、これらのリソースの関係を示します。The following diagram shows the relationship between these resources.

Queue storage のアーキテクチャ図

これらのリソースとやり取りするには、以下の .NET クラスを使用します。Use the following .NET classes to interact with these resources:

  • QueueServiceClient: QueueServiceClient を使用すると、ストレージ アカウント内のすべてのキューを管理できます。QueueServiceClient: The QueueServiceClient allows you to manage the all queues in your storage account.
  • QueueClient: QueueClient クラスを使用すると、個々のキューとそのメッセージを管理および操作できます。QueueClient: The QueueClient class allows you to manage and manipulate an individual queue and its messages.
  • QueueMessage: QueueMessage クラスは、キューに対して ReceiveMessages を呼び出したときに返される個々のオブジェクトを表します。QueueMessage: The QueueMessage class represents the individual objects returned when calling ReceiveMessages on a queue.

コード例Code examples

以下のサンプル コード スニペットは、.NET 用 Azure Queue Storage クライアント ライブラリを使用して以下の操作を実行する方法を示します。These example code snippets show you how to perform the following actions with the Azure Queue Storage client library for .NET:

接続文字列を取得するGet the connection string

以下のコードは、ストレージ アカウントの接続文字列を取得します。The following code retrieves the connection string for the storage account. この接続文字列は、「ストレージ接続文字列の構成」セクションで作成した環境変数に格納されます。The connection string is stored in the environment variable created in the Configure your storage connection string section.

このコードを Main メソッド内に追加します。Add this code inside the Main method:

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

キューを作成するCreate a queue

新しいキューの名前を決定します。Decide on a name for the new queue. 次のコードは、キュー名に GUID 値を追加して、確実に一意になるようにします。The following code appends a GUID value to the queue name to ensure that it's unique.

重要

キュー名に使用できるのは小文字、数字、ハイフンのみであり、名前の先頭は文字または数字にする必要があります。Queue names may only contain lowercase letters, numbers, and hyphens, and must begin with a letter or a number. 各ハイフンの前後にはハイフン以外の文字を指定する必要があります。Each hyphen must be preceded and followed by a non-hyphen character. また、名前は 3 から 63 文字で指定する必要があります。The name must also be between 3 and 63 characters long. 詳細については、「キューおよびメタデータの名前付け」を参照してください。For more information, see Naming queues and metadata.

QueueClient クラスのインスタンスを作成します。Create an instance of the QueueClient class. 次に、CreateAsync メソッドを呼び出して、ストレージ アカウントにキューを作成します。Then, call the CreateAsync method to create the queue in your storage account.

Main メソッドの末尾に次のコードを追加します。Add this code to the end of the Main method:

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

メッセージをキューに追加するAdd messages to a queue

以下のコード スニペットでは、SendMessageAsync メソッドを呼び出してキューにメッセージを非同期的に追加します。The following code snippet asynchronously adds messages to queue by calling the SendMessageAsync method. さらに、SendMessageAsync の呼び出しから返された SendReceipt を保存します。It also saves a SendReceipt returned from a SendMessageAsync call. この receipt は、後でプログラムの中でメッセージを更新する際に使用します。The receipt is used to update the message later in the program.

Main メソッドの末尾に次のコードを追加します。Add this code to the end of the Main method:

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

キュー内のメッセージを表示するPeek at messages in a queue

キュー内のメッセージをクイック表示するには、PeekMessagesAsync メソッドを呼び出します。Peek at the messages in the queue by calling the PeekMessagesAsync method. このメソッドは、キューの先頭からメッセージを 1 つ以上取得しますが、メッセージの可視性は変更しません。This method retrieves one or more messages from the front of the queue but doesn't alter the visibility of the message.

Main メソッドの末尾に次のコードを追加します。Add this code to the end of the Main method:

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

キュー内のメッセージを更新するUpdate a message in a queue

メッセージの内容を更新するには、UpdateMessageAsync メソッドを呼び出します。Update the contents of a message by calling the UpdateMessageAsync method. メッセージの表示タイムアウトと内容は、このメソッドで変更できます。This method can change a message's visibility timeout and contents. メッセージの内容には UTF-8 でエンコードされた文字列を指定してください。最大サイズは 64 KB です。The message content must be a UTF-8 encoded string that is up to 64 KB in size. 先ほどこのコードの中で保存した SendReceipt の値を、新しいメッセージの内容と共に渡します。Along with the new content for the message, pass in the values from the SendReceipt that was saved earlier in the code. SendReceipt の値によって、更新するメッセージが識別されます。The SendReceipt values identify which message to update.

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

キューからメッセージを受信するReceive messages from a queue

ReceiveMessagesAsync メソッドを呼び出して、先ほど追加したメッセージをダウンロードします。Download previously added messages by calling the ReceiveMessagesAsync method.

Main メソッドの末尾に次のコードを追加します。Add this code to the end of the Main method:

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

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

キューからメッセージを削除するDelete messages from a queue

メッセージが処理された後、キューからメッセージを削除します。Delete messages from the queue after they're been processed. ここでの処理は、単にメッセージをコンソールに表示するだけです。In this case, processing is just displaying the message on the console.

ユーザーからの入力を待ってメッセージを処理、削除するために、Console.ReadLine を呼び出してアプリを一時停止させます。The app pauses for user input by calling Console.ReadLine before it processes and deletes the messages. リソースが正しく作成されたことを Azure portal で確認してから、それらを削除してください。Verify in your Azure portal that the resources were created correctly, before they're deleted. 明示的に削除されなかったメッセージは、最終的にキューに再表示され、別の機会に処理されることになります。Any messages not explicitly deleted will eventually become visible in the queue again for another chance to process them.

Main メソッドの末尾に次のコードを追加します。Add this code to the end of the Main method:

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

キューを削除するDelete a queue

次のコードでは、DeleteAsync メソッドを使用してキューを削除することにより、アプリによって作成されたリソースがクリーンアップされます。The following code cleans up the resources the app created by deleting the queue using the DeleteAsync method.

Main メソッドの末尾に次のコードを追加します。Add this code to the end of the Main method:

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

コードの実行Run the code

このアプリは、3 つのメッセージを作成して Azure のキューに追加します。This app creates and adds three messages to an Azure queue. コードでは、キュー内のメッセージを一覧表示した後にそれらを取得して削除してから、最後にキューを削除します。The code lists the messages in the queue, then retrieves and deletes them, before finally deleting the queue.

コンソール ウィンドウで、お使いのアプリケーションのディレクトリに移動し、アプリケーションをビルドして実行します。In your console window, navigate to your application directory, then build and run the application.

dotnet build
dotnet run

アプリの出力は、次の例のようになります。The output of the app is similar to the following example:

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 portal でストレージ アカウントを確認してください。When the app pauses before receiving messages, check your storage account in the Azure portal. キューにメッセージが存在することを確認します。Verify the messages are in the queue.

Enter キーを押してメッセージを受信し、削除します。Press the Enter key to receive and delete the messages. 確認を求められたら、もう一度 Enter キーを押してキューを削除し、デモを終了します。When prompted, press the Enter key again to delete the queue and finish the demo.

次のステップNext steps

このクイックスタートでは、非同期 .NET コードを使用して、キューを作成し、そこにメッセージを追加する方法について説明しました。In this quickstart, you learned how to create a queue and add messages to it using asynchronous .NET code. その後、メッセージの表示、取得、削除について説明しました。Then you learned to peek, retrieve, and delete messages. 最後に、メッセージ キューを削除する方法を説明しました。Finally, you learned how to delete a message queue.

チュートリアル、サンプル、クイック スタートなどのドキュメントについては、次のページを参照してください。For tutorials, samples, quick starts and other documentation, visit: