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

Artykuł
08/08/2024

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 być skalowana natychmiast, aby zaspokoić zapotrzebowanie. W tym artykule przedstawiono podstawowe kroki pracy z kolejką usługi Azure Queue Storage.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

Tworzenie konta usługi Azure Storage
Tworzenie aplikacji
Dodawanie bibliotek klienckich platformy Azure
Dodawanie obsługi kodu asynchronicznego
Utwórz kolejkę
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 programu 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.
Upewnij się, że twoje konto użytkownika zostało przypisane do roli Współautor danych kolejki magazynu, w zakresie do konta magazynu, nadrzędnej grupy zasobów lub subskrypcji. Zobacz Uwierzytelnianie na platformie Azure.

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.

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

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

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

W wierszu polecenia w katalogu projektu wpisz code . polecenie , aby otworzyć program 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 .
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;
```
Zapisz plik Program.cs.

Dodawanie obsługi kodu asynchronicznego

Ponieważ aplikacja używa zasobów w chmurze, kod jest uruchamiany asynchronicznie.

Zaktualizuj metodę Main , aby uruchomić asynchronicznie. Zastąp void element wartością zwracaną async Task .
```
static async Task Main(string[] args)
```
Zapisz plik Program.cs.

Utwórz kolejkę

Przed wykonaniem jakichkolwiek wywołań do interfejsów API platformy Azure należy upewnić się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano tę rolę. Po uwierzytelnieniu można utworzyć i autoryzować QueueClient obiekt przy użyciu funkcji DefaultAzureCredential uzyskiwania dostępu do danych kolejki na koncie magazynu. DefaultAzureCredential automatycznie odnajduje i używa zalogowanego konta. Aby dowiedzieć się, jak się zalogować, a następnie utworzyć QueueClient obiekt, zobacz Autoryzowanie dostępu i tworzenie obiektu klienta.

Wstawianie komunikatów do kolejki

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

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 przez wywołanie metody SendMessageAsync.
```
static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
{
    if (null != await theQueue.CreateIfNotExistsAsync())
    {
        Console.WriteLine("The queue was created.");
    }

    await theQueue.SendMessageAsync(newMessage);
}
```
Opcjonalnie: domyślnie maksymalny czas wygaśnięcia komunikatu 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 polecenia Timespan.FromSeconds(-1) w wywołaniu metody .SendMessageAsync
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
Zapisz plik.

Komunikat kolejki musi być w formacie zgodnym z żądaniem XML przy użyciu kodowania UTF-8. Komunikat może mieć rozmiar 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.

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. Po pobraniu komunikatu przy użyciu zestawu SDK w wersji 12 nie jest on automatycznie dekodowany w formacie 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;
}
```
Zapisz plik.

Usuwanie pustej kolejki

Jest to najlepsze rozwiązanie na końcu projektu, aby określić, czy nadal potrzebujesz utworzonych zasobów. Uruchomione zasoby mogą generować koszty. Jeśli kolejka istnieje, ale jest pusta, poproś użytkownika o jego usunięcie.

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

Zapisz plik.

Sprawdzanie argumentów wiersza polecenia

Jeśli do aplikacji są przekazywane jakiekolwiek 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 metodę InsertMessageAsync dodaną wcześniej.

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 zaczekaj na wprowadzenie danych wejściowych użytkownika przed wyjściem, wywołując metodę Console.ReadLine.

Rozwiń metodę Main , aby sprawdzić argumenty wiersza polecenia i poczekać na wprowadzenie danych przez użytkownika. W poniższym fragmencie kodu zastąp {storageAccountName} symbol zastępczy nazwą konta magazynu.

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

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

Skompiluj i uruchom aplikację

W wierszu polecenia w katalogu projektu uruchom następujące polecenie dotnet, aby skompilować projekt.
```
dotnet build
```
Po pomyślnym skompilowania 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..._
```
Uruchom aplikację bez argumentów wiersza polecenia, aby odbierać i usuwać pierwszy komunikat w kolejce.
```
dotnet run
```

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 tym samouczku zawarto informacje na temat wykonywania następujących czynności:

Utwórz kolejkę
Dodawanie i usuwanie komunikatów z kolejki
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 korzystające z platformy .NET w wersji 11.x.

Udostępnij za pośrednictwem