Sdílet prostřednictvím

Začínáme s Azure Queue Storage pomocí rozhraní .NET

  • Článek

Přehled

Azure Queue Storage poskytuje cloudové zasílání zpráv mezi komponentami aplikace. Při návrhu aplikací pro škálování jsou komponenty aplikací často oddělené, aby se mohly škálovat nezávisle. Queue Storage poskytuje asynchronní zasílání zpráv mezi komponentami aplikace, ať už běží v cloudu, na stolním počítači, na místním serveru nebo na mobilním zařízení. Queue Storage také podporuje správu asynchronních úloh a vytváření pracovních toků procesů.

O tomto kurzu

V tomto kurzu se dozvíte, jak psát kód .NET pro některé běžné scénáře s využitím Služby Azure Queue Storage. Jsou například zahrnuty scénáře vytváření a odstraňování front a přidávání, čtení a odstraňování front zpráv.

Odhadovaný čas dokončení: 45 minut

Požadavky

Co je Queue Storage?

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke které můžete získat přístup z jakéhokoli místa na světě prostřednictvím ověřených volání s využitím protokolu HTTP nebo HTTPS. Zpráva s jednou frontou může mít velikost až 64 kB a jedna fronta můžete obsahovat miliony zpráv, až do dosažení celkové kapacity účtu úložiště. Queue Storage se často používá k vytvoření backlogu práce, která se má zpracovat asynchronně.

Koncepty služby Fronta

Služba Azure Queue obsahuje následující komponenty:

Komponenty služby Azure Queue

  • Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště. Další informace o účtech úložiště najdete v tématu Přehled účtu úložiště.

  • Fronta: Fronta obsahuje sadu zpráv. Všechny zprávy musí být ve frontě. Upozorňujeme, že název fronty musí být psaný malými písmeny. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.

  • Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní. Pro verzi 2017-07-29 nebo novější může být maximální hodnota time-to-live libovolné kladné číslo nebo -1 označující, že platnost zprávy nevyprší. Pokud je tento parametr vynechán, výchozí hodnota time-to-live je sedm dní.

  • Formát adresy URL: Fronty lze adresovat pomocí následujícího formátu adresy URL: http://<storage account>.queue.core.windows.net/<queue>

    Následující adresa URL odkazuje na frontu v diagramu:

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

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je použít Azure Portal. Další informace najdete v tématu Vytvoření účtu úložiště.

Účet úložiště Azure můžete vytvořit také pomocí prostředí Azure PowerShell, rozhraní příkazového řádku Azure nebo pomocí poskytovatele prostředků služby Azure Storage pro .NET.

Pokud nechcete v tuto chvíli vytvořit účet úložiště v Azure, můžete také použít emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí. Další informace najdete v tématu Použití emulátoru Azurite pro místní vývoj služby Azure Storage.

Nastavíte vývojové prostředí

Potom si nastavte vývojové prostředí v sadě Visual Studio, abyste byli připraveni vyzkoušet příklady kódů z této příručky.

Vytvoření projektu konzolové aplikace pro Windows

V sadě Visual Studio vytvořte novou konzolovou aplikaci pro Windows. Následující kroky ukazují, jak vytvořit konzolovou aplikaci v sadě Visual Studio 2019. Kroky u ostatních verzí sady Visual Studio jsou podobné.

  1. Vyberte Soubornový>projekt.>
  2. Vyberte Windows platformy.>
  3. Výběr konzolové aplikace (.NET Framework)
  4. Vyberte Další.
  5. Do pole Název projektu zadejte název vaší aplikace.
  6. Vyberte Vytvořit.

Všechny příklady kódu v tomto kurzu můžete přidat do metody Main() v souboru Program.cs vaší konzolové aplikace.

Klientské knihovny Azure Storage můžete používat v libovolném typu aplikace .NET, včetně cloudové služby Azure nebo webové aplikace a desktopových a mobilních aplikací. V této příručce použijeme konzolovou aplikaci kvůli zjednodušení.

Použití balíčku NuGet k instalaci požadovaných balíčků

K dokončení tohoto kurzu potřebujete v projektu odkazovat na následující čtyři balíčky:

K získání těchto balíčků můžete použít NuGet. Postupujte takto:

  1. Klikněte pravým tlačítkem na projekt v Průzkumník řešení a zvolte Spravovat balíčky NuGet.
  2. Vyberte Procházet.
  3. Vyhledejte online Azure.Storage.Queuesa výběrem možnosti Nainstalovat nainstalujte klientskou knihovnu Azure Storage a její závislosti. Tím se také nainstalují knihovny Azure.Storage.Common a Azure.Core, které jsou závislostmi knihovny front.
  4. Vyhledejte online System.Configuration.ConfigurationManagera výběrem možnosti Nainstalovat nainstalujte Configuration Manager.

Určení cílového prostředí

Ke spuštění příkladů z této příručky máte dvě možnosti prostředí:

  • Svůj kód můžete spustit na účtu služby Azure Storage v cloudu.
  • Kód můžete spustit v emulátoru úložiště Azurite. Azurite je místní prostředí, které emuluje účet Azure Storage v cloudu. Azurite je bezplatná možnost pro testování a ladění kódu v době, kdy je vaše aplikace ve vývoji. Emulátor používá známý účet a klíč. Další informace najdete v tématu Použití emulátoru Azurite k místnímu vývoji a testování služby Azure Storage.

Poznámka

Pokud se chcete vyhnout nákladům spojeným se službou Azure Storage, můžete se zaměřit na emulátor úložiště. Pokud se ale rozhodnete cílit na účet služby Azure Storage v cloudu, budou náklady na provedení tohoto kurzu zanedbatelné.

Získání připojovacího řetězce úložiště

Klientské knihovny Azure Storage pro .NET podporují použití připojovacího řetězce úložiště ke konfiguraci koncových bodů a přihlašovacích údajů pro přístup ke službám úložiště. Další informace najdete v tématu Správa přístupových klíčů účtu úložiště.

Zkopírování přihlašovacích údajů z webu Azure Portal

Ukázkový kód potřebuje autorizovat přístup k vašemu účtu úložiště. Autorizaci provedete tak, že aplikaci poskytnete přihlašovací údaje svého účtu úložiště v podobě připojovacího řetězce. Zobrazení přihlašovacích údajů účtu úložiště:

  1. Přejděte na Azure Portal.

  2. Vyhledejte svůj účet úložiště.

  3. V části Nastavení v přehledu účtu úložiště vyberte Přístupové klíče. Zobrazí se přístupové klíče vašeho účtu a také úplný připojovací řetězec pro jednotlivé klíče.

  4. V části key1 vyhledejte hodnotu Připojovací řetězec a kliknutím na tlačítko Kopírovat zkopírujte připojovací řetězec. V dalším kroku přidáte hodnotu připojovacího řetězce do proměnné prostředí.

    Snímek obrazovky ukazující zkopírování připojovacího řetězce z webu Azure Portal

Další informace o připojovacích řetězcích najdete v tématu věnovaném konfiguraci připojovacího řetězce pro službu Azure Storage.

Poznámka

Klíč účtu úložiště je podobný kořenovému heslu vašeho účtu úložiště. Vždy klíč účtu úložiště pečlivě chraňte. Nedávejte ho jiným uživatelům, nezakódovávejte ho ani ho neukládejte do souboru ve formátu prostého textu, který je přístupný ostatním uživatelům. Pokud se domníváte, že klíč je ohrožený, vygenerujte ho znovu pomocí webu Azure Portal.

Připojovací řetězec úložiště se nejlépe uchovává v konfiguračním souboru. Pokud chcete konfigurovat připojovací řetězec, otevřete v sadě Visual Studio Průzkumníka řešení a v něm soubor app.config. Přidejte obsah zde zobrazeného elementu <appSettings> . Nahraďte connection-string hodnotou, kterou jste zkopírovali z účtu úložiště na portálu:

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

Nastavení konfigurace může vypadat následovně:

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

Pokud chcete cílit na emulátor úložiště Azurite, můžete použít zástupce, který se mapuje na dobře známý název účtu a klíč. V takovém případě bude nastavení připojovacího řetězce vypadat následovně:

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

Přidání direktiv using

Přidejte na začátek souboru Program.cs následující direktivy using:

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

Vytvoření klienta Queue Storage

Třída QueueClient umožňuje načíst fronty uložené ve službě Queue Storage. Tady je jeden ze způsobů, jak vytvořit klienta služby:

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

Tip

Zprávy odeslané pomocí QueueClient třídy musí být ve formátu, který lze zahrnout do požadavku XML s kódováním UTF-8. Volitelně můžete nastavit možnost MessageEncoding na Base64 pro zpracování zpráv, které nedodržují předpisy.

Teď jste připraveni napsat kód, který čte data ze služby Queue Storage a zapisuje je do služby Queue Storage.

Vytvoření fronty

Tento příklad ukazuje, jak vytvořit frontu:

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

Vložení zprávy do fronty

Pokud chcete vložit zprávu do existující fronty, zavolejte metodu SendMessage . Zpráva může být buď řetězec (ve formátu UTF-8), nebo pole bajtů. Následující kód vytvoří frontu (pokud neexistuje) a vloží zprávu:

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

Zobrazení náhledu další zprávy

Voláním metody můžete zobrazit náhled zpráv ve frontě, aniž byste je z fronty odebrali PeekMessages . Pokud hodnotu parametru maxMessages nepředáte, ve výchozím nastavení se zobrazí náhled jedné zprávy.

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

Změna obsahu zpráv zařazených ve frontě

Podle potřeby můžete změnit obsah zprávy přímo ve frontě. Pokud zpráva představuje pracovní úlohu, mohli byste tuto funkci použít k aktualizaci stavu pracovních úloh. Následující kód aktualizuje zprávy ve frontě o nový obsah a prodlouží časový limit viditelnosti na 60 sekund. Uloží se tím stav práce spojený se zprávou a klient získá další minutu, aby mohl pokračovat ve zpracování zprávy. Tuto techniku můžete použít ke sledování vícekrokových pracovních postupů u zpráv ve frontě, aniž byste museli začít od začátku, pokud krok zpracování selže kvůli selhání hardwaru nebo softwaru. Obvykle byste udržovali také hodnotu počtu opakování, a pokud by se pokus o zpracování zprávy opakoval více než nkrát, odstranili byste ji. Je to ochrana proti tomu, aby zpráva při každém pokusu o zpracování nevyvolala chyby aplikace.

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

Vyřazení další zprávy z fronty

Vyřazení zprávy z fronty ve dvou krocích Když zavoláte ReceiveMessages, zobrazí se další zpráva ve frontě. Zpráva vrácená z ReceiveMessages této fronty se stane neviditelnou pro jakýkoli jiný kód, který čte zprávy z této fronty. Ve výchozím nastavení tato zpráva zůstává neviditelná po dobu 30 sekund. Pokud chcete dokončit odebrání zprávy z fronty, musíte také zavolat DeleteMessage. Tento dvoukrokový proces odebrání zprávy zaručuje, aby v případě, že se vašemu kódu nepodaří zprávu zpracovat z důvodu selhání hardwaru nebo softwaru, mohla stejnou zprávu získat jiná instance vašeho kódu a bylo možné to zkusit znovu. Váš kód volá DeleteMessage hned po zpracování zprávy.

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

Použití modelu Async-Await s běžnými rozhraními API služby Queue Storage

Tento příklad ukazuje, jak používat vzor Async-Await s běžnými rozhraními API služby Queue Storage. Ukázka volá asynchronní verzi každé z daných metod, jak je uvedeno příponou Async každé metody. Při použití asynchronní metody model Async-Await pozastaví místní provádění, dokud se volání neskončí. Toto chování umožňuje aktuálnímu vláknu provádět další činnosti, což pomáhá zabránit vzniku kritických bodů z hlediska výkonu a zlepšuje celkovou rychlost reakce aplikace. Další podrobnosti o použití modelu Async-Await v .NET najdete v tématu Async a Await (C# a 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}'");
}

Použití dalších možností pro vyřazení zpráv z fronty

Načítání zpráv z fronty si můžete přizpůsobit dvěma způsoby. Za prvé si můžete načíst dávku zpráv (až 32). Za druhé si můžete nastavit delší nebo kratší časový limit neviditelnosti, aby měl váš kód více nebo méně času na úplné zpracování jednotlivých zpráv.

Následující příklad kódu používá metodu ReceiveMessages k získání 20 zpráv v jednom volání. Každou zprávu pak zpracuje pomocí smyčky foreach . Také se pro každou zprávu nastaví časový limit neviditelnosti 5 minut. Všimněte si, že 5 minut začíná u všech zpráv najednou, takže po uplynutí pěti minut od volání služby ReceiveMessagesse všechny zprávy, které nebyly odstraněny, znovu zobrazí.

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

Získání délky fronty

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě. Metoda GetProperties vrátí vlastnosti fronty včetně počtu zpráv. Vlastnost ApproximateMessagesCount obsahuje přibližný počet zpráv ve frontě. Toto číslo není nižší než skutečný počet zpráv ve frontě, ale může být vyšší.

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

Odstranění fronty

Chcete-li odstranit frontu a všechny zprávy v ní obsažené, zavolejte metodu Delete objektu fronty.

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

Další kroky

Teď, když jste se seznámili se základy služby Queue Storage, použijte tyto odkazy a seznamte se se složitějšími úlohami úložiště.

Související ukázky kódu s využitím zastaralých sad SDK rozhraní .NET verze 11.x najdete v tématu Ukázky kódu s využitím rozhraní .NET verze 11.x.