Tutorial: Arbeiten mit Azure Queue Storage-Warteschlangen in .NET

Artikel
04/28/2023

Azure Queue Storage implementiert cloudbasierte Warteschlangen, um eine Kommunikation zwischen Komponenten einer verteilten Anwendung zu ermöglichen. Jede Warteschlange verwaltet eine Liste von Nachrichten, die von einer Absenderkomponente hinzugefügt und einer Empfängerkomponente verarbeitet werden kann. Bei einer Warteschlange kann Ihre Anwendung entsprechend den Anforderungen sofort skaliert werden. In diesem Artikel werden die grundlegenden Schritte zum Arbeiten mit einer Azure Queue Storage-Warteschlange gezeigt.

In diesem Tutorial lernen Sie Folgendes:

Erstellen eines Azure-Speicherkontos
Erstellen der App
Hinzufügen der Azure-Clientbibliotheken
Hinzufügen von Unterstützung für asynchronen Code
Erstellen einer Warteschlange
Einfügen von Nachrichten in eine Warteschlange
Entfernen von Nachrichten aus Warteschlangen
Löschen einer leeren Warteschlange
Überprüfen auf Befehlszeilenargumente
Erstellen und Ausführen der App

Voraussetzungen

Laden Sie Ihre kostenlose Kopie des plattformübergreifenden Visual Studio Code-Editors herunter.
Laden Sie die .NET Core SDK-Version 3.1 oder höher herunter, und installieren Sie sie.
Wenn Sie über kein aktuelles Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.

Erstellen eines Azure-Speicherkontos

Erstellen Sie zuerst ein Azure-Speicherkonto. Eine schrittweise Anleitung zum Erstellen eines Speicherkontos finden Sie im Schnellstart Erstellen eines Speicherkontos. Dies ist ein separater Schritt, den Sie nach dem Erstellen eines kostenlosen Azure-Kontos in den Voraussetzungen ausführen.

Erstellen der App

Erstellen Sie eine .NET Core-Anwendung mit dem Namen QueueApp. Der Einfachheit halber wird diese App Nachrichten über die Warteschlange sowohl senden als auch empfangen.

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Azure CLI) den Befehl dotnet new zum Erstellen der neuen Konsolen-App QueueApp. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit der einzigen Quelldatei Program.cs.
```
dotnet new console -n QueueApp
```

Wechseln Sie zum neu erstellten Ordner QueueApp, und erstellen Sie die App, um sich zu vergewissern, dass alles funktioniert hat.

cd QueueApp

dotnet build

Die Ergebnisse sollten in etwa wie in der folgenden Ausgabe aussehen:

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

Hinzufügen der Azure-Clientbibliotheken

Fügen Sie dem Projekt mit dem Befehl dotnet add package die Azure Storage Client-Bibliotheken hinzu.

Führen Sie den folgenden Befehl aus dem Projektordner im Konsolenfenster aus.
```
dotnet add package Azure.Storage.Queues
```

Hinzufügen mit Anweisungen

Geben Sie in der Befehlszeile im Projektverzeichnis code . ein, um Visual Studio Code im aktuellen Verzeichnis zu öffnen. Lassen Sie das Befehlszeilenfenster geöffnet. Später müssen darin noch weitere Befehle ausgeführt werden. Wenn Sie zum Hinzufügen von C#-Ressourcen aufgefordert werden, die zum Erstellen und Debuggen erforderlich sind, klicken Sie auf die Schaltfläche Ja.
Öffnen Sie die Quelldatei Program.cs, und fügen Sie die folgenden Namespaces direkt nach der Anweisung using System; hinzu. Diese App verwendet Typen aus diesen Namespaces zum Herstellen einer Verbindung mit Azure Storage und zum Arbeiten mit Warteschlangen.
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
Speichern Sie die Datei Program.cs.

Hinzufügen von Unterstützung für asynchronen Code

Da die App Cloud-Ressourcen verwendet, wird der Code asynchron ausgeführt.

Aktualisieren Sie die Methode Main, damit sie asynchron ausgeführt wird. Ersetzen Sie void durch einen Rückgabewert von async Task.
```
static async Task Main(string[] args)
```
Speichern Sie die Datei Program.cs.

Erstellen einer Warteschlange

Bevor Sie Aufrufe in Azure-APIs ausführen, müssen Sie Ihre Anmeldeinformationen aus dem Azure-Portal abrufen.

Kopieren Ihrer Anmeldeinformationen aus dem Azure-Portal

Wenn die Beispielanwendung eine Anforderung an Azure Storage sendet, muss diese autorisiert werden. Fügen Sie zum Autorisieren einer Anforderung die Anmeldeinformationen für Ihr Speicherkonto in Form einer Verbindungszeichenfolge hinzu. Führen Sie zum Anzeigen der Anmeldeinformationen Ihres Speicherkontos die folgenden Schritte aus:

Melden Sie sich beim Azure-Portal an.
Suchen Sie nach Ihrem Speicherkonto.
Wählen Sie im Speicherkonto-Menübereich unter Sicherheit + Netzwerkbetrieb die Option Zugriffsschlüssel aus. Hier können Sie die Kontozugriffsschlüssel und die vollständige Verbindungszeichenfolge für jeden Schlüssel anzeigen.
Wählen Sie im Bereich Zugriffsschlüssel die Option Schlüssel anzeigen aus.
Suchen Sie im Abschnitt key1 nach dem Wert Verbindungszeichenfolge. Wählen Sie das Symbol In Zwischenablage kopieren zum Kopieren der Verbindungszeichenfolge aus. Im nächsten Abschnitt fügen Sie den Wert der Verbindungszeichenfolge in eine Umgebungsvariable ein.

Konfigurieren der Speicherverbindungszeichenfolge

Schreiben Sie die Verbindungszeichenfolge nach dem Kopieren in eine neue Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird. Öffnen Sie zum Festlegen der Umgebungsvariablen ein Konsolenfenster, und befolgen Sie die Anleitung für Ihr Betriebssystem. Ersetzen Sie <yourconnectionstring> durch Ihre Verbindungszeichenfolge.

Windows
Linux und macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Sie müssen nach dem Hinzufügen der Umgebungsvariablen unter Windows eine neue Instanz des Befehlsfensters öffnen.

Neustarten von Programmen

Nachdem Sie die Umgebungsvariable hinzugefügt haben, starten Sie alle ausgeführten Programme neu, in denen die Umgebungsvariable gelesen werden muss. Starten Sie beispielsweise die Entwicklungsumgebung oder den Editor neu, bevor Sie fortfahren.

Hinzufügen der Verbindungszeichenfolge zur App

Fügen Sie die Verbindungszeichenfolge in die App ein, damit sie auf das Speicherkonto zugreifen kann.

Wechseln Sie zurück zu Visual Studio Code.
Ersetzen Sie in der Methode Main den Code Console.WriteLine("Hello, World"); durch die folgende Zeile, die die Verbindungszeichenfolge aus der Umgebungsvariablen abruft.
```
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
```
Fügen Sie Main den folgenden Code zum Erstellen eines Warteschlangenobjekts hinzu, das später an die Methoden zum Senden und Empfangen übergeben wird.
```
QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
```
Speichern Sie die Datei .

Einfügen von Nachrichten in die Warteschlange

Erstellen Sie eine neue Methode zum Senden einer Nachricht in die Warteschlange.

Fügen Sie Ihrer Klasse Program die folgende InsertMessageAsync-Methode hinzu.

Dieser Methode wird ein Warteschlangenverweis übergeben. Wenn sie nicht bereits vorhanden ist, wird durch Aufrufen von CreateIfNotExistsAsync eine neue Warteschlange erstellt. Anschließend fügt sie der Warteschlange durch Aufrufen von SendMessageAsync die newMessage hinzu.
```
static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
{
    if (null != await theQueue.CreateIfNotExistsAsync())
    {
        Console.WriteLine("The queue was created.");
    }

    await theQueue.SendMessageAsync(newMessage);
}
```
Optional: Die maximale Gültigkeitsdauer für eine Nachricht wird standardmäßig auf sieben Tage festgelegt. Sie können für die Gültigkeitsdauer der Nachricht eine beliebige positive Zahl angeben. Der folgende Codeausschnitt fügt eine Nachricht hinzu, die nie abläuft.

Zum Hinzufügen einer Nachricht, die nicht abläuft, geben Sie in Ihrem Aufruf von SendMessageAsync den Wert Timespan.FromSeconds(-1) an.
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
Speichern Sie die Datei .

Eine Warteschlangennachricht muss in einem Format vorliegen, das mit einer XML-Anforderung mit UTF-8-Codierung kompatibel ist. Eine Nachricht kann bis zu 64 KB groß sein. Wenn eine Nachricht Binärdaten enthält, codieren Sie die Nachricht mit Base64-encode.

Entfernen von Nachrichten aus Warteschlangen

Erstellen Sie eine neue Methode zum Abrufen einer Nachricht aus der Warteschlange. Sobald die Nachricht erfolgreich empfangen wurde, muss sie aus der Warteschlange gelöscht werden, damit sie nicht mehrmals verarbeitet wird.

Fügen Sie Ihrer Program-Klasse die neue Methode RetrieveNextMessageAsync hinzu.

Diese Methode empfängt durch Aufrufen von ReceiveMessagesAsync eine Nachricht aus der Warteschlange. Dabei wird im ersten Parameter der Wert 1 zum Abrufen nur der nächsten Nachricht in der Warteschlange übergeben. Löschen Sie die empfangene Nachricht durch Aufrufen von DeleteMessageAsync aus der Warteschlange.

Wenn eine Nachricht mit einer niedrigeren Version des SDK als v12 an die Warteschlange gesendet wird, wird Sie automatisch Base64-codiert. Ab v12 wurde diese Funktion entfernt. Wenn Sie eine Nachricht mit dem v12-SDK abrufen, wird diese nicht automatisch Base64-decodiert. Sie müssen den Inhalt selbst explizit Base64-decodieren.
```
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;
}
```
Speichern Sie die Datei .

Löschen einer leeren Warteschlange

Es empfiehlt sich, am Ende eines Projekts zu ermitteln, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Wenn die Warteschlange noch vorhanden, aber leer ist, fragen Sie den Benutzer, ob sie gelöscht werden soll.

Erweitern Sie die Methode RetrieveNextMessageAsync, um eine Aufforderung zum Löschen der leeren Warteschlange einzubeziehen.

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

Speichern Sie die Datei .

Überprüfen auf Befehlszeilenargumente

Wenn es irgendwelche Befehlszeilenargumente gibt, die an die App übergeben werden, stellen Sie sich vor, dass es sich dabei um eine Nachricht handelt, die der Warteschlange hinzugefügt werden muss. Verknüpfen Sie die Argumente zu einer Zeichenfolge. Fügen Sie diese Zeichenfolge durch Aufrufen der zuvor hinzugefügten Methode InsertMessageAsync der Nachrichtenwarteschlange hinzu.

Wenn es keine Befehlszeilenargumente gibt, versuchen Sie es mit einem Abrufvorgang. Rufen Sie die Methode RetrieveNextMessageAsync zum Abrufen der nächsten Nachricht in der Warteschlange auf.

Warten Sie schließlich auf die Benutzereingabe, bevor Sie den Vorgang durch Aufrufen von Console.ReadLine beenden.

Erweitern Sie die Methode Main, um auf Befehlszeilenargumente zu überprüfen und auf die Benutzereingabe zu warten.

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

Speichern Sie die Datei .

Vollständiger Code

Hier ist die vollständige Codeauflistung für dieses Projekt.

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

Erstellen und Ausführen der App

Führen Sie über die Befehlszeile im Projektverzeichnis den folgenden dotnet-Befehl zum Erstellen des Projekts aus.
```
dotnet build
```
Nachdem das Projekt erfolgreich erstellt wurde, führen Sie den folgenden Befehl aus, um der Warteschlange die erste Nachricht hinzuzufügen.
```
dotnet run First queue message
```
Die folgende Ausgabe sollte angezeigt werden:
```
C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter..._
```
Führen Sie die App ohne Befehlszeilenargumente aus, um die erste Nachricht in der Warteschlange zu empfangen und zu entfernen.
```
dotnet run
```

Setzen Sie die Ausführung der App fort, bis alle Nachrichten entfernt wurden. Wenn Sie sie dann noch einmal ausführen, wird eine Meldung, dass die Warteschlange leer ist, und eine Aufforderung zum Löschen der Warteschlange angezeigt.

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

Nächste Schritte

In diesem Tutorial haben Sie Folgendes gelernt:

Erstellen einer Warteschlange
Hinzufügen und Entfernen von Nachrichten zu bzw. aus einer Warteschlange
Löschen einer Azure Queue Storage-Warteschlange

In den Schnellstarts zu Azure Queue Storage finden Sie weitere Informationen.

Warteschlangen – Schnellstart für das Portal

Verwandte Code-Beispiele mithilfe veralteter SDKs der .NET-Version 11.x finden Sie unter Code-Beispiele mithilfe der .NET-Version 11.x.