Quickstart: Azure Queue Storage-clientbibliotheek voor .NET

  • Artikel

Aan de slag met de Azure Queue Storage-clientbibliotheek voor .NET. Azure Queue Storage is een service waarmee u grote aantallen berichten kunt opslaan om later op te halen en te verwerken. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

API-referentiedocumentatie | Broncode van bibliotheek | Pakket (NuGet) | Samples

Gebruik de Azure Queue Storage-clientbibliotheek voor .NET om:

  • Een wachtrij maken
  • Berichten aan een wachtrij toevoegen
  • Berichten in een wachtrij bekijken
  • Een bericht in een wachtrij bijwerken
  • Lengte van de wachtrij ophalen
  • Berichten van een wachtrij ontvangen
  • Berichten uit een wachtrij verwijderen
  • Een wachtrij verwijderen

Vereisten

Instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Queue Storage-clientbibliotheek voor .NET.

Het project maken

Maak een .NET-toepassing met de naam QueuesQuickstart.

  1. Gebruik in een consolevenster (zoals cmd, PowerShell of Bash) de opdracht dotnet new om een nieuwe console-app te maken met de naam QueuesQuickstart. Met deze opdracht maakt u een eenvoudig 'hallo wereld' C#-project met één bronbestand met de naam Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Schakel over naar de zojuist gemaakte QueuesQuickstart map.

    cd QueuesQuickstart

De pakketten installeren

Blijf in de toepassingsmap en installeer met de opdracht dotnet add package de Azure Queue Storage-clientbibliotheek voor het .NET-pakket.

dotnet add package Azure.Storage.Queues

Het pakket met de Azure Identity-clientbibliotheek is ook nodig voor verbindingen zonder wachtwoord met Azure-services.

dotnet add package Azure.Identity

Stel het app-framework in

  1. Open het project in uw editor naar keuze
  2. Open het bestand Program.cs
  3. Werk de bestaande code bij zodat deze overeenkomt met het volgende:
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

Verifiëren bij Azure

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van wachtwoordloze verbindingen met Azure-services in uw code.

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeks s of andere referenties. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit zichtbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan worden geverifieerd. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken. Beide opties worden in het volgende voorbeeld gedemonstreerd.

DefaultAzureCredential is een klasse die wordt geleverd door de Azure Identity-clientbibliotheek voor .NET. Zie het overzicht DefaultAzureCredential voor meer DefaultAzureCredentialinformatie. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

Uw app kan bijvoorbeeld verifiëren met behulp van uw aanmeldingsreferenties voor Visual Studio bij het lokaal ontwikkelen en vervolgens een beheerde identiteit gebruiken zodra deze is geïmplementeerd in Azure. Er zijn geen codewijzigingen vereist voor deze overgang.

Wanneer u lokaal ontwikkelt, moet u ervoor zorgen dat het gebruikersaccount dat toegang heeft tot de wachtrijgegevens over de juiste machtigingen beschikt. U hebt Inzender voor opslagwachtrijgegevens nodig om wachtrijgegevens te lezen en te schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Gebruikerstoegang Beheer istrator of een andere rol met de actie Microsoft.Authorization/roleAssignments/write toegewezen krijgen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de overzichtspagina van het bereik.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Inzender voor opslagwachtrijgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot wachtrijgegevens in uw opslagaccount.

Belangrijk

In de meeste gevallen duurt het een of twee minuten voordat de roltoewijzing is doorgegeven in Azure, maar in zeldzame gevallen kan het maximaal acht minuten duren. Als u verificatiefouten ontvangt wanneer u de code voor het eerst uitvoert, wacht u even en probeert u het opnieuw.

  1. Zoek uw opslagaccount in Azure Portal met behulp van de hoofdzoekbalk of linkernavigatiebalk.

  2. Selecteer op de overzichtspagina van het opslagaccount toegangsbeheer (IAM) in het menu aan de linkerkant.

  3. Selecteer op de pagina Toegangsbeheer (IAM) het tabblad Roltoewijzingen .

  4. Selecteer + Toevoegen in het bovenste menu en voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.

A screenshot showing how to assign a role.

  1. Gebruik het zoekvak om de resultaten te filteren op de gewenste rol. In dit voorbeeld zoekt u inzender voor opslagwachtrijgegevens en selecteert u het overeenkomende resultaat en kiest u vervolgens Volgende.

  2. Selecteer onder Toegang toewijzen de optie Gebruiker, groep of service-principal en kies vervolgens + Leden selecteren.

  3. Zoek in het dialoogvenster naar uw Microsoft Entra-gebruikersnaam (meestal uw user@domain e-mailadres) en kies Vervolgens onderaan het dialoogvenster Selecteren .

  4. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

Objectmodel

Azure Queue Storage is een service om grote aantallen berichten op te slaan. Een wachtrijbericht kan maximaal 64 KB groot zijn. Een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteitslimiet van een opslagaccount. Wachtrijen worden vaak gebruikt om een voorraad werk te maken dat asynchroon moet worden verwerkt. Queue Storage biedt drie typen resources:

  • Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie overzicht van opslagaccounts voor meer informatie over opslagaccounts
  • Wachtrij: Een wachtrij bevat een set berichten. Alle berichten moeten zich in een wachtrij bevinden. De naam van een wachtrij mag alleen kleine letters bevatten. Zie Naming Queues and Metadata (Wachtrijen en metagegevens een naam geven) voor informatie over de naamgeving van wachtrijen.
  • Bericht: Een bericht in een willekeurige indeling, van maximaal 64 KB. Een bericht kan maximaal 7 dagen in de wachtrij blijven. Voor versie 29-07-2017 of hoger mag de maximale time-to-live elk positief getal zijn. Of -1 om aan te geven dat het bericht niet verloopt. Als deze parameter wordt weggelaten, is de standaard time-to-live zeven dagen.

Het volgende diagram geeft de relatie tussen deze resources weer.

Diagram of Queue storage architecture

Gebruik de volgende .NET-klassen om te communiceren met deze resources:

  • QueueServiceClient: Hiermee QueueServiceClient kunt u alle wachtrijen in uw opslagaccount beheren.
  • QueueClient: Met de QueueClient klasse kunt u een afzonderlijke wachtrij en de bijbehorende berichten beheren en bewerken.
  • QueueMessage: De QueueMessage klasse vertegenwoordigt de afzonderlijke objecten die worden geretourneerd bij het aanroepen ReceiveMessages van een wachtrij.

Codevoorbeelden

Deze voorbeeldcodefragmenten laten zien hoe u de volgende acties kunt uitvoeren met de Azure Queue Storage-clientbibliotheek voor .NET:

Toegang autoriseren en een clientobject maken

Zorg ervoor dat u voor lokale ontwikkeling bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via populaire ontwikkelhulpprogramma's, zoals de Azure CLI of Azure PowerShell. De ontwikkelhulpprogramma's waarmee u zich kunt verifiëren, variëren per taal.

Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

az login

Nadat u bent geverifieerd, kunt u een QueueClient object maken en autoriseren met behulp van DefaultAzureCredential toegang tot wachtrijgegevens in het opslagaccount. DefaultAzureCredential detecteert en gebruikt automatisch het account waarmee u zich in de vorige stap hebt aangemeld.

Als u het gebruik DefaultAzureCredentialwilt autoriseren, moet u ervoor zorgen dat u het Azure.Identity-pakket hebt toegevoegd, zoals beschreven in De pakketten installeren. Zorg er ook voor dat u een using-instructie toevoegt voor de Azure.Identity naamruimte in het bestand Program.cs :

using Azure.Identity;

Bepaal vervolgens een naam voor de wachtrij en maak een exemplaar van de QueueClient klasse met behulp van DefaultAzureCredential autorisatie. We gebruiken dit clientobject om de wachtrijresource in het opslagaccount te maken en ermee te communiceren.

Belangrijk

Wachtrijnamen mogen alleen kleine letters, cijfers en afbreekstreepjes bevatten en moeten beginnen met een letter of cijfer. Elk afbreekstreepje moet worden voorafgegaan en gevolgd door een cijfer of letter. De naam moet bovendien tussen 3 en 63 tekens lang zijn. Zie Naamgeving van wachtrijen en metagegevens voor meer informatie.

Voeg de volgende code toe aan het einde van het bestand Program.cs . Zorg ervoor dat u de waarde van de <storage-account-name> tijdelijke aanduiding vervangt:

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

Notitie

Berichten die met de QueueClient klasse worden verzonden, moeten een indeling hebben die kan worden opgenomen in een XML-aanvraag met UTF-8-codering. U kunt desgewenst de optie MessageEncoding instellen op Base64 om niet-compatibele berichten te verwerken.

Een wachtrij maken

Roep met behulp van het QueueClient object de CreateAsync methode aan om de wachtrij in uw opslagaccount te maken.

Voeg deze code toe aan het einde van de methode Program.cs :

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

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

Berichten aan een wachtrij toevoegen

Met het volgende codefragment worden berichten asynchroon aan de wachtrij toegevoegd door de methode SendMessageAsync aan te roepen. Ook wordt een SendReceipt opgeslagen die met een SendMessageAsync-aanroep wordt geretourneerd. Het resultaat wordt gebruikt om het bericht later in het programma bij te werken.

Voeg deze code toe aan het einde van het bestand Program.cs :

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

Berichten in een wachtrij bekijken

Bekijk de berichten in de wachtrij door de methode PeekMessagesAsync aan te roepen. Met deze methode worden één of meer berichten vooraan in de wachtrij opgehaald, maar wordt de zichtbaarheid van het bericht niet gewijzigd.

Voeg deze code toe aan het einde van het bestand Program.cs :

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

Een bericht in een wachtrij bijwerken

Werk de inhoud van een bericht bij door de methode UpdateMessageAsync aan te roepen. Deze methode kan de time-out voor zichtbaarheid en de inhoud van een bericht wijzigen. De inhoud van het bericht moet een UTF-8-gecodeerde tekenreeks zijn die maximaal 64 KB groot is. Geef behalve de nieuwe inhoud voor het bericht ook de waarden uit de SendReceipt door die eerder in de code waren opgeslagen. De SendReceipt-waarden identificeren welk bericht moet worden bijgewerkt.

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

Lengte van de wachtrij ophalen

U kunt een schatting ophalen van het aantal berichten in de wachtrij. De GetProperties methode retourneert wachtrijeigenschappen, inclusief het aantal berichten. De ApproximateMessagesCount eigenschap bevat het geschatte aantal berichten in de wachtrij. Dit aantal is niet lager dan het werkelijke aantal berichten in de wachtrij, maar kan hoger zijn.

Voeg deze code toe aan het einde van het bestand Program.cs :

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

Berichten van een wachtrij ontvangen

Download eerder toegevoegde berichten door de methode ReceiveMessagesAsync aan te roepen.

Voeg deze code toe aan het einde van het bestand Program.cs :

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

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

U kunt desgewenst een waarde opgeven voor maxMessages, wat het aantal berichten is dat uit de wachtrij moet worden opgehaald. De standaardwaarde is 1 bericht en het maximum is 32 berichten. U kunt ook een waarde opgeven waarvoor visibilityTimeoutde berichten voor de time-outperiode worden verborgen voor andere bewerkingen. De standaardwaarde is 30 seconden.

Berichten uit een wachtrij verwijderen

Verwijder berichten uit de wachtrij nadat ze zijn verwerkt. In dit geval betekent ‘verwerken’ gewoon dat het bericht wordt weergegeven in de console.

De app pauzeert voor gebruikersinvoer door Console.ReadLine aan te roepen voordat deze de berichten verwerkt en verwijdert. Verifieer in uw Azure-portal dat de resources correct zijn gemaakt, voordat ze worden verwijderd. Berichten die niet expliciet worden verwijderd, worden uiteindelijk weer zichtbaar in de wachtrij voor een andere kans om ze te verwerken.

Voeg deze code toe aan het einde van het bestand Program.cs :

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

Een wachtrij verwijderen

Met de volgende code worden de resources opgeschoond die met de app zijn gemaakt, door de wachtrij te verwijderen met de methode DeleteAsync.

Voeg deze code toe aan het einde van het bestand Program.cs :

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

De code uitvoeren

Met deze app worden drie berichten gemaakt en aan een Azure-wachtrij toegevoegd. De code toont de berichten in de wachtrij, haalt ze op en verwijdert ze, en verwijdert uiteindelijk de wachtrij.

Navigeer in uw consolevenster naar de toepassingsmap, bouw de toepassing en voer deze uit.

dotnet build

dotnet run

De uitvoer van de app lijkt op die in het volgende voorbeeld:

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

Wanneer de app pauzeert voordat deze berichten ontvangt, controleert u uw opslagaccount in de Azure-portal. Verifieer dat de berichten in de wachtrij staan.

Druk op de Enter toets om de berichten te ontvangen en te verwijderen. Wanneer u hierom wordt gevraagd, drukt u nogmaals op de Enter toets om de wachtrij te verwijderen en de demo te voltooien.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een wachtrij maakt en berichten eraan toevoegt met behulp van asynchrone .NET-code. Vervolgens leerde u hoe u berichten kunt bekijken, ophalen en verwijderen. Tot slot leerde u hoe u een berichtenwachtrij verwijdert.

Voor zelfstudies, voorbeelden, quickstarts en andere documentatie gaat u naar:

Azure voor ontwikkelaars van .NET en .NET Core