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

Översikt

Azure Queue Storage tillhandahåller molnmeddelanden mellan programkomponenter. Vid utformning av program för skalning är programkomponenter ofta fristående 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 också stöd för att hantera asynkrona uppgifter och skapa 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 Hjälp av 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. Queue Storage används ofta för att skapa en efter släpning av arbete som ska bearbetas asynkront.

Kötjänst begrepp

Azure-Kötjänst innehåller följande komponenter:

Azure Kötjänst-komponenter

  • Lagringskonto: All åtkomst till Azure Storage görs genom ett lagringskonto. Mer information om lagrings konton finns i Översikt över lagrings konto.

  • 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 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 standardvärdet för Time-to-Live sju dagar.

  • URL-format: Köer är adresser bara 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 inte vill skapa ett lagrings konto i Azure just nu kan du också använda Azurite-emulatorn för att köra och testa din kod 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.

  1. Välj Arkiv > Ny > Project
  2. Välj > Plattforms-Windows
  3. Välj Konsolapp (.NET Framework)
  4. Välj Nästa
  5. I fältet Project namn anger du ett namn för ditt program
  6. 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 klientbibliotek i alla typer av .NET-program, inklusive en Azure-molntjänst eller webbapp, samt skrivbordsprogram och mobilappar. 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:

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

  1. Högerklicka på ditt projekt i Solution Explorer och välj Hantera NuGet-paket.
  2. Välj Bläddra
  3. Sök online efter Azure.Storage.Queues och välj Installera för att installera Azure Storage klientbiblioteket och dess beroenden. Då installeras även Azure. Storage. Vanliga bibliotek och Azure.Core-bibliotek, som är köbibliotekets beroenden.
  4. Sök online efter System.Configuration.ConfigurationManager och välj Installera för att installera Konfigurationshanteraren.

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 din kod 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 ett Azure Storage i molnet kommer kostnaderna för att utföra den här självstudien att vara minimala.

Hämta lagringsanslutningssträngen

Klientbiblioteken Azure Storage .NET med hjälp 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:

  1. Gå till Azure Portal.

  2. Leta rätt på ditt lagringskonto.

  3. 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.

  4. 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.

    Skärmbild som visar hur man kopierar en anslutningssträng från Azure-portalen

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 <appSettings> som visas här. Ersätt connection-string med det värde som du kopierade från lagringskontot 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);
}

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 antingen vara 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 granska 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 maxMessages parametern är standardvärdet att granska 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 metoden 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 i frånkö

Ta bort ett meddelande från en kö i två steg. När du ReceiveMessages anropar får du nästa meddelande i en kö. Ett meddelande som returneras ReceiveMessages från blir osynligt för andra kodläsningsmeddelanden 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 också 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 vanliga Queue Storage-API:er

Det här exemplet visar hur du använder Async-Await med vanliga Queue Storage-API:er. Exemplet anropar den asynkrona versionen av var och en av de angivna metoderna, enligt Async suffixet för varje metod. När en asynkron metod används pausar Async-Await lokala körningen 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 Async-Await i .NET finns i Async och 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ända ytterligare alternativ för att ta bort meddelanden i frånqueuing

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 metoden ReceiveMessages för att hämta 20 meddelanden i ett anrop. Sedan bearbetar den 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å efter fem minuter har gått sedan anropet till , visas alla meddelanden som ReceiveMessages 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 Delete anropar 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 kan du följa dessa länkar för att lära dig mer om komplexa lagringsuppgifter.