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

Översikt

Azure Queue Storage tillhandahåller molnmeddelanden mellan programkomponenter. När program utformas 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 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

Krav

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 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 tidsgränsen 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 time to live 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-lagringskonto ä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.

  1. Välj Arkiv>Nytt>projekt
  2. VäljPlattformsfönster>
  3. Välj Konsolapp (.NET Framework)
  4. Välj Nästa
  5. I fältet Projektnamn 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-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:

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

  1. Högerklicka på projektet i Průzkumník řešení och välj Hantera NuGet-paket.
  2. Välj Bläddra
  3. 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 till köbiblioteket.
  4. 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 utveckling och testning i Azure Storage.

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 din lagrings-συμβολοσειρά σύνδεσης

Azure Storage-klientbiblioteken för .NET stöder användning av en lagrings-συμβολοσειρά σύνδεσης 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 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 ingå 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 PeekMessages anropa 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 med 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
            );
    }
}

Avmarkera nästa meddelande

Avmarkera 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 andra kodläsningsmeddelanden från den här kön. Som standard är det här meddelandet osynligt i 30 sekunder. Om du vill ta bort 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 anropas 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 mönstret Async-Await med vanliga Queue Storage-API:er. Exemplet anropar den asynkrona versionen av var och en av de angivna metoderna, enligt 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 Async-Await-mönstret 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ända 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å efter fem minuter har gått sedan anropet till ReceiveMessagesblir alla meddelanden som inte har tagits bort synliga 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 talet ä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.