البرنامج التعليمي: العمل باستخدام قوائم انتظار Azure Queue Storage في .NET

مقالة
08/08/2024

يبادر Azure Queue Storage بتنفيذ قوائم الانتظار المستندة إلى السحابة لتمكين الاتصال بين مكونات تطبيق موزع. تحتفظ كل قائمة انتظار بقائمة رسائل يمكن إضافتها بواسطة مكون مرسل ومعالجتها بواسطة مكون مستقبل. باستخدام قائمة انتظار، يمكن توسيع تطبيقك على الفور ليفي بالمتطلبات. تعرض هذه المقالة الخطوات الأساسية للعمل باستخدام قائمة انتظار Azure Queue Storage.

في هذا البرنامج التعليمي، تتعلم كيفية:

إنشاء حساب تخزين Azure
إنشاء التطبيق
إضافة مكتبات عميل Azure
إضافة دعم للتعليمات البرمجية غير المتزامنة
إنشاء ‏‫‏‏قائمة انتظار‬
إدراج رسائل في قائمة انتظار
إلغاء ترتيب الرسائل
حذف قائمة انتظار فارغة
التحقق من وجود وسيطات سطر الأوامر
إنشاء وتشغيل التطبيق

المتطلبات الأساسية

احصل على نسختك المجانية من محرر Visual Studio Code عبر النظام الأساسي.
بادر بتنزيل وتثبيت .NET Core SDK الإصدار 3.1 أو أحدث.
في حال لم يكن لديك اشتراك Azure حالي، يُمكنك إنشاء حساب مجاني قبل البدء.

إنشاء حساب تخزين Azure

أولاً، قم بإنشاء حساب تخزين Azure.

للحصول على دليل خطوة بخطوة لإنشاء حساب تخزين، راجع إنشاء حساب تخزين. هذه خطوة منفصلة تقوم بتنفيذها بعد إنشاء حساب Azure مجاني في المتطلبات الأساسية.
تأكد من تعيين دور مساهم بيانات قائمة انتظار التخزين لحساب المستخدم الخاص بك، أو تحديد نطاقه لحساب التخزين، أو مجموعة الموارد الأصل، أو الاشتراك. راجع المصادقة على Azure.

إنشاء التطبيق

أنشئ تطبيق .NET Core يسمى QueueApp. للتبسيط، سيرسل هذا التطبيق الرسائل ويستقبلها عبر قائمة الانتظار.

في نافذة وحدة تحكم (مثل cmd أو PowerShell أو Azure CLI) استخدم الأمر dotnet new⁩ لإنشاء تطبيق وحدة تحكم جديد يحمل الاسم ⁧QueueApp⁩. يُنشئ هذا الأمر مشروع "hello world" C# بسيطاً مع ملف مصدر واحد يسمى Program.cs.
```
dotnet new console -n QueueApp
```

قم بالتبديل إلى المجلد الذي تم إنشاؤه QueueApp حديثا وأنشئ التطبيق للتحقق من أن كل شيء على ما يرام.

cd QueueApp

dotnet build

ينبغي أن ترى نتائج مشابهة للإخراج التالي:

C:\Tutorials>dotnet new console -n QueueApp
The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on QueueApp\QueueApp.csproj...
  Restore completed in 155.63 ms for C:\Tutorials\QueueApp\QueueApp.csproj.

Restore succeeded.

C:\Tutorials>cd QueueApp

C:\Tutorials\QueueApp>dotnet build
Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 40.87 ms for C:\Tutorials\QueueApp\QueueApp.csproj.
  QueueApp -> C:\Tutorials\QueueApp\bin\Debug\netcoreapp3.1\QueueApp.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:02.40

C:\Tutorials\QueueApp>_

إضافة مكتبات عميل Azure

أضف مكتبات عميل Azure Storage إلى المشروع باستخدام الأمر dotnet add package.

يمكنك تشغيل الأمر التالي من مجلد المشروع في نافذة وحدة التحكم.
```
dotnet add package Azure.Storage.Queues
```

الإضافة عبارات الاستخدام

من سطر الأوامر في دليل المشروع، اكتب code . لفتح Visual Studio Code في الدليل الحالي. اترك نافذة سطر الأوامر مفتوحة. سيكون هناك المزيد من الأوامر لتشغيلها لاحقًا. إذا تمت مطالبتك بإضافة أصول C# المطلوبة للبناء وتصحيح الأخطاء، فانقر فوق الزر نعم.
افتح الملف المصدر Program.cs وأضف مساحات الأسماء التالية مباشرة بعد العبارة using System;. يستخدم هذا التطبيق أنواعًا من مساحات الأسماء هذه للاتصال بـ Azure Storage والعمل باستخدام قوائم الانتظار.
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
احفظ الملف Program.cs.

إضافة دعم للتعليمات البرمجية غير المتزامنة

نظرًا لأن التطبيق يستخدم موارد السحابة، يتم تشغيل التعليمات البرمجية بشكل غير متزامن.

حدّث أسلوب Main للتشغيل بشكل غير متزامن. استبدل void بالقيمة المرتجعة async Task.
```
static async Task Main(string[] args)
```
احفظ الملف Program.cs.

إنشاء ‏‫‏‏قائمة انتظار‬

قبل إجراء أي استدعاءات إلى واجهات برمجة تطبيقات Azure، يجب التأكد من مصادقتك باستخدام نفس حساب Microsoft Entra الذي قمت بتعيين الدور له. بمجرد المصادقة، يمكنك إنشاء عنصر QueueClient وتخويله باستخدام DefaultAzureCredential للوصول إلى بيانات قائمة الانتظار في حساب التخزين. DefaultAzureCredential يكتشف الحساب الذي سجلت الدخول إليه ويستخدمه تلقائيا. لمعرفة كيفية تسجيل الدخول ثم إنشاء كائن QueueClient ، راجع تخويل الوصول وإنشاء كائن عميل.

إدراج رسائل في قائمة الانتظار

أنشئ أسلوب جديد لإرسال رسالة إلى قائمة الانتظار.

أضف أسلوب InsertMessageAsync التالي إلى فئة Program.

يتم تمرير هذا الأسلوب إلى مرجع قائمة انتظار. يتم إنشاء قائمة انتظار جديدة، إذا لم تكن موجودة بالفعل، عن طريق استدعاء CreateIfNotExistsAsync. ثم، يضيف newMessage إلى قائمة الانتظار عن طريق استدعاء SendMessageAsync.
```
static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
{
    if (null != await theQueue.CreateIfNotExistsAsync())
    {
        Console.WriteLine("The queue was created.");
    }

    await theQueue.SendMessageAsync(newMessage);
}
```
اختياري: يبلغ الحد الأقصى لمدة حياة الرسالة سبعة أيام بشكل افتراضي. يمكن تحديد أي رقم موجب لوقت بقاء الرسالة. تضيف قصاصة التعليمات البرمجية التالية رسالة لا تنتهي صلاحيتها أبدًا.

لإضافة رسالة لا تنتهي صلاحيتها، استخدم Timespan.FromSeconds(-1) في مكالمتك لـ SendMessageAsync.
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
حفظ الملف.

يجب أن تكون رسالة قائمة الانتظار بتنسيق متوافق مع طلب XML باستخدام ترميز UTF-8. يمكن أن يصل حجم الرسالة إلى 64 كيلوبايت. إذا كانت الرسالة تحتوي على بيانات ثنائية، فبادر بترميز الرسالة باستخدام Base64.

إلغاء ترتيب الرسائل

أنشئ أسلوب جديد لاسترداد رسالة من قائمة الانتظار. بمجرد تلقي الرسالة بنجاح، من المهم حذفها من قائمة الانتظار حتى لا تتم معالجتها أكثر من مرة.

أضف أسلوب جديد يسمى RetrieveNextMessageAsync إلى فئة Program.

يتلقى هذا الأسلوب رسالة من قائمة الانتظار عن طريق استدعاء ReceiveMessagesAsync، وتمرير 1 في المعلمة الأولى لاسترداد الرسالة التالية فقط في قائمة الانتظار. بعد تلقي الرسالة، احذفها من قائمة الانتظار عن طريق استدعاء DeleteMessageAsync.

عندما يتم إرسال رسالة إلى قائمة الانتظار بإصدار من SDK قبل v12، يتم تلقائيا ترميزها باستخدام Base64. تمت إزالة هذه الوظيفة بدءًا من v12. عند استرداد رسالة باستخدام SDK v12، فإنه لا يتم فك ترميزها تلقائيًا باستخدام Base64. يجب أن تبادر بفك ترميز المحتويات باستخدام Base64 بنفسك.
```
static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
{
    if (await theQueue.ExistsAsync())
    {
        QueueProperties properties = await theQueue.GetPropertiesAsync();

        if (properties.ApproximateMessagesCount > 0)
        {
            QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
            string theMessage = retrievedMessage[0].Body.ToString();
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }

        return null;
    }

    return null;
}
```
حفظ الملف.

حذف قائمة انتظار فارغة

إنها أفضل ممارسة في نهاية المشروع أن تحدد ما إذا كنت لا تزال تحتاج الموارد التي أنشأتها. الموارد المتبقية قيد التشغيل يمكن أن تكلفك المال. إذا كانت قائمة الانتظار موجودة ولكنها فارغة، فاسأل المستخدم ما إذا كان يرغب في حذفها.

بادر بتوسيع أسلوب RetrieveNextMessageAsync لتضمين مطالبة لحذف قائمة الانتظار الفارغة.

static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
{
    if (await theQueue.ExistsAsync())
    {
        QueueProperties properties = await theQueue.GetPropertiesAsync();

        if (properties.ApproximateMessagesCount > 0)
        {
            QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
            string theMessage = retrievedMessage[0].Body.ToString();
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }
        else
        {
            Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
            string response = Console.ReadLine();

            if (response.ToUpper() == "Y")
            {
                await theQueue.DeleteIfExistsAsync();
                return "The queue was deleted.";
            }
            else
            {
                return "The queue was not deleted.";
            }
        }
    }
    else
    {
        return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
    }
}

حفظ الملف.

التحقق من وجود وسيطات سطر الأوامر

إذا كانت هناك أي وسيطات سطر أوامر تم تمريرها إلى التطبيق، افترض أنها رسالة يمكن إضافتها إلى قائمة الانتظار. بادر بضم الوسيطات معًا لإنشاء سلسلة. أضف هذه السلسلة إلى قائمة انتظار الرسائل عن طريق استدعاء أسلوب InsertMessageAsync الذي أضفناه سابقًا.

إذا لم تكن هناك وسيطات سطر أوامر، حاول استرداد العملية. بادر باستدعاء أسلوب RetrieveNextMessageAsync لاسترداد الرسالة التالية في قائمة الانتظار.

وأخيرًا، انتظر إدخال المستخدم قبل الخروج عن طريق استدعاء Console.ReadLine.

بادر بتوسيع أسلوب Main للتحقق من وجود وسيطات سطر الأوامر وانتظر إدخال المستخدم. في مقتطف التعليمات البرمجية أدناه، تأكد من استبدال {storageAccountName} العنصر النائب باسم حساب التخزين الخاص بك.

static async Task Main(string[] args)
{
   QueueClient queue = new QueueClient(
      new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
      new DefaultAzureCredential());

   if (args.Length > 0)
   {
      string value = String.Join(" ", args);
      await InsertMessageAsync(queue, value);
      Console.WriteLine($"Sent: {value}");
   }
   else
   {
      string value = await RetrieveNextMessageAsync(queue);
      Console.WriteLine($"Received: {value}");
   }

   Console.Write("Press Enter...");
   Console.ReadLine();
}

حفظ الملف.

تعليمة برمجية كاملة

إليك قائمة التعليمات البرمجية الكاملة لهذا المشروع.

using System;
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using Azure.Identity;

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            QueueClient queue = new QueueClient(
               new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
               new DefaultAzureCredential());

            if (args.Length > 0)
            {
                string value = String.Join(" ", args);
                await InsertMessageAsync(queue, value);
                Console.WriteLine($"Sent: {value}");
            }
            else
            {
                string value = await RetrieveNextMessageAsync(queue);
                Console.WriteLine($"Received: {value}");
            }

            Console.Write("Press Enter...");
            Console.ReadLine();
        }

        static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
        {
            if (null != await theQueue.CreateIfNotExistsAsync())
            {
                Console.WriteLine("The queue was created.");
            }

            await theQueue.SendMessageAsync(newMessage);
        }

        static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
        {
            if (await theQueue.ExistsAsync())
            {
                QueueProperties properties = await theQueue.GetPropertiesAsync();

                if (properties.ApproximateMessagesCount > 0)
                {
                    QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
                    string theMessage = retrievedMessage[0].Body.ToString();
                    await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                    return theMessage;
                }
                else
                {
                    Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
                    string response = Console.ReadLine();

                    if (response.ToUpper() == "Y")
                    {
                        await theQueue.DeleteIfExistsAsync();
                        return "The queue was deleted.";
                    }
                    else
                    {
                        return "The queue was not deleted.";
                    }
                }
            }
            else
            {
                return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
            }
        }
    }
}

إنشاء وتشغيل التطبيق

من سطر الأوامر في دليل المشروع، بادر بتشغيل أمر dotnet التالي لبناء المشروع.
```
dotnet build
```
بعد بناء المشروع بنجاح، بادر بتشغيل الأمر التالي لإضافة الرسالة الأولى إلى قائمة الانتظار.
```
dotnet run First queue message
```
ينبغي لك أن تشاهد هذا الإخراج:
```
C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter..._
```
يمكنك تشغيل التطبيق بدون وسيطات سطر الأوامر لتلقي وإزالة الرسالة الأولى في قائمة الانتظار.
```
dotnet run
```

تابع تشغيل التطبيق حتى تتم إزالة جميع الرسائل. إذا قمت بتشغيله مرة أخرى، فستحصل على رسالة مفادها أن قائمة الانتظار فارغة ومطالبة بحذف قائمة الانتظار.

C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run Second queue message
Sent: Second queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run Third queue message
Sent: Third queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: First queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: Second queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: Third queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
The queue is empty. Attempt to delete it? (Y/N) Y
Received: The queue was deleted.
Press Enter...

C:\Tutorials\QueueApp>_

الخطوات التالية

في هذا البرنامج التعليمي، نتعلم طريقة القيام بما يأتي:

إنشاء ‏‫‏‏قائمة انتظار‬
إضافة الرسائل وإزالتها من قائمة انتظار
حذف قائمة انتظار Azure Queue Storage

تحقق من قوالب التشغيل السريع لـ Azure Queue Storage للحصول على مزيد من المعلومات.

التشغيل السريع لقوائم الانتظار للمدخل

للحصول على نماذج التعليمات البرمجية ذات الصلة باستخدام حزم SDK للإصدار 11.x من .NET المهملة، راجع نماذج التعليمات البرمجية باستخدام .NET الإصدار 11.x.

مشاركة عبر