Schnellstart: Azure Queue Storage-Clientbibliothek für .NET

Erste Schritte mit der Azure Queue Storage-Clientbibliothek für .NET. Azure Queue Storage ist ein Dienst zum Speichern einer großen Anzahl von Nachrichten, die später abgerufen und verarbeitet werden. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | Beispiele

Mit der Azure Queue Storage-Clientbibliothek für .NET können Sie Folgendes ausführen:

• Erstellen einer Warteschlange
• Hinzufügen von Nachrichten zu einer Warteschlange
• Einsehen von Nachrichten in einer Warteschlange
• Aktualisieren einer Nachricht in einer Warteschlange
• Abrufen der Warteschlangenlänge
• Empfangen von Nachrichten aus einer Warteschlange
• Löschen von Nachrichten aus einer Warteschlange
• Löschen einer Warteschlange

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Azure Storage-Konto – Erstellen eines Speicherkontos
• Aktuelles .NET SDK für Ihr Betriebssystem. Laden Sie unbedingt das SDK und nicht die Runtime herunter.

Einrichten

In diesem Abschnitt wird beschrieben, wie Sie ein Projekt zum Arbeiten mit der Azure Queue Storage-Clientbibliothek für .NET vorbereiten.

Erstellen des Projekts

Erstellen einer .NET-Anwendung namens QueuesQuickstart.

1. Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen QueuesQuickstart. Dieser Befehl erstellt ein einfaches C#-Projekt vom Typ „Hallo Welt“ mit einer einzelnen Quelldatei namens program.cs.

   dotnet new console -n QueuesQuickstart
   

2. Wechseln Sie zum neu erstellten Verzeichnis QueuesQuickstart.

   cd QueuesQuickstart
   

Installieren der Pakete

Installieren Sie im Anwendungsverzeichnis mit dem Befehl dotnet add package das Paket für die Azure Queue Storage-Clientbibliothek für .NET.

dotnet add package Azure.Storage.Queues

Das Azure Identity-Clientbibliothekspaket wird auch für kennwortlose Verbindungen mit Azure-Diensten benötigt.

dotnet add package Azure.Identity

Einrichten des App-Frameworks

1. Öffnen Sie das Projekt im Editor Ihrer Wahl.
2. Öffnen Sie die Datei Program.cs.
3. Aktualisieren Sie den vorhandenen Code wie folgt:

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

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

Für Azure authentifizieren

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Die Verwendung der von der Azure Identity-Clientbibliothek bereitgestellten Klasse DefaultAzureCredential ist der empfohlene Ansatz zum Implementieren von kennwortlosen Verbindungen mit Azure-Diensten in Ihrem Code.

Anforderungen an Azure-Dienste können auch direkt mithilfe von Kennwörtern, Verbindungszeichenfolgen oder anderen Anmeldeinformationen autorisiert werden. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass diese Geheimnisse nicht an einem unsicheren Ort offengelegt werden. Jeder Benutzer, der Zugriff auf das Kennwort oder auf den geheimen Schlüssel erlangt, kann sich damit authentifizieren. DefaultAzureCredential bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um kennwortlose Authentifizierung zu ermöglichen. Beide Optionen werden im folgenden Beispiel veranschaulicht.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Objektmodell

Azure Queue Storage ist ein Dienst für die Speicherung großer Nachrichtenmengen. Eine Warteschlangennachricht kann bis zu 64 KB groß sein. Eine Warteschlange kann Millionen Nachrichten enthalten, bis die maximale Kapazität eines Speicherkontos erreicht ist. Warteschlangen werden häufig verwendet, um ein Arbeits-Backlog zur asynchronen Verarbeitung zu erstellen. Queue Storage bietet drei Arten von Ressourcen:

• Speicherkonto:Alle Zugriffe auf den Azure-Speicher erfolgen über ein Speicherkonto. Weitere Informationen zu Speicherkonten finden Sie in der Speicherkontoübersicht
• Warteschlange: Eine Warteschlange enthält einen Satz von Nachrichten. Alle Nachrichten müssen sich in Warteschlangen befinden. Beachten Sie, dass der Warteschlangenname nur aus Kleinbuchstaben bestehen darf. Informationen zum Benennen von Warteschlangen finden Sie unter Benennen von Warteschlangen und Metadaten.
• Nachricht: Eine Nachricht in einem beliebigen Format und mit einer Größe von bis zu 64 KB. Eine Nachricht kann maximal 7 Tage in der Warteschlange verbleiben. Für Version 2017-07-29 oder höhere Versionen kann die maximale Gültigkeitsdauer eine beliebige positive Zahl sein. Mit -1 wird angegeben, dass die Nachricht nicht abläuft. Wird dieser Parameter ausgelassen, beträgt die Standardgültigkeitsdauer sieben Tage.

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.

Verwenden Sie die folgenden .NET-Klassen zur Interaktion mit folgenden Ressourcen:

• QueueServiceClient: Mit dem QueueServiceClient können Sie alle Warteschlangen in Ihrem Speicherkonto verwalten.
• QueueClient: Mit der QueueClient-Klasse können Sie eine einzelne Warteschlange und die darin enthaltenen Nachrichten verwalten und bearbeiten.
• QueueMessage: Die QueueMessage-Klasse repräsentiert die einzelnen Objekte, die beim Aufrufen von ReceiveMessages in einer Warteschlange zurückgegeben werden.

Codebeispiele

Diese Beispielcodeausschnitte zeigen Ihnen, wie folgende Aktionen mit der Azure Queue Storage-Clientbibliothek für .NET ausgeführt werden:

• Autorisieren des Zugriffs und Erstellen eines Clientobjekts
• Erstellen einer Warteschlange
• Hinzufügen von Nachrichten zu einer Warteschlange
• Einsehen von Nachrichten in einer Warteschlange
• Aktualisieren einer Nachricht in einer Warteschlange
• Abrufen der Warteschlangenlänge
• Empfangen von Nachrichten aus einer Warteschlange
• Löschen von Nachrichten aus einer Warteschlange
• Löschen einer Warteschlange

az login

az login

Connect-AzAccount

using Azure.Identity;

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

// 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 unique name for the queue
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(connectionString, queueName);

Erstellen einer Warteschlange

Rufen Sie dann mithilfe des QueueClient-Objekts die CreateAsync-Methode auf, um die Warteschlange in Ihrem Speicherkonto zu erstellen.

Fügen Sie am Ende der Methode Program.cs folgenden Code hinzu:

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

Hinzufügen von Nachrichten zu einer Warteschlange

Der folgende Codeausschnitt fügt der Warteschlange Nachrichten durch Aufrufen der SendMessageAsync-Methode asynchron hinzu. Außerdem wird ein von einem SendMessageAsync-Aufruf zurückgegebenes SendReceipt gespeichert. Die Bestätigung wird später im Programm zum Aktualisieren der Nachricht verwendet.

Fügen Sie am Ende der Datei Program.cs folgenden Code hinzu:

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

Einsehen von Nachrichten in einer Warteschlange

Durch Aufrufen der PeekMessagesAsync-Methode können Sie die Nachrichten in der Warteschlange einsehen. Diese Methode ruft mindestens eine Nachricht vom Anfang der Warteschlange ab, ändert aber nicht die Sichtbarkeit der Nachricht.

Fügen Sie am Ende der Datei Program.cs folgenden Code hinzu:

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

Aktualisieren einer Nachricht in einer Warteschlange

Aktualisieren Sie den Inhalt einer Nachricht durch Aufrufen der UpdateMessageAsync-Methode. Diese Methode kann das Sichtbarkeitstimeout und den Inhalt einer Nachricht ändern. Beim Nachrichteninhalt muss es sich um eine UTF-8-codierte Zeichenfolge handeln, die bis zu 64 KB groß sein darf. Übergeben Sie zusammen mit dem neuen Inhalt für die Nachricht Werte aus dem SendReceipt, das weiter oben im Code gespeichert wurde. Die SendReceipt-Werte identifizieren die Nachricht, die aktualisiert werden soll.

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

Abrufen der Warteschlangenlänge

Sie können die Anzahl der Nachrichten in einer Warteschlange schätzen lassen. Die Methode GetProperties gibt Warteschlangeneigenschaften einschließlich der Nachrichtenanzahl zurück. Die ApproximateMessagesCount-Eigenschaft enthält die ungefähre Anzahl der Nachrichten in der Warteschlange. Diese Anzahl ist nicht kleiner als die tatsächliche Anzahl der Nachrichten in der Warteschlange, kann aber größer sein.

Fügen Sie am Ende der Datei Program.cs folgenden Code hinzu:

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

Empfangen von Nachrichten aus einer Warteschlange

Laden Sie zuvor hinzugefügte Nachrichten durch Aufrufen der ReceiveMessagesAsync-Methode herunter.

Fügen Sie am Ende der Datei Program.cs folgenden Code hinzu:

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

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

Sie können optional einen Wert für maxMessages angeben, der die Anzahl der Nachrichten darstellt, die aus der Warteschlange abgerufen werden sollen. Der Standardwert ist „1 Nachricht“, und der Höchstwert ist „32 Nachrichten“. Sie können auch einen Wert für visibilityTimeout angeben, wodurch die Nachrichten für den Timeoutzeitraum vor anderen Vorgängen ausgeblendet werden. Der Standardwert ist 30 Sekunden.

Löschen von Nachrichten aus einer Warteschlange

Löschen Sie Nachrichten aus der Warteschlange, nachdem sie verarbeitet wurden. In diesem Fall besteht die Verarbeitung nur darin, dass die Nachricht in der Konsole angezeigt wird.

Die App wird angehalten und wartet auf Benutzereingaben, indem Console.ReadLine aufgerufen wird, bevor die Nachrichten verarbeitet und gelöscht werden. Überprüfen Sie im Azure-Portal, ob die Ressourcen ordnungsgemäß erstellt wurden, bevor sie gelöscht werden. Alle Nachrichten, die nicht explizit gelöscht werden, werden schlussendlich wieder in der Warteschlange angezeigt und ggf. erneut verarbeitet.

Fügen Sie am Ende der Datei Program.cs folgenden Code hinzu:

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

Löschen einer Warteschlange

Der folgende Code bereinigt die von der App erstellten Ressourcen, indem die Warteschlange mithilfe der DeleteAsync-Methode gelöscht wird.

Fügen Sie am Ende der Datei Program.cs folgenden Code hinzu:

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

Ausführen des Codes

Diese App erstellt drei Nachrichten und fügt sie einer Azure-Warteschlange hinzu. Der Code listet die Nachrichten in der Warteschlange auf, ruft sie ab und löscht sie, bevor er letztendlich die Warteschlange löscht.

Navigieren Sie im Konsolenfenster zu Ihrem Anwendungsverzeichnis, erstellen Sie die Anwendung, und führen Sie sie aus.

dotnet build

dotnet run

Die Ausgabe der App sieht etwa wie das folgende Beispiel aus:

Azure Queue Storage client library - .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

Wenn die App vor dem Empfangen von Nachrichten angehalten wird, überprüfen Sie Ihr Speicherkonto im Azure-Portal. Überprüfen Sie, ob sich in der Warteschlange Nachrichten befinden.

Drücken Sie die Enter, um Nachrichten zu empfangen und zu löschen. Wenn Sie dazu aufgefordert werden, drücken Sie erneut die Enter, um die Warteschlange zu löschen und die Demo zu beenden.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie gelernt, wie Sie mithilfe von asynchronem .NET-Code eine Warteschlange erstellen und dieser Nachrichten hinzufügen. Danach haben Sie erfahren, wie Sie Nachrichten einsehen, abrufen und löschen. Zum Schluss haben Sie gelernt, wie Sie eine Nachrichtenwarteschlange löschen.

Tutorials, Beispiele, Schnellstartanleitungen und weiteres Dokumentationsmaterial finden Sie hier:

• Verwandte Code-Beispiele mithilfe veralteter SDKs der .NET-Version 11.x finden Sie unter Code-Beispiele mithilfe der .NET-Version 11.x.
• Weitere Informationen finden Sie unter Azure Storage libraries for .NET (Azure Storage-Bibliotheken für .NET).
• Weitere Informationen zu Azure Queue Storage-Beispiel-Apps finden Sie unter Azure Queue Storage-Clientbibliothek v12 für .NET – Beispiele.
• Weitere Informationen zu .NET Core finden Sie unter Get started with .NET in 10 minutes (Einstieg in .NET in 10 Minuten).