Komma igång med Azure Queue Storage med hjälp av .NET

Artikel
10/08/2020

Översikt

Azure Queue Storage tillhandahåller molnmeddelanden mellan programkomponenter. Vid utformning av program för skalning är programkomponenter ofta frikopplade så att de kan skalas oberoende av varandra. Queue Storage levererar asynkrona meddelanden mellan programkomponenter, oavsett om de körs i molnet, på skrivbordet, på en lokal server eller på en mobil enhet. Queue Storage stöder också hantering av asynkrona uppgifter och skapande av processarbetsflöden.

Om den här självstudiekursen

Den här självstudien visar hur du skriver .NET-kod för några vanliga scenarier med Azure Queue Storage. Du lär dig bland annat hur du skapar och tar bort köer och hur du lägger till, läser och tar bort kömeddelanden.

Uppskattad tidsåtgång: 45 minuter

Förutsättningar

Vad är Queue Storage?

Azure Queue Storage är en tjänst för att lagra stora mängder meddelanden som kan nås från var som helst i världen via autentiserade anrop med HTTP eller HTTPS. Ett enda kömeddelande kan vara upp till 64 KB stort och en kö kan innehålla miljontals meddelanden, upp till den totala kapacitetsgränsen för ett lagringskonto. Kölagring används ofta för att skapa en kvarvarande arbetslogg för att bearbeta asynkront.

Begrepp för kötjänst

Azure Queue-tjänsten innehåller följande komponenter:

Azure Queue-tjänstkomponenter

Lagringskonto: All åtkomst till Azure Storage görs genom 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. Den maximala tid som ett meddelande kan finnas i kön är 7 dagar. För version 2017-07-29 eller senare kan den maximala time-to-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 att leva sju dagar.
URL-format: Köer kan adresseras med följande URL-format: http://<storage account>.queue.core.windows.net/<queue>

Följande URL adresserar en kö i diagrammet:

http://myaccount.queue.core.windows.net/incoming-orders

Skapa ett Azure Storage-konto

Det enklaste sättet att skapa ditt första Azure Storage-konto är att använda Azure Portal. Läs mer i Skapa ett lagringskonto.

Du kan också skapa ett Azure Storage-konto med Azure PowerShell, Azure CLI eller Azure Storage-resursprovidern för .NET.

Om du föredrar att inte skapa ett lagringskonto i Azure just nu kan du också använda Azurite Storage-emulatorn för att köra och testa koden i en lokal miljö. Mer information finns i Använda Azurite-emulatorn för lokal Azure Storage-utveckling.

Ställt in din utvecklingsmiljö

Konfigurera sedan din utvecklingsmiljö i Visual Studio så att du är redo att testa kodexemplen i den här guiden.

Skapa ett Windows-konsolprogramprojekt

Skapa ett nytt Windows-konsolprogram i Visual Studio. Följande steg visar hur du skapar ett konsolprogram i Visual Studio 2019. Stegen är ungefär som i andra versioner av Visual Studio.

Välj Nyttprojektför fil>>
VäljPlattformsfönster>
Välj Konsolapp (.NET Framework)
Välj Nästa
I fältet Projektnamn anger du ett namn för ditt program
Välj Skapa

Alla kodexempel i den här självstudiekursen kan läggas till i Main()-metoden i konsolprogrammets Program.cs-fil.

Du kan använda Azure Storage-klientbiblioteken i alla typer av .NET-program, inklusive en Azure-molntjänst eller webbapp, samt skrivbords- och mobilprogram. I den här guiden använder vi oss av en konsolapp för enkelhetens skull.

Använd NuGet för att installera de paket som behövs

Du måste referera till följande fyra paket i projektet för att slutföra den här självstudien:

Azure.Core-bibliotek för .NET: Det här paketet innehåller delade primitiver, abstraktioner och hjälpfunktioner för moderna .NET Azure SDK-klientbibliotek.
Azure.Storage.Common-klientbibliotek för .NET: Det här paketet tillhandahåller infrastruktur som delas av de andra Azure Storage-klientbiblioteken.
Azure.Storage.Queues-klientbibliotek för .NET: Med det här paketet kan du arbeta med Azure Queue Storage för att lagra meddelanden som kan nås av en klient.
System.Configuration.ConfigurationManager-bibliotek för .NET: Det här paketet ger åtkomst till konfigurationsfiler för klientprogram.

Du kan använda NuGet för att hämta dessa paket. Följ de här stegen:

Högerklicka på projektet i Solution Explorer och välj Hantera NuGet-paket.
Välj Bläddra
Sök online efter och välj Installera för Azure.Storage.Queuesatt installera Azure Storage-klientbiblioteket och dess beroenden. Detta installerar även Biblioteken Azure.Storage.Common och Azure.Core, som är beroenden för köbiblioteket.
Sök online efter och välj Installera för System.Configuration.ConfigurationManageratt installera Configuration Manager.

Fastställ målmiljön

Du har två miljöalternativ för att köra exemplen i den här guiden:

Du kan köra din kod mot ett Azure Storage-konto i molnet.
Du kan köra koden mot Azurite Storage-emulatorn. Azurite är en lokal miljö som emulerar ett Azure Storage-konto i molnet. Azurite är ett kostnadsfritt alternativ för att testa och felsöka koden medan programmet är under utveckling. Emulatorn använder sig av ett välkänt konto och nyckel. Mer information finns i Använda Azurite-emulatorn för lokal Azure Storage-utveckling och testning.

Anteckning

Du kan använda lagringsemulatorn för att undvika kostnader associerade med Azure Storage. Men om du väljer att rikta in dig på ett Azure Storage-konto i molnet blir kostnaderna för att utföra den här självstudien försumbara.

Hämta lagringsanslutningssträngen

Azure Storage-klientbiblioteken för .NET stöder användning av en lagringsanslutningssträng för att konfigurera slutpunkter och autentiseringsuppgifter för åtkomst till lagringstjänster. Mer information finns i Hantera åtkomstnycklar för lagringskonto.

Kopiera dina autentiseringsuppgifter från Azure-portalen

Exempelkoden måste autentisera åtkomsten till lagringskontot. När du vill autentisera tillhandahåller du autentiseringsuppgifterna för ditt lagringskonto i form av en anslutningssträng i programmet. Visa autentiseringsuppgifterna för lagringskontot:

Navigera till Azure-portalen.
Leta rätt på ditt lagringskonto.
Välj Åtkomstnycklar i avsnittet Inställningar i lagringskontoöversikten. Åtkomstnycklarna för kontot visas, samt den fullständiga anslutningssträngen för varje nyckel.
Sök efter värdet för Anslutningssträng under key1 och kopiera anslutningssträngen genom att klicka på Kopiera. Du lägger till strängvärdet för anslutningen till en miljövariabel i nästa steg.

Mer information om anslutningssträngar finns i Konfigurera en anslutningssträng för Azure Storage.

Anteckning

Din nyckel för lagringskontot liknar rotlösenordet för lagringskontot. Var alltid noga med att skydda din lagringskontonyckel. Undvik att dela ut den till andra användare, hårdkoda den eller spara den i en oformaterad textfil som andra har åtkomst till. Återskapa din nyckel med hjälp av Azure Portal om du misstänker att den komprometterats.

Det bästa sättet att underhålla anslutningssträngen för lagring är i en konfigurationsfil. För att konfigurera din anslutningssträng öppnar du app.config-filen i Solutions Explorer i Visual Studio. Lägg till innehållet i elementet som <appSettings> visas här. Ersätt connection-string med värdet som du kopierade från ditt lagringskonto i portalen:

<configuration>
    <startup>
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
    </startup>
    <appSettings>
        <add key="StorageConnectionString" value="connection-string" />
    </appSettings>
</configuration>

Din konfigurationsinställning kan till exempel se ut så här:

<add key="StorageConnectionString" value="DefaultEndpointsProtocol=https;AccountName=storagesample;AccountKey=GMuzNHjlB3S9itqZJHHCnRkrokLkcSyW7yK9BRbGp0ENePunLPwBgpxV1Z/pVo9zpem/2xSHXkMqTHHLcx8XRA==EndpointSuffix=core.windows.net" />

Om du vill rikta in dig på Azurite Storage-emulatorn kan du använda en genväg som mappar till det välkända kontonamnet och nyckeln. I så fall är din inställning för anslutningssträngen:

<add key="StorageConnectionString" value="UseDevelopmentStorage=true" />

Lägga till med hjälp av direktiv

Lägg till följande using-direktiv längst upp i filen Program.cs:

using System; // Namespace for Console output
using System.Configuration; // Namespace for ConfigurationManager
using System.Threading.Tasks; // Namespace for Task
using Azure.Identity;
using Azure.Storage.Queues; // Namespace for Queue storage types
using Azure.Storage.Queues.Models; // Namespace for PeekedMessage

Skapa Queue Storage-klienten

Med QueueClient klassen kan du hämta köer som lagras i Queue Storage. Här är ett sätt att skapa tjänstklienten:

//-------------------------------------------------
// Create the queue service client
//-------------------------------------------------
public void CreateQueueClient(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to create and manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);
}

Tips

Meddelanden som du skickar med hjälp QueueClient av klassen måste vara i ett format som kan inkluderas i en XML-begäran med UTF-8-kodning. Du kan också ange alternativet MessageEncoding till Base64 för att hantera icke-kompatibla meddelanden.

Nu är du redo att skriva kod som läser data från och skriver data till Queue Storage.

Skapa en kö

Det här exemplet visar hur du skapar en kö:

//-------------------------------------------------
// Create a message queue
//-------------------------------------------------
public bool CreateQueue(string queueName)
{
    try
    {
        // Get the connection string from app settings
        string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

        // Instantiate a QueueClient which will be used to create and manipulate the queue
        QueueClient queueClient = new QueueClient(connectionString, queueName);

        // Create the queue
        queueClient.CreateIfNotExists();

        if (queueClient.Exists())
        {
            Console.WriteLine($"Queue created: '{queueClient.Name}'");
            return true;
        }
        else
        {
            Console.WriteLine($"Make sure the Azurite storage emulator running and try again.");
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Exception: {ex.Message}\n\n");
        Console.WriteLine($"Make sure the Azurite storage emulator running and try again.");
        return false;
    }
}

Infoga ett meddelande i en kö

Om du vill infoga ett meddelande i en befintlig kö anropar du SendMessage metoden . Ett meddelande kan vara antingen en sträng (i UTF-8-format) eller en bytematris. Följande kod skapar en kö (om den inte finns) och infogar ett meddelande:

//-------------------------------------------------
// Insert a message into a queue
//-------------------------------------------------
public void InsertMessage(string queueName, string message)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to create and manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    // Create the queue if it doesn't already exist
    queueClient.CreateIfNotExists();

    if (queueClient.Exists())
    {
        // Send a message to the queue
        queueClient.SendMessage(message);
    }

    Console.WriteLine($"Inserted: {message}");
}

En titt på nästa meddelande

Du kan titta på meddelandena i kön utan att ta bort dem från kön genom att anropa PeekMessages metoden . Om du inte skickar ett värde för parametern maxMessages är standardvärdet att titta på ett meddelande.

//-------------------------------------------------
// Peek at a message in the queue
//-------------------------------------------------
public void PeekMessage(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    { 
        // Peek at the next message
        PeekedMessage[] peekedMessage = queueClient.PeekMessages();

        // Display the message
        Console.WriteLine($"Peeked message: '{peekedMessage[0].Body}'");
    }
}

Ändra innehållet i ett meddelande i kön

Du kan ändra innehållet i ett meddelande direkt i kön. Om meddelandet representerar en arbetsuppgift kan du använda den här funktionen för att uppdatera arbetsuppgiftens status. Följande kod uppdaterar kömeddelandet med nytt innehåll och utökar tidsgränsen för visning med ytterligare 60 sekunder. Koden sparar statusen för arbetsuppgiften som associeras med meddelandet och ger klienten ytterligare en minut att fortsätta arbeta med meddelandet. Du kan använda den här tekniken för att spåra arbetsflöden i flera steg i kömeddelanden, utan att behöva börja om från början om ett bearbetningssteg misslyckas på grund av maskinvaru- eller programvarufel. Normalt räknar du även antalet omförsök och tar bort meddelandet om fler än n försök misslyckas. Detta skyddar mot meddelanden som utlöser ett programfel varje gång de bearbetas.

//-------------------------------------------------
// Update an existing message in the queue
//-------------------------------------------------
public void UpdateMessage(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Get the message from the queue
        QueueMessage[] message = queueClient.ReceiveMessages();

        // Update the message contents
        queueClient.UpdateMessage(message[0].MessageId, 
                message[0].PopReceipt, 
                "Updated contents",
                TimeSpan.FromSeconds(60.0)  // Make it invisible for another 60 seconds
            );
    }
}

Ta bort nästa meddelande från kön

Ta bort ett meddelande från en kö i två steg. När du anropar ReceiveMessagesfår du nästa meddelande i en kö. Ett meddelande som returneras från ReceiveMessages blir osynligt för all annan kod som läser meddelanden från den här kön. Som standard är det här meddelandet osynligt i 30 sekunder. För att slutföra borttagningen av meddelandet från kön måste du även anropa DeleteMessage. Den här tvåstegsprocessen för att ta bort ett meddelande säkerställer att om din kod inte kan bearbeta ett meddelande på grund av ett maskin- eller programvarufel så kan en annan instans av koden hämta samma meddelande och försöka igen. Koden anropar DeleteMessage direkt efter att meddelandet har bearbetats.

//-------------------------------------------------
// Process and remove a message from the queue
//-------------------------------------------------
public void DequeueMessage(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Get the next message
        QueueMessage[] retrievedMessage = queueClient.ReceiveMessages();

        // Process (i.e. print) the message in less than 30 seconds
        Console.WriteLine($"Dequeued message: '{retrievedMessage[0].Body}'");

        // Delete the message
        queueClient.DeleteMessage(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
    }
}

Använd mönstret Async-Await med vanliga Queue Storage-API:er

Det här exemplet visar hur du använder Async-Await-mönstret med vanliga Queue Storage-API:er. Exemplet anropar den asynkrona versionen av var och en av de angivna metoderna, vilket anges av suffixet för Async varje metod. När en asynkron metod används pausar Async-Await-mönstret lokal körning tills anropet har slutförts. Detta gör att den aktuella tråden kan arbeta med annat, vilket innebär att flaskhalsar kan undvikas samtidigt som programmets svarstider förbättras. Mer information om hur du använder mönstret Async-Await i .NET finns i Async and Await (C# och Visual Basic)

//-------------------------------------------------
// Perform queue operations asynchronously
//-------------------------------------------------
public async Task QueueAsync(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    // Create the queue if it doesn't already exist
    await queueClient.CreateIfNotExistsAsync();

    if (await queueClient.ExistsAsync())
    {
        Console.WriteLine($"Queue '{queueClient.Name}' created");
    }
    else
    {
        Console.WriteLine($"Queue '{queueClient.Name}' exists");
    }

    // Async enqueue the message
    await queueClient.SendMessageAsync("Hello, World");
    Console.WriteLine($"Message added");

    // Async receive the message
    QueueMessage[] retrievedMessage = await queueClient.ReceiveMessagesAsync();
    Console.WriteLine($"Retrieved message with content '{retrievedMessage[0].Body}'");

    // Async delete the message
    await queueClient.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
    Console.WriteLine($"Deleted message: '{retrievedMessage[0].Body}'");

    // Async delete the queue
    await queueClient.DeleteAsync();
    Console.WriteLine($"Deleted queue: '{queueClient.Name}'");
}

Använd ytterligare alternativ för att ta bort meddelanden

Det finns två metoder som du kan använda för att anpassa meddelandehämtningen från en kö. För det första kan du hämta en grupp med meddelanden (upp till 32). För det andra kan du ange en längre eller kortare tidsgräns för osynlighet för att ge koden mer eller mindre tid att bearbeta klart varje meddelande.

I följande kodexempel används ReceiveMessages metoden för att hämta 20 meddelanden i ett anrop. Sedan bearbetas varje meddelande med hjälp av en foreach loop. Koden ställer också in tidsgränsen för osynlighet till fem minuter för varje meddelande. Observera att de fem minuterna startar för alla meddelanden samtidigt, så när fem minuter har gått sedan anropet till ReceiveMessagesvisas alla meddelanden som inte har tagits bort igen.

//-----------------------------------------------------
// Process and remove multiple messages from the queue
//-----------------------------------------------------
public void DequeueMessages(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Receive and process 20 messages
        QueueMessage[] receivedMessages = queueClient.ReceiveMessages(20, TimeSpan.FromMinutes(5));

        foreach (QueueMessage message in receivedMessages)
        {
            // Process (i.e. print) the messages in less than 5 minutes
            Console.WriteLine($"De-queued message: '{message.Body}'");

            // Delete the message
            queueClient.DeleteMessage(message.MessageId, message.PopReceipt);
        }
    }
}

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 antalet är inte lägre än det faktiska antalet meddelanden i kön, men kan vara högre.

//-----------------------------------------------------
// Get the approximate number of messages in the queue
//-----------------------------------------------------
public void GetQueueLength(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        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 bort en kö

Om du vill ta bort en kö och alla meddelanden som finns i den anropar Delete du metoden för köobjektet.

//-------------------------------------------------
// Delete the queue
//-------------------------------------------------
public void DeleteQueue(string queueName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a QueueClient which will be used to manipulate the queue
    QueueClient queueClient = new QueueClient(connectionString, queueName);

    if (queueClient.Exists())
    {
        // Delete the queue
        queueClient.Delete();
    }

    Console.WriteLine($"Queue deleted: '{queueClient.Name}'");
}

Nästa steg

Nu när du har lärt dig grunderna i Queue Storage följer du dessa länkar för att lära dig mer om mer komplexa lagringsuppgifter.

Se referensdokumentationen för Queue Storage för fullständig information om tillgängliga API:er:
- Azure Storage-klientbibliotek för .NET-referens
- Rest-API-referens för Azure Storage
Visa fler funktionsguider och lär dig mer om andra alternativ för att lagra data i Azure.
- Kom igång med Azure Table Storage med hjälp av .NET för att lagra strukturerade data.
- Kom igång med Azure Blob Storage använda .NET för att lagra ostrukturerade data.
- Anslut till SQL Database med hjälp av .NET (C#) för att lagra relationsdata.
Lär dig hur du förenklar koden du skriver så att den fungerar med Azure Storage genom att använda Azure WebJobs SDK.

Relaterade kodexempel med inaktuell .NET version 11.x SDK:er finns i Kodexempel med .NET version 11.x.

Dela via