チュートリアル:.NET で Azure Queue Storage キューを操作するTutorial: Work with Azure Queue Storage queues in .NET

Azure Queue Storage では、クラウドベースのキューが実装され、分散アプリケーションのコンポーネント間で通信できます。Azure Queue Storage implements cloud-based queues to enable communication between components of a distributed application. 各キューには、送信側コンポーネントにより追加し、受信側コンポーネントにより処理できるメッセージの一覧が保持されます。Each queue maintains a list of messages that can be added by a sender component and processed by a receiver component. キューを利用することで、アプリケーションを需要に合わせてすぐにスケーリングできます。With a queue, your application can scale immediately to meet demand. この記事では、Azure Queue Storage を使用するための基本手順について説明します。This article shows the basic steps for working with an Azure Queue Storage queue.

このチュートリアルでは、以下の内容を学習します。In this tutorial, you learn how to:

  • Azure Storage アカウントの作成Create an Azure Storage account
  • アプリを作成するCreate the app
  • Azure クライアント ライブラリを追加するAdd the Azure client libraries
  • 非同期コードのサポートを追加するAdd support for asynchronous code
  • キューを作成するCreate a queue
  • キューにメッセージを挿入するInsert messages into a queue
  • メッセージをデキューするDequeue messages
  • 空のキューを削除するDelete an empty queue
  • コマンドライン引数を確認するCheck for command-line arguments
  • アプリのビルドと実行Build and run the app

前提条件Prerequisites

  • プラットフォームに依存しない Visual Studio Code エディターの無料コピーを入手します。Get your free copy of the cross platform Visual Studio Code editor.
  • .NET Core SDK バージョン 3.1 以降をダウンロードし、インストールします。Download and install the .NET Core SDK version 3.1 or later.
  • Azure サブスクリプションを現在お持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have a current Azure subscription, create a free account before you begin.

Azure Storage アカウントを作成するCreate an Azure Storage account

まず、Azure Storage アカウントを作成します。First, create an Azure Storage account. ストレージ アカウントを作成する詳細な手順については、「ストレージ アカウントを作成する」を参照してください。For a step-by-step guide to creating a storage account, see Create a storage account. 前提条件の無料 Azure アカウントを作成した後に別途行う手順となります。This is a separate step you perform after creating a free Azure account in the prerequisites.

アプリを作成するCreate the app

QueueApp という名前の .NET Core アプリケーションを作成します。Create a .NET Core application named QueueApp. わかりやすくするために、このアプリではメッセージの送受信ともキューを介して行います。For simplicity, this app will both send and receive messages through the queue.

  1. コンソール ウィンドウ (cmd、PowerShell、Azure CLI など) で、dotnet new コマンドを使用し、QueueApp という名前で新しいコンソール アプリを作成します。In a console window (such as cmd, PowerShell, or Azure CLI), use the dotnet new command to create a new console app with the name QueueApp. このコマンドにより、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 QueueApp
    
  2. 新しく作成された QueueApp フォルダーに切り替え、アプリをビルドして、すべて問題ないことを確認します。Switch to the newly created QueueApp folder and build the app to verify that all is well.

    cd QueueApp
    
    dotnet build
    

    次の出力のような結果が表示されます。You should see results similar to the following output:

    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 クライアント ライブラリを追加するAdd the Azure client libraries

  1. dotnet add package コマンドを使用して、Azure Storage クライアント ライブラリをプロジェクトに追加します。Add the Azure Storage client libraries to the project by using the dotnet add package command.

    コンソール ウィンドウでプロジェクト フォルダーから次のコマンドを実行します。Run the following command from the project folder in the console window.

    dotnet add package Azure.Storage.Queues
    

using ステートメントを追加するAdd using statements

  1. プロジェクト ディレクトリのコマンド ラインで「code .」と入力し、現在のディレクトリで Visual Studio Code を開きます。From the command line in the project directory, type code . to open Visual Studio Code in the current directory. コマンドライン ウィンドウは開いたままにします。Keep the command-line window open. 後で他にもコマンドを実行します。There will be more commands to run later. ビルドとデバッグに必要な C# アセットを追加するように求められた場合、 [はい] をクリックします。If you're prompted to add C# assets required to build and debug, click the Yes button.

  2. Program.cs ソース ファイルを開いて、using System; ステートメントの直後に次の名前空間を追加します。Open the Program.cs source file and add the following namespaces right after the using System; statement. このアプリでは、Azure Storage に接続し、キューを使用するとき、これらの名前空間からの型が使用されます。This app uses types from these namespaces to connect to Azure Storage and work with queues.

    using System.Threading.Tasks;
    using Azure.Storage.Queues;
    using Azure.Storage.Queues.Models;
    
  3. Program.cs ファイルを保存します。Save the Program.cs file.

非同期コードのサポートを追加するAdd support for asynchronous code

このアプリではクラウド リソースが使用されているため、コードは非同期で実行されます。Since the app uses cloud resources, the code runs asynchronously.

  1. 非同期で実行されるように Main メソッドを更新します。Update the Main method to run asynchronously. voidasync Task 戻り値に変更します。Replace void with an async Task return value.

    static async Task Main(string[] args)
    
  2. Program.cs ファイルを保存します。Save the Program.cs file.

キューを作成するCreate a queue

Azure API を呼び出す前に、Azure portal から資格情報を取得する必要があります。Before making any calls into Azure APIs, you must get your credentials from the Azure portal.

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.

アプリに接続文字列を追加するAdd the connection string to the app

ストレージ アカウントにアクセスできるよう、アプリに接続文字列を追加します。Add the connection string into the app so it can access the storage account.

  1. Visual Studio Code に戻ります。Switch back to Visual Studio Code.

  2. Main メソッドで、Console.WriteLine("Hello, World"); コードを、環境変数から接続文字列を取得する次の行に置き換えます。In the Main method, replace the Console.WriteLine("Hello, World"); code with the following line that gets the connection string from the environment variable.

    string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
    
  3. キュー オブジェクトを作成する次のコードを Main に追加します。このキュー オブジェクトを後で送信メソッドと受信メソッドに渡します。Add the following code to Main to create a queue object, which is later passed into the send and receive methods.

    QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
    
  4. ファイルを保存します。Save the file.

キューにメッセージを挿入するInsert messages into the queue

キューにメッセージを送信する新しいメソッドを作成します。Create a new method to send a message into the queue.

  1. 次の InsertMessageAsync メソッドを Program クラスに追加します。Add the following InsertMessageAsync method to your Program class.

    このメソッドには、キューの参照が渡されます。This method is passed a queue reference. まだキューがない場合は、CreateIfNotExistsAsync を呼び出すことによって新しいキューが作成されます。A new queue is created, if it doesn't already exist, by calling CreateIfNotExistsAsync. 次に、SendMessageAsync を呼び出すことによって、キューに newMessage が追加されます。Then, it adds the newMessage to the queue by calling SendMessageAsync.

    static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
    {
        if (null != await theQueue.CreateIfNotExistsAsync())
        {
            Console.WriteLine("The queue was created.");
        }
    
        await theQueue.SendMessageAsync(newMessage);
    }
    
  2. 省略可能: 既定では、メッセージの最大 Time to Live は 7 日に設定されます。Optional: By default, the maximum time-to-live for a message is set to seven days. メッセージの有効期限には、任意の正の数値を指定できます。You can specify any positive number for the message time-to-live. 次のコード スニペットは、有効期限の "ない" メッセージを追加します。The following code snippet adds a message that never expires.

    有効期限のないメッセージを追加するには、SendMessageAsync への呼び出しで Timespan.FromSeconds(-1) を使用します。To add a message that doesn't expire, use Timespan.FromSeconds(-1) in your call to SendMessageAsync.

    await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
    
  3. ファイルを保存します。Save the file.

キュー メッセージは、UTF-8 エンコードを使用して、XML 要求と互換性のある形式にする必要があります。A queue message must be in a format compatible with an XML request using UTF-8 encoding. メッセージの許容される最大サイズは 64 KB です。A message may be up to 64 KB in size. メッセージにバイナリ データが含まれている場合は、メッセージを Base64 でエンコードしてください。If a message contains binary data, Base64-encode the message.

メッセージをデキューするDequeue messages

キューからメッセージを取得する新しいメソッドを作成します。Create a new method to retrieve a message from the queue. メッセージが正常に受け取られたら、何度も処理されないよう、キューから削除しておくことが重要です。Once the message is successfully received, it's important to delete it from the queue so it isn't processed more than once.

  1. RetrieveNextMessageAsync という新しいメソッドを Program クラスに追加します。Add a new method called RetrieveNextMessageAsync to your Program class.

    このメソッドは、ReceiveMessagesAsync を呼び出してキューからメッセージを受け取ります。第 1 パラメーターに 1 を渡すと、キューにおける次のメッセージだけが取得されます。This method receives a message from the queue by calling ReceiveMessagesAsync, passing 1 in the first parameter to retrieve only the next message in the queue. メッセージを受け取ったら、DeleteMessageAsync を呼び出して、キューからそれを削除します。After the message is received, delete it from the queue by calling DeleteMessageAsync.

    v12 より前のバージョンの SDK でメッセージがキューに送信されると、自動的に Base64 でエンコードされます。When a message is sent to the queue with a version of the SDK prior to v12, it is automatically Base64-encoded. v12 以降では、この機能は削除されています。Starting with v12, that functionality was removed. v12 SDK を使用してメッセージを取得しても、自動的に Base64 デコードされることはありません。When you retrieve a message by using the v12 SDK, it is not automatically Base64-decoded. コンテンツは、明示的に Base64 デコードする必要があります。You must explicitly Base64-decode the contents yourself.

    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].MessageText;
                await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                return theMessage;
            }
    
            return null;
        }
    
        return null;
    }
    
  2. ファイルを保存します。Save the file.

空のキューを削除するDelete an empty queue

プロジェクトの終わりに、作成したリソースを引き続き必要とするかどうかを判断することをお勧めします。It's a best practice at the end of a project to identify whether you still need the resources you created. リソースを実行したままにすると、お金がかかる場合があります。Resources left running can cost you money. キューが存在するが空の場合、削除して良いかどうかをユーザーに確認してください。If the queue exists but is empty, ask the user if they would like to delete it.

  1. RetrieveNextMessageAsync メソッドを拡張し、空のキューを削除するプロンプトを追加します。Expand the RetrieveNextMessageAsync method to include a prompt to delete the empty queue.

    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].MessageText;
                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.";
        }
    }
    
  2. ファイルを保存します。Save the file.

コマンドライン引数を確認するCheck for command-line arguments

コマンドラインの引数がアプリに渡されている場合、それらがキューに追加するメッセージであると想定してください。If there are any command-line arguments passed into the app, assume they're a message to be added to the queue. 引数を結合し、文字列を作ります。Join the arguments together to make a string. 前に追加した InsertMessageAsync メソッドを呼び出し、この文字列をメッセージ キューに追加します。Add this string to the message queue by calling the InsertMessageAsync method we added earlier.

コマンドラインの引数がない場合、取得操作を試行します。If there are no command-line arguments, attempt a retrieve operation. RetrieveNextMessageAsync メソッドを呼び出し、キューの次のメッセージを取得します。Call the RetrieveNextMessageAsync method to retrieve the next message in the queue.

最後に、Console.ReadLine を呼び出し、ユーザーの入力を待ってから終了します。Finally, wait for user input before exiting by calling Console.ReadLine.

  1. コマンドラインの引数を確認し、ユーザーの入力を待つよう、Main メソッドを拡張します。Expand the Main method to check for command-line arguments and wait for user input.

    static async Task Main(string[] args)
    {
        string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
    
        QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
    
        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();
    }
    
  2. ファイルを保存します。Save the file.

完成したコードComplete code

このプロジェクトの完成したコードは次のようになります。Here is the complete code listing for this project.

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

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

            QueueClient queue = new QueueClient(connectionString, "mystoragequeue");

            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].MessageText;
                    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.";
            }
        }
    }
}

アプリのビルドと実行Build and run the app

  1. プロジェクト ディレクトリのコマンド ラインから、次の dotnet コマンドを実行し、プロジェクトをビルドします。From the command line in the project directory, run the following dotnet command to build the project.

    dotnet build
    
  2. プロジェクトが正常にビルドされたら、次のコマンドを実行し、最初のメッセージをキューに追加します。After the project builds successfully, run the following command to add the first message to the queue.

    dotnet run First queue message
    

    次のように出力されます。You should see this output:

    C:\Tutorials\QueueApp>dotnet run First queue message
    The queue was created.
    Sent: First queue message
    Press Enter..._
    
  3. コマンドラインの引数なしでアプリを実行し、キューの最初のメッセージを受け取り、削除します。Run the app with no command-line arguments to receive and remove the first message in the queue.

    dotnet run
    
  4. すべてのメッセージが削除されるまでアプリの実行を続けます。Continue to run the app until all the messages are removed. さらに 1 回実行すると、キューが空であるというメッセージとキューを削除するためのプロンプトが表示されます。If you run it one more time, you'll get a message that the queue is empty and a prompt to delete the queue.

    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>_
    

次のステップNext steps

このチュートリアルでは、以下の内容を学習しました。In this tutorial, you learned how to:

  1. キューを作成するCreate a queue
  2. メッセージをキューに追加し、キューから削除するAdd and remove messages from a queue
  3. Azure Queue Storage キューを削除するDelete an Azure Queue Storage queue

詳細については、Azure Queue Storage のクイックスタートを参照してください。Check out the Azure Queue Storage quickstarts for more information.