Samouczek: praca z kolejkami usługi Azure Queue Storage na platformie .NET

  • Artykuł

Usługa Azure Queue Storage implementuje kolejki oparte na chmurze, aby umożliwić komunikację między składnikami aplikacji rozproszonej. Każda kolejka przechowuje listę komunikatów, które mogą być dodawane przez składnik nadawcy i przetwarzane przez składnik odbiorcy. Dzięki kolejce aplikacja może natychmiast skalować w celu spełnienia wymagań. W tym artykule przedstawiono podstawowe kroki pracy z kolejką usługi Azure Queue Storage.

Ten samouczek zawiera informacje na temat wykonywania następujących czynności:

  • Tworzenie konta usługi Azure Storage
  • Tworzenie aplikacji
  • Dodawanie bibliotek klienckich platformy Azure
  • Dodawanie obsługi kodu asynchronicznego
  • Tworzenie kolejki
  • Wstawianie komunikatów do kolejki
  • Dequeue messages (Dequeue messages)
  • Usuwanie pustej kolejki
  • Sprawdzanie argumentów wiersza polecenia
  • Skompiluj i uruchom aplikację

Wymagania wstępne

  • Pobierz bezpłatną kopię międzyplatformowego edytora Visual Studio Code.
  • Pobierz i zainstaluj zestaw .NET Core SDK w wersji 3.1 lub nowszej.
  • Jeśli nie masz bieżącej subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto .

Tworzenie konta usługi Azure Storage

Najpierw utwórz konto usługi Azure Storage. Aby zapoznać się z przewodnikiem krok po kroku dotyczącym tworzenia konta magazynu, zobacz Tworzenie konta magazynu. Jest to oddzielny krok, który należy wykonać po utworzeniu bezpłatnego konta platformy Azure w wymaganiach wstępnych.

Tworzenie aplikacji

Utwórz aplikację platformy .NET Core o nazwie QueueApp. Dla uproszczenia ta aplikacja będzie wysyłać i odbierać komunikaty za pośrednictwem kolejki.

  1. W oknie konsoli (takim jak cmd, PowerShell lub interfejs wiersza polecenia platformy Azure) użyj dotnet new polecenia , aby utworzyć nową aplikację konsolową o nazwie QueueApp. To polecenie tworzy prosty projekt języka C# "hello world" z pojedynczym plikiem źródłowym o nazwie Program.cs.

    dotnet new console -n QueueApp

  2. Przejdź do nowo utworzonego folderu QueueApp i skompiluj aplikację, aby sprawdzić, czy wszystko jest w porządku.

    cd QueueApp

    dotnet build

    Powinny zostać wyświetlone wyniki podobne do następujących danych wyjściowych:

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

Dodawanie bibliotek klienckich platformy Azure

  1. Dodaj biblioteki klienta usługi Azure Storage do projektu przy użyciu dotnet add package polecenia .

    Uruchom następujące polecenie z folderu projektu w oknie konsoli.

    dotnet add package Azure.Storage.Queues

Dodawanie instrukcji using

  1. W wierszu polecenia w katalogu projektu wpisz code . , aby otworzyć Visual Studio Code w bieżącym katalogu. Pozostaw otwarte okno wiersza polecenia. Będzie więcej poleceń do uruchomienia później. Jeśli zostanie wyświetlony monit o dodanie zasobów języka C# wymaganych do skompilowania i debugowania, kliknij przycisk Tak .

  2. Program.cs Otwórz plik źródłowy i dodaj następujące przestrzenie nazw bezpośrednio po instrukcji using System; . Ta aplikacja używa typów z tych przestrzeni nazw do łączenia się z usługą Azure Storage i pracy z kolejkami.

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

  3. Zapisz plik Program.cs.

Dodawanie obsługi kodu asynchronicznego

Ponieważ aplikacja korzysta z zasobów w chmurze, kod jest uruchamiany asynchronicznie.

  1. Zaktualizuj metodę Main , aby uruchomić asynchronicznie. Zastąp void element wartością zwracaną async Task .

    static async Task Main(string[] args)

  2. Zapisz plik Program.cs.

Tworzenie kolejki

Przed wykonaniem wywołań do interfejsów API platformy Azure należy uzyskać poświadczenia z Azure Portal.

Kopiowanie poświadczeń z witryny Azure Portal

Gdy przykładowa aplikacja wysyła żądanie do usługi Azure Storage, musi być autoryzowana. Aby autoryzować żądanie, dodaj poświadczenia konta magazynu do aplikacji jako parametry połączenia. Aby wyświetlić poświadczenia konta magazynu, wykonaj następujące kroki:

  1. Zaloguj się w witrynie Azure Portal.

  2. Odszukaj konto magazynu.

  3. W okienku menu konta magazynu w obszarze Zabezpieczenia i sieć wybierz pozycję Klucze dostępu. W tym miejscu można wyświetlić klucze dostępu do konta i pełne parametry połączenia dla każdego klucza.

    Zrzut ekranu pokazujący, gdzie znajdują się ustawienia klucza dostępu w Azure Portal

  4. W okienku Klucze dostępu wybierz pozycję Pokaż klucze.

  5. W sekcji key1 znajdź wartość Parametry połączenia . Wybierz ikonę Kopiuj do schowka , aby skopiować parametry połączenia. W następnej sekcji dodasz wartość parametrów połączenia do zmiennej środowiskowej.

    Zrzut ekranu pokazujący sposób kopiowania parametrów połączenia z witryny Azure Portal

Konfigurowanie parametrów połączenia magazynu

Po skopiowaniu parametrów połączenia zapisz je w nowej zmiennej środowiskowej na komputerze lokalnym z uruchomioną aplikacją. Aby ustawić zmienną środowiskową, otwórz okno konsoli i postępuj zgodnie z instrukcjami dla systemu operacyjnego. Zastąp <yourconnectionstring> ciąg rzeczywistymi parametrami połączenia.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Po dodaniu zmiennej środowiskowej w systemie Windows należy uruchomić nowe wystąpienie okna polecenia.

Ponowne uruchamianie programów

Po dodaniu zmiennej środowiskowej uruchom ponownie wszystkie uruchomione programy, które będą musiały odczytać zmienną środowiskową. Na przykład przed kontynuowaniem uruchom ponownie środowisko programistyczne lub edytor.

Dodawanie parametrów połączenia do aplikacji

Dodaj parametry połączenia do aplikacji, aby uzyskać dostęp do konta magazynu.

  1. Wróć do Visual Studio Code.

  2. W metodzie Main zastąp Console.WriteLine("Hello, World"); kod następującym wierszem, który pobiera parametry połączenia ze zmiennej środowiskowej.

    string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

  3. Dodaj następujący kod, aby Main utworzyć obiekt kolejki, który jest później przekazywany do metod wysyłania i odbierania.

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

  4. Zapisz plik.

Wstawianie komunikatów do kolejki

Utwórz nową metodę wysyłania komunikatu do kolejki.

  1. Dodaj następującą InsertMessageAsync metodę do Program klasy .

    Ta metoda jest przekazywana odwołanie do kolejki. Zostanie utworzona nowa kolejka, jeśli jeszcze nie istnieje, wywołując metodę CreateIfNotExistsAsync. Następnie dodaje element newMessage do kolejki, wywołując metodę 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. Opcjonalne: Domyślnie maksymalny czas wygaśnięcia wiadomości wynosi siedem dni. Możesz określić dowolną liczbę dodatnią dla czasu wygaśnięcia wiadomości. Poniższy fragment kodu dodaje komunikat, który nigdy nie wygasa.

    Aby dodać komunikat, który nie wygaśnie, użyj Timespan.FromSeconds(-1) w wywołaniu metody .SendMessageAsync

    await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);

  3. Zapisz plik.

Komunikat w kolejce musi być w formacie zgodnym z żądaniem XML przy użyciu kodowania UTF-8. Rozmiar komunikatu może wynosić do 64 KB. Jeśli komunikat zawiera dane binarne, zakoduj komunikat Base64 .

Dequeue messages (Dequeue messages)

Utwórz nową metodę pobierania komunikatu z kolejki. Po pomyślnym odebraniu komunikatu ważne jest usunięcie go z kolejki, aby nie było przetwarzane więcej niż raz.

  1. Dodaj nową metodę o nazwie RetrieveNextMessageAsync do Program klasy.

    Ta metoda odbiera komunikat z kolejki, wywołując ReceiveMessagesAsyncmetodę , przekazując 1 pierwszy parametr w celu pobrania tylko kolejnego komunikatu w kolejce. Po odebraniu komunikatu usuń go z kolejki, wywołując metodę DeleteMessageAsync.

    Gdy komunikat jest wysyłany do kolejki z wersją zestawu SDK przed wersją 12, jest on automatycznie zakodowany w formacie Base64. Począwszy od wersji 12, ta funkcja została usunięta. Podczas pobierania komunikatu przy użyciu zestawu SDK w wersji 12 nie jest on automatycznie dekodowany za pomocą algorytmu Base64. Musisz jawnie zdekodować zawartość w formacie Base64 samodzielnie.

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

  2. Zapisz plik.

Usuwanie pustej kolejki

Jest to najlepsze rozwiązanie na końcu projektu, aby określić, czy nadal są potrzebne utworzone zasoby. Uruchomione zasoby mogą generować koszty. Jeśli kolejka istnieje, ale jest pusta, zapytaj użytkownika, czy chce ją usunąć.

  1. Rozwiń metodę , RetrieveNextMessageAsync aby dołączyć monit o usunięcie pustej kolejki.

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

  2. Zapisz plik.

Sprawdzanie argumentów wiersza polecenia

Jeśli do aplikacji są przekazywane argumenty wiersza polecenia, załóżmy, że są one komunikatem, który ma zostać dodany do kolejki. Połącz argumenty, aby utworzyć ciąg. Dodaj ten ciąg do kolejki komunikatów, wywołując wcześniej dodaną metodę InsertMessageAsync .

Jeśli nie ma argumentów wiersza polecenia, spróbuj pobrać operację. Wywołaj metodę , RetrieveNextMessageAsync aby pobrać następny komunikat w kolejce.

Na koniec poczekaj na dane wejściowe użytkownika przed zakończeniem pracy, wywołując metodę Console.ReadLine.

  1. Rozwiń metodę , Main aby sprawdzić argumenty wiersza polecenia i poczekać na wprowadzenie danych przez użytkownika.

    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. Zapisz plik.

Kompletny kod

Oto kompletna lista kodu dla tego projektu.

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

Skompiluj i uruchom aplikację

  1. W wierszu polecenia w katalogu projektu uruchom następujące polecenie dotnet, aby skompilować projekt.

    dotnet build

  2. Po pomyślnym utworzeniu projektu uruchom następujące polecenie, aby dodać pierwszy komunikat do kolejki.

    dotnet run First queue message

    Powinny być widoczne następujące dane wyjściowe:

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

  3. Uruchom aplikację bez argumentów wiersza polecenia, aby odbierać i usuwać pierwszy komunikat w kolejce.

    dotnet run

  4. Kontynuuj uruchamianie aplikacji do momentu usunięcia wszystkich komunikatów. Jeśli uruchomisz go jeszcze raz, zostanie wyświetlony komunikat informujący, że kolejka jest pusta i zostanie wyświetlony monit o usunięcie kolejki.

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

Następne kroki

W niniejszym samouczku zawarto informacje na temat wykonywania następujących czynności:

  1. Tworzenie kolejki
  2. Dodawanie i usuwanie komunikatów z kolejki
  3. Usuwanie kolejki usługi Azure Queue Storage

Aby uzyskać więcej informacji, zapoznaj się z przewodnikami Szybki start usługi Azure Queue Storage.

Przewodnik Szybki start dotyczący kolejek dla portalu

Aby uzyskać powiązane przykłady kodu korzystające z przestarzałych zestawów SDK platformy .NET w wersji 11.x, zobacz Przykłady kodu przy użyciu platformy .NET w wersji 11.x.