Rövid útmutató: Az Azure Queue Storage ügyfélkódtára a .NET-hez

  • Cikk

Ismerkedés az Azure Queue Storage .NET-hez készült ügyfélkódtárával. Az Azure Queue Storage szolgáltatás nagy mennyiségű üzenet tárolására szolgál későbbi lekéréshez és feldolgozáshoz. Az alábbi lépések végrehajtásával telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

API-referenciadokumentáció Kódtár forráskódcsomagja | (NuGet) | -minták |

A .NET-hez készült Azure Queue Storage ügyfélkódtár használatával:

  • Üzenetsor létrehozása
  • Üzenetek hozzáadása üzenetsorhoz
  • Üzenetsor üzeneteibe való betekintés
  • Üzenet frissítése üzenetsorban
  • Az üzenetsor hosszának lekérése
  • Üzenetek fogadása üzenetsorból
  • Üzenetek törlése üzenetsorból
  • Üzenetsor törlése

Előfeltételek

Beállítás

Ez a szakasz végigvezeti egy projekt előkészítésén az Azure Queue Storage .NET-hez készült ügyfélkódtárával való együttműködésre.

A projekt létrehozása

Hozzon létre egy .NET-alkalmazást .QueuesQuickstart

  1. Egy konzolablakban (például parancsmag, PowerShell vagy Bash) a dotnet new paranccsal hozzon létre egy új konzolalkalmazást a névvel QueuesQuickstart. Ez a parancs létrehoz egy egyszerű "hello world" C# projektet egy Program.cs nevű egyetlen forrásfájllal.

    dotnet new console -n QueuesQuickstart

  2. Váltson az újonnan létrehozott QueuesQuickstart könyvtárra.

    cd QueuesQuickstart

A csomagok telepítése

Amíg továbbra is az alkalmazáskönyvtárban van, telepítse az Azure Queue Storage .NET-csomaghoz készült ügyfélkódtárát a dotnet add package parancs használatával.

dotnet add package Azure.Storage.Queues

Az Azure Identity ügyfélkódtárcsomagra az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatokhoz is szükség van.

dotnet add package Azure.Identity

Az alkalmazás-keretrendszer beállítása

  1. A projekt megnyitása a választott szerkesztőben
  2. A Program.cs fájl megnyitása
  3. Frissítse a meglévő kódot az alábbiaknak megfelelően:
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

Hitelesítés az Azure-ban

A legtöbb Azure-szolgáltatáshoz irányuló alkalmazáskéréseket engedélyezni kell. DefaultAzureCredential Az Azure Identity-ügyfélkódtár által biztosított osztály használata ajánlott módszer az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatok implementálásához a kódban.

Az Azure-szolgáltatásokra irányuló kéréseket közvetlenül jelszóval, kapcsolati sztring vagy más hitelesítő adatokkal is engedélyezheti. Ezt a megközelítést azonban körültekintően kell alkalmazni. A fejlesztőknek szorgalmasnak kell lenniük ahhoz, hogy ezeket a titkos kulcsokat soha ne fedje fel nem biztonságos helyen. Bárki, aki hozzáfér a jelszóhoz vagy titkos kulcshoz, hitelesítheti magát. DefaultAzureCredential továbbfejlesztett felügyeleti és biztonsági előnyöket kínál a fiókkulcson keresztül a jelszó nélküli hitelesítés engedélyezéséhez. Az alábbi példában mindkét lehetőség látható.

DefaultAzureCredential A .NET-hez készült Azure Identity-ügyfélkódtár által biztosított osztály. További információkért DefaultAzureCredentialtekintse meg a DefaultAzureCredential áttekintését. DefaultAzureCredential több hitelesítési módszert támogat, és meghatározza, hogy melyik metódust kell használni futásidőben. Ez a megközelítés lehetővé teszi, hogy az alkalmazás különböző hitelesítési módszereket használjon különböző környezetekben (helyi és éles környezetben) környezetspecifikus kód implementálása nélkül.

Az alkalmazás például helyi fejlesztéskor hitelesítheti a Visual Studio bejelentkezési hitelesítő adataival, majd használhat felügyelt identitást az Azure-ban való üzembe helyezés után. Ehhez az áttűnéshez nincs szükség kódmódosításra.

Helyi fejlesztéskor győződjön meg arról, hogy az üzenetsor-adatokat elérő felhasználói fiók rendelkezik a megfelelő engedélyekkel. A várólista adatainak olvasásához és írásához tárolósoradat-közreműködőre lesz szükség. A szerepkör hozzárendeléséhez hozzá kell rendelnie a Felhasználói hozzáférés Rendszergazda istrator szerepkört, vagy egy másik szerepkört, amely tartalmazza a Microsoft.Authorization/roleAssignments/write műveletet. Azure RBAC-szerepköröket rendelhet egy felhasználóhoz az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával. A szerepkör-hozzárendelések elérhető hatóköreiről a hatókör áttekintési oldalán tudhat meg többet.

Ebben a forgatókönyvben engedélyeket rendel hozzá a felhasználói fiókjához, amely a tárfiókra terjed ki, hogy kövesse a minimális jogosultság elvét. Ez a gyakorlat csak a minimálisan szükséges engedélyeket biztosítja a felhasználóknak, és biztonságosabb éles környezeteket hoz létre.

Az alábbi példa a Storage Queue Data Contributor szerepkört rendeli hozzá a felhasználói fiókjához, amely olvasási és írási hozzáférést biztosít a tárfiók üzenetsoradataihoz.

Fontos

A szerepkör-hozzárendelés propagálása a legtöbb esetben egy-két percet vesz igénybe az Azure-ban, de ritkán akár nyolc percet is igénybe vehet. Ha hitelesítési hibákat kap a kód első futtatásakor, várjon néhány percet, és próbálkozzon újra.

  1. Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.

  2. A tárfiók áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget a bal oldali menüben.

  3. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.

  4. Válassza a +Hozzáadás lehetőséget a felső menüből, majd a szerepkör-hozzárendelés hozzáadása lehetőséget az eredményül kapott legördülő menüből.

A screenshot showing how to assign a role.

  1. A keresőmezővel szűrheti az eredményeket a kívánt szerepkörre. Ebben a példában keresse meg a Tárolási várólista adatszolgáltatóját, és válassza ki a megfelelő eredményt, majd válassza a Tovább gombot.

  2. A Hozzáférés hozzárendelése területen válassza a Felhasználó, csoport vagy szolgáltatásnév lehetőséget, majd válassza a + Tagok kijelölése lehetőséget.

  3. A párbeszédpanelen keresse meg a Microsoft Entra-felhasználónevet (általában a user@domain e-mail-címét), majd válassza a Párbeszédpanel alján található Kiválasztás lehetőséget.

  4. Válassza a Véleményezés + hozzárendelés lehetőséget a végső lapra való ugráshoz, majd a folyamat befejezéséhez a Véleményezés + hozzárendelés lehetőséget.

Objektummodell

Az Azure Queue Storage szolgáltatás nagy számú üzenet tárolására szolgál. Az üzenetsor-üzenetek mérete legfeljebb 64 KB lehet. Az üzenetsorok több millió üzenetet tartalmazhatnak, akár a tárfiók teljes kapacitáskorlátját is. Az üzenetsorokat gyakran használják az aszinkron feldolgozáshoz használt teendőlista létrehozásához. A Queue Storage három típusú erőforrást kínál:

  • Tárfiók: Az Azure Storage-hoz való minden hozzáférés egy tárfiókon keresztül történik. További információ a tárfiókokról: Tárfiókok áttekintése
  • Üzenetsor: Az üzenetsorok üzenetek készleteit tartalmazzák. Az összes üzenetnek üzenetsorban kell lennie. Vegye figyelembe, hogy az üzenetsor neve csak kisbetűket tartalmazhat. Az üzenetsorok elnevezésével kapcsolatos információkat lásd: Naming Queues and Metadata (Üzenetsorok és metaadatok elnevezése).
  • Üzenet: Egy legfeljebb 64 KB méretű, tetszőleges méretű üzenet. Egy üzenet legfeljebb 7 napig maradhat az üzenetsorban. A 2017-07-29-es vagy újabb verzió esetén a maximális élettartam bármilyen pozitív szám lehet, vagy -1, amely azt jelzi, hogy az üzenet nem jár le. Ha ez a paraméter nincs megadva, az alapértelmezett élettartam hét nap.

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

Diagram of Queue storage architecture

Az alábbi .NET-osztályokkal kezelheti ezeket az erőforrásokat:

  • QueueServiceClient: Ez QueueServiceClient lehetővé teszi a tárfiók összes üzenetsorának kezelését.
  • QueueClient: Az QueueClient osztály lehetővé teszi az egyes üzenetsorok és azok üzeneteinek kezelését és kezelését.
  • QueueMessage: Az QueueMessage osztály az üzenetsor hívása ReceiveMessages során visszaadott egyes objektumokat jelöli.

Kódpéldák

Ezek a példakódrészletek bemutatják, hogyan hajthatja végre a következő műveleteket a .NET-hez készült Azure Queue Storage ügyfélkódtárral:

Hozzáférés engedélyezése és ügyfélobjektum létrehozása

A helyi fejlesztéshez győződjön meg arról, hogy ugyanazzal a Microsoft Entra-fiókkal van hitelesítve, amelyhez a szerepkört hozzárendelte. A hitelesítést olyan népszerű fejlesztői eszközökkel végezheti el, mint az Azure CLI vagy az Azure PowerShell. A hitelesítéshez használható fejlesztői eszközök különböző nyelveken eltérőek lehetnek.

Jelentkezzen be az Azure-ba az Azure CLI-vel a következő paranccsal:

az login

A hitelesítés után létrehozhat és engedélyezheti az objektumokat QueueClientDefaultAzureCredential a tárfiók üzenetsoradatainak eléréséhez. DefaultAzureCredential automatikusan felderíti és használja az előző lépésben bejelentkezett fiókot.

A használat engedélyezéséhez DefaultAzureCredentialgyőződjön meg arról, hogy hozzáadta az Azure.Identity-csomagot a csomagok telepítésében leírtak szerint. Emellett a Program.cs fájlban adja hozzá a Azure.Identity névtérre vonatkozó irányelveket is:

using Azure.Identity;

Ezután döntse el az üzenetsor nevét, és hozza létre az QueueClient osztály egy példányát engedélyezés DefaultAzureCredential céljából. Ezt az ügyfélobjektumot használjuk a tárfiók üzenetsor-erőforrásának létrehozásához és használatához.

Fontos

Az üzenetsornevek csak kisbetűket, számokat és kötőjeleket tartalmazhatnak, és betűvel vagy számmal kell kezdődniük. A kötőjelek előtt és után csak nem kötőjel karakter állhat. A névnek 3 és 63 karakter közötti hosszúságúnak kell lennie. További információ: Elnevezési üzenetsorok és metaadatok.

Adja hozzá a következő kódot a Program.cs fájl végéhez. Mindenképpen cserélje le a <storage-account-name> helyőrző értékét:

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

Megjegyzés:

Az osztály használatával QueueClient küldött üzeneteknek olyan formátumban kell lenniük, amely szerepelhet egy UTF-8 kódolású XML-kérelemben. A MessageEncoding beállítást igény szerint Base64 értékre állíthatja a nem megfelelő üzenetek kezeléséhez.

Üzenetsor létrehozása

QueueClient Az objektum használatával hívja meg a metódust, CreateAsync hogy létrehozza az üzenetsort a tárfiókban.

Adja hozzá ezt a kódot a Program.cs metódus végéhez:

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

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

Üzenetek hozzáadása üzenetsorhoz

Az alábbi kódrészlet aszinkron módon a metódus meghívásával ad hozzá üzeneteket az SendMessageAsync üzenetsorhoz. Emellett egy hívásból SendMessageAsync visszaadott fájlt is mentSendReceipt. A nyugtával frissítheti az üzenetet a program későbbi részében.

Adja hozzá ezt a kódot a Program.cs fájl végéhez:

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

Üzenetsor üzeneteibe való betekintés

A metódus meghívásával PeekMessagesAsync pillanthat meg az üzenetsor üzeneteibe. Ez a metódus egy vagy több üzenetet kér le az üzenetsor elejéről, de nem módosítja az üzenet láthatóságát.

Adja hozzá ezt a kódot a Program.cs fájl végéhez:

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

Üzenet frissítése üzenetsorban

Frissítse az üzenet tartalmát a UpdateMessageAsync metódus meghívásával. Ez a módszer módosíthatja az üzenetek láthatóságának időtúllépését és tartalmát. Az üzenet tartalmának legfeljebb 64 KB méretű UTF-8 kódolt sztringnek kell lennie. Az üzenet új tartalmával együtt adja meg a kódban korábban mentett értékek értékeit SendReceipt . Az SendReceipt értékek azonosítják a frissíteni kívánt üzenetet.

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

Az üzenetsor hosszának lekérése

Megbecsülheti egy üzenetsorban található üzenetek számát. A GetProperties metódus az üzenetsor tulajdonságait adja vissza, beleértve az üzenetszámot is. A ApproximateMessagesCount tulajdonság az üzenetsorban lévő üzenetek hozzávetőleges számát tartalmazza. Ez a szám nem alacsonyabb, mint az üzenetsorban lévő üzenetek tényleges száma, de magasabb is lehet.

Adja hozzá ezt a kódot a Program.cs fájl végéhez:

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

Üzenetek fogadása üzenetsorból

Töltse le a korábban hozzáadott üzeneteket a metódus meghívásával ReceiveMessagesAsync .

Adja hozzá ezt a kódot a Program.cs fájl végéhez:

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

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

Megadhat egy értéket maxMessages, amely az üzenetsorból lekérendő üzenetek száma. Az alapértelmezett érték 1 üzenet, a maximum 32 üzenet. Megadhat egy értéket visibilityTimeoutis, amely elrejti az üzeneteket más műveletekből az időtúllépési időszakra vonatkozóan. Az alapértelmezett érték 30 másodperc.

Üzenetek törlése üzenetsorból

A feldolgozásuk után törölje az üzeneteket az üzenetsorból. Ebben az esetben a feldolgozás csak az üzenetet jeleníti meg a konzolon.

Az alkalmazás szünetelteti a felhasználói bevitelt, Console.ReadLine mielőtt feldolgozza és törli az üzeneteket. A törlés előtt ellenőrizze az Azure Portalon , hogy az erőforrások megfelelően lettek-e létrehozva. A kifejezetten nem törölt üzenetek végül ismét láthatóvá válnak az üzenetsorban, hogy újra feldolgozzák őket.

Adja hozzá ezt a kódot a Program.cs fájl végéhez:

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

Üzenetsor törlése

Az alábbi kód megtisztítja az alkalmazás által létrehozott erőforrásokat az üzenetsor törlésével a DeleteAsync metódus használatával.

Adja hozzá ezt a kódot a Program.cs fájl végéhez:

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

A kód futtatása

Ez az alkalmazás három üzenetet hoz létre és ad hozzá egy Azure-üzenetsorhoz. A kód felsorolja az üzenetsorban lévő üzeneteket, majd lekéri és törli őket, mielőtt véglegesen törölené az üzenetsort.

A konzolablakban keresse meg az alkalmazás könyvtárát, majd hozza létre és futtassa az alkalmazást.

dotnet build

dotnet run

Az alkalmazás kimenete a következő példához hasonló:

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

Amikor az alkalmazás szünetelteti az üzenetek fogadását, ellenőrizze a tárfiókot az Azure Portalon. Ellenőrizze, hogy az üzenetek szerepelnek-e az üzenetsorban.

Nyomja le a billentyűt az Enter üzenetek fogadásához és törléséhez. Amikor a rendszer kéri, nyomja le ismét a billentyűt az Enter üzenetsor törléséhez és a bemutató befejezéséhez.

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre egy üzenetsort, és hogyan adhat hozzá üzeneteket aszinkron .NET-kóddal. Ezután megtanulta betekinteni, lekérni és törölni az üzeneteket. Végül megtanulta, hogyan törölhet egy üzenetsort.

Oktatóanyagok, minták, rövid útmutatók és egyéb dokumentációk:

Azure .NET- és .NET Core-fejlesztőknek