Snabbstart: Azure Queue Storage-klientbibliotek för .NET

Kom igång med Azure Queue Storage-klientbiblioteket för .NET. Azure Queue Storage är en tjänst för lagring av ett stort antal meddelanden för senare hämtning och bearbetning. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

API-referensdokumentation NuGet-exempel (Library source code | Package) | |

Använd Azure Queue Storage-klientbiblioteket för .NET för att:

• Skapa en kö
• Lägga till meddelanden i en kö
• Titta på meddelanden i en kö
• Uppdatera ett meddelande i en kö
• Hämta kölängden
• Ta emot meddelanden från en kö
• Ta bort meddelanden från en kö
• Ta bort en kö

Förutsättningar

• Azure-prenumeration – skapa en kostnadsfritt
• Azure Storage-konto – skapa ett lagringskonto
• Aktuell .NET SDK för operativsystemet. Se till att hämta SDK:et och inte körningen.

Konfigurera

Det här avsnittet beskriver hur du förbereder ett projekt för att arbeta med Azure Queue Storage-klientbiblioteket för .NET.

Skapa projektet

Skapa ett .NET-program med namnet QueuesQuickstart.

1. I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet new kommandot för att skapa en ny konsolapp med namnet QueuesQuickstart. Det här kommandot skapar ett enkelt "hello world"-C#-projekt med en enda källfil med namnet Program.cs.

   dotnet new console -n QueuesQuickstart
   

2. Växla till den nyligen skapade QueuesQuickstart katalogen.

   cd QueuesQuickstart
   

Installera paketen

Installera Azure Queue Storage-klientbiblioteket för .NET-paketet medan du fortfarande är i programkatalogen dotnet add package med hjälp av kommandot .

dotnet add package Azure.Storage.Queues

Azure Identity-klientbibliotekspaketet behövs också för lösenordslösa anslutningar till Azure-tjänster.

dotnet add package Azure.Identity

Konfigurera appramverket

1. Öppna projektet i valfri redigerare
2. Öppna filen Program.cs
3. Uppdatera den befintliga koden så att den matchar följande:

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

Autentisera till Azure

Programbegäranden till de flesta Azure-tjänster måste auktoriseras. Att använda klassen DefaultAzureCredential som tillhandahålls av Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i din kod.

Du kan också auktorisera begäranden till Azure-tjänster med hjälp av lösenord, anslutningssträng eller andra autentiseringsuppgifter direkt. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera dessa hemligheter på en osäker plats. Alla som får åtkomst till lösenordet eller den hemliga nyckeln kan autentisera sig. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordslös autentisering. Båda alternativen visas i följande exempel.

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 är en tjänst för lagring av ett stort antal meddelanden. Ett kömeddelande kan vara upp till 64 KB stort. En kö kan innehålla miljontals meddelanden, upp till den totala kapacitetsgränsen för ett lagringskonto. Köer används ofta för att skapa en kvarvarande arbetslogg för att bearbeta asynkront. Queue Storage erbjuder tre typer av resurser:

• Lagringskonto: All åtkomst till Azure Storage görs via ett lagringskonto. Mer information om lagringskonton finns i Översikt över lagringskonto
• Kö: en kö innehåller en uppsättning meddelanden. Alla meddelanden måste vara i en kö. Observera att könamnet måste vara helt i gemener. Mer information om namngivning av köer finns i namngivning av köer och metadata.
• Meddelande: ett meddelande i valfritt format, som är upp till 64 KB. Ett meddelande kan finnas kvar i kön i högst 7 dagar. För version 2017-07-29 eller senare kan den maximala tiden till live vara ett positivt tal, eller -1 som anger att meddelandet inte upphör att gälla. Om den här parametern utelämnas är standardtiden till live sju dagar.

Följande diagram visar relationen mellan de här resurserna.

Använd följande .NET-klasser för att interagera med dessa resurser:

• QueueServiceClientQueueServiceClient: Gör att du kan hantera alla köer i ditt lagringskonto.
• QueueClient: Med QueueClient klassen kan du hantera och ändra en enskild kö och dess meddelanden.
• QueueMessage: Klassen QueueMessage representerar de enskilda objekt som returneras när de anropas ReceiveMessages i en kö.

Kodexempel

Dessa exempelkodfragment visar hur du utför följande åtgärder med Azure Queue Storage-klientbiblioteket för .NET:

• Auktorisera åtkomst och skapa ett klientobjekt
• Skapa en kö
• Lägga till meddelanden i en kö
• Titta på meddelanden i en kö
• Uppdatera ett meddelande i en kö
• Hämta kölängden
• Ta emot meddelanden från en kö
• Ta bort meddelanden från en kö
• Ta bort en kö

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

Skapa en kö

Med hjälp av QueueClient objektet anropar du CreateAsync metoden för att skapa kön i ditt lagringskonto.

Lägg till den här koden i slutet av metoden Program.cs :

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

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

Lägga till meddelanden i en kö

Följande kodfragment lägger asynkront till meddelanden i kön genom att anropa SendMessageAsync metoden. Det sparar också en SendReceipt returnerad från ett SendMessageAsync anrop. Kvittot används för att uppdatera meddelandet senare i programmet.

Lägg till den här koden i slutet av Filen 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");

Titta på meddelanden i en kö

Titta på meddelandena i kön genom att anropa PeekMessagesAsync metoden. Den här metoden hämtar ett eller flera meddelanden längst fram i kön, men ändrar inte meddelandets synlighet.

Lägg till den här koden i slutet av Filen 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}");
}

Uppdatera ett meddelande i en kö

Uppdatera innehållet i ett meddelande genom att anropa UpdateMessageAsync metoden. Den här metoden kan ändra ett meddelandes tidsgräns för synlighet och innehåll. Meddelandeinnehållet måste vara en UTF-8-kodad sträng som är upp till 64 KB stor. Tillsammans med det nya innehållet för meddelandet skickar du in värdena från SendReceipt det som sparades tidigare i koden. Värdena SendReceipt identifierar vilket meddelande som ska uppdateras.

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

Hämta kölängden

Du kan hämta en uppskattning av antalet meddelanden i en kö. Metoden GetProperties returnerar köegenskaper inklusive antalet meddelanden. Egenskapen ApproximateMessagesCount innehåller det ungefärliga antalet meddelanden i kön. Det här talet är inte lägre än det faktiska antalet meddelanden i kön, men kan vara högre.

Lägg till den här koden i slutet av Filen 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}");

Ta emot meddelanden från en kö

Ladda ned tidigare tillagda meddelanden genom att anropa ReceiveMessagesAsync metoden.

Lägg till den här koden i slutet av Filen Program.cs :

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

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

Du kan också ange ett värde för maxMessages, vilket är antalet meddelanden som ska hämtas från kön. Standardvärdet är 1 meddelande och det maximala är 32 meddelanden. Du kan också ange ett värde för visibilityTimeout, som döljer meddelandena från andra åtgärder under tidsgränsperioden. Standardvärdet är 30 sekunder.

Ta bort meddelanden från en kö

Ta bort meddelanden från kön när de har bearbetats. I det här fallet visar bearbetningen bara meddelandet i konsolen.

Appen pausar för användarindata genom att anropa Console.ReadLine innan den bearbetar och tar bort meddelandena. Kontrollera i Azure-portalen att resurserna har skapats korrekt innan de tas bort. Meddelanden som inte uttryckligen tas bort visas så småningom i kön igen för en ny chans att bearbeta dem.

Lägg till den här koden i slutet av Filen 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);
}

Ta bort en kö

Följande kod rensar de resurser som appen skapade genom att ta bort kön med hjälp av DeleteAsync metoden .

Lägg till den här koden i slutet av Filen 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");

Kör koden

Den här appen skapar och lägger till tre meddelanden i en Azure-kö. Koden visar meddelandena i kön och hämtar och tar sedan bort dem innan du slutligen tar bort kön.

I konsolfönstret navigerar du till programkatalogen och skapar och kör sedan programmet.

dotnet build

dotnet run

Utdata från appen liknar följande exempel:

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

När appen pausar innan du tar emot meddelanden kontrollerar du ditt lagringskonto i Azure-portalen. Kontrollera att meddelandena finns i kön.

Tryck på tangenten Enter för att ta emot och ta bort meddelandena. När du uppmanas att göra det trycker du på tangenten Enter igen för att ta bort kön och slutföra demonstrationen.

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar en kö och lägger till meddelanden i den med hjälp av asynkron .NET-kod. Sedan lärde du dig att granska, hämta och ta bort meddelanden. Slutligen har du lärt dig hur du tar bort en meddelandekö.

Självstudier, exempel, snabbstarter och annan dokumentation finns i:

• Relaterade kodexempel med inaktuella .NET version 11.x SDK:er finns i Kodexempel med .NET version 11.x.
• Mer information finns i Azure Storage-biblioteken för .NET.
• Fler Azure Queue Storage-exempelappar finns i Azure Queue Storage-klientbiblioteket för .NET-exempel.
• Mer information om .NET Core finns i Kom igång med .NET på 10 minuter.