البرنامج التعليمي: استخدام التكوين الديناميكي باستخدام تحديث الدفع في تطبيق .NET

تدعم مكتبة عميل App Configuration .NET تحديث التكوين عند الطلب دون التسبب في إعادة تشغيل التطبيق. يمكن تكوين تطبيق للكشف عن التغييرات في App Configuration باستخدام أحد النهجين التاليين أو كليهما.

1. نموذج الاستقصاء: هذا هو السلوك الافتراضي الذي يستخدم الاستقصاء للكشف عن التغييرات في التكوين. بمجرد انتهاء صلاحية قيمة الإعداد المخزنة مؤقتًا، يرسل الاستدعاء التالي إلى TryRefreshAsync أو RefreshAsync طلبا للخادم للتحقق مما إذا كان قد حدث تغير في التكوين، وسحب التكوين المحدثة إذا لزم الأمر.

2. نموذج الإرسال: يستخدم هذا النموذج أحداث App Configuration للكشف عن التغييرات في التكوين. بمجرد إعداد App Configuration لإرسال أحداث تغيير القيمة الرئيسية إلىAzure Event Grid، يمكن للتطبيق استخدام هذه الأحداث لتحسين عدد الطلبات الإجمالي اللازمة للحفاظ على تحديث التكوين. يمكن للتطبيقات اختيار الاشتراك في هذه إما مباشرة من Event Grid أو من خلال أحد معالجات الأحداث المعتمدة مثل webhook أو Azure function أو موضوع Service Bus.

يوضح هذا البرنامج التعليمي كيف يمكنك تنفيذ تحديثات التكوين الديناميكية في التعليمات البرمجية باستخدام تحديث الإرسال. وهو يعتمد على التطبيق المقدم في البرنامج التعليمي. قبل المتابعة، قم بإنهاء البرنامج التعليمي: استخدم التكوين الديناميكي في تطبيق .NET أولا.

يمكنك استخدام أي محرر تعليمات برمجية للقيام بالخطوات الواردة في هذا البرنامج التعليمي. يعد Visual Studio Code خيارًا ممتازًا متاحًا على أنظمة التشغيل Windows، وmacOS، وLinux.

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

• إعداد اشتراك لإرسال أحداث تغيير التكوين من App Configuration إلى موضوعService Bus
• قم بإعداد تطبيق .NET لتحديث تكوينه استجابة للتغييرات في تكوين التطبيق.
• استخدم أحدث تكوين في التطبيق الخاص بك.

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

• البرنامج التعليمي: استخدام التكوين الديناميكي في تطبيق .NET
• حزمة NuGet Microsoft.Extensions.Configuration.AzureAppConfiguration الإصدار 5.0.0 أو أحدث

إعداد موضوع واشتراك Azure Service Bus

يستخدم هذا البرنامج التعليمي تكامل Service Bus لـ Event Grid لتبسيط الكشف عن التغييرات في التكوين للتطبيقات التي لا ترغب في استقصاء App Configuration للتغييرات بشكل مستمر. يوفر Azure Service Bus SDK واجهة برمجة تطبيقات لتسجيل معالج رسائل يمكن استخدامه لتحديث التكوين عند الكشف عن التغييرات في App Configuration. اتبع الخطوات الواردة في التشغيل السريع: استخدم مدخل Microsoft Azure لإنشاء موضوع ناقل خدمة Microsoft Azure والاشتراك لإنشاء مساحة اسم ناقل خدمة وموضوع واشتراك.

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

مفتاح	القيمة
ServiceBusConnectionString	سلسلة الاتصال لمساحة اسم Service Bus
ServiceBusTopic	اسم موضوع Service Bus
ServiceBusSubscription	اسم اشتراك Service Bus

إعداد اشتراك حدث

1. افتح مورد App Configuration في مدخل Azure، ثم انقر فوق + Event Subscription في جزء Events.

   

2. أدخل اسمًا لـ Event Subscription وSystem Topic.

   

3. حدد Endpoint Type كـ Service Bus Topic، اختر موضوع Service Bus، ثم انقر فوق Confirm Selection.

   

4. انقر على Create لإنشاء اشتراك الحدث.

5. انقر فوق Event Subscriptions في جزء Events للتحقق من أن الاشتراك تم إنشاؤه بنجاح.

   

إشعار

عند الاشتراك في تغييرات التكوين، يمكن استخدام عامل تصفية واحد أو أكثر لتقليل عدد الأحداث المرسلة إلى تطبيقك. يمكن تكوينها إما كعوامل تصفية اشتراك Event Grid أو كعوامل تصفية الاشتراك Service Bus. على سبيل المثال، يمكن استخدام عامل تصفية اشتراك فقط للاشتراك في الأحداث للتغييرات في مفتاح يبدأ بسلسلة محددة.

تسجيل معالج الأحداث لإعادة تحميل البيانات من App Configuration

افتح Program.cs وحدث الملف باستخدام التعليمات البرمجية التالية.

using Azure.Messaging.EventGrid;
using Azure.Messaging.ServiceBus;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration.Extensions;
using System;
using System.Threading.Tasks;

namespace TestConsole
{
    class Program
    {
        private const string AppConfigurationConnectionStringEnvVarName = "AppConfigurationConnectionString";
        // e.g. Endpoint=https://{store_name}.azconfig.io;Id={id};Secret={secret}
        
        private const string ServiceBusConnectionStringEnvVarName = "ServiceBusConnectionString";
        // e.g. Endpoint=sb://{service_bus_name}.servicebus.windows.net/;SharedAccessKeyName={key_name};SharedAccessKey={key}
        
        private const string ServiceBusTopicEnvVarName = "ServiceBusTopic";
        private const string ServiceBusSubscriptionEnvVarName = "ServiceBusSubscription";

        private static IConfigurationRefresher _refresher = null;

        static async Task Main(string[] args)
        {
            string appConfigurationConnectionString = Environment.GetEnvironmentVariable(AppConfigurationConnectionStringEnvVarName);

            IConfiguration configuration = new ConfigurationBuilder()
                .AddAzureAppConfiguration(options =>
                {
                    options.Connect(appConfigurationConnectionString);
                    options.ConfigureRefresh(refresh =>
                        refresh
                            .Register("TestApp:Settings:Message")
                            // Important: Reduce poll frequency
                            .SetCacheExpiration(TimeSpan.FromDays(1))  
                    );

                    _refresher = options.GetRefresher();
                }).Build();

            await RegisterRefreshEventHandler();
            var message = configuration["TestApp:Settings:Message"];
            Console.WriteLine($"Initial value: {configuration["TestApp:Settings:Message"]}");

            while (true)
            {
                await _refresher.TryRefreshAsync();

                if (configuration["TestApp:Settings:Message"] != message)
                {
                    Console.WriteLine($"New value: {configuration["TestApp:Settings:Message"]}");
                    message = configuration["TestApp:Settings:Message"];
                }

                await Task.Delay(TimeSpan.FromSeconds(1));
            }
        }

        private static async Task RegisterRefreshEventHandler()
        {
            string serviceBusConnectionString = Environment.GetEnvironmentVariable(ServiceBusConnectionStringEnvVarName);
            string serviceBusTopic = Environment.GetEnvironmentVariable(ServiceBusTopicEnvVarName);
            string serviceBusSubscription = Environment.GetEnvironmentVariable(ServiceBusSubscriptionEnvVarName); 
            ServiceBusClient serviceBusClient = new ServiceBusClient(serviceBusConnectionString);
            ServiceBusProcessor serviceBusProcessor = serviceBusClient.CreateProcessor(serviceBusTopic, serviceBusSubscription);

            serviceBusProcessor.ProcessMessageAsync += (processMessageEventArgs) =>
            {
                // Build EventGridEvent from notification message
                EventGridEvent eventGridEvent = EventGridEvent.Parse(BinaryData.FromBytes(processMessageEventArgs.Message.Body));

                // Create PushNotification from eventGridEvent
                eventGridEvent.TryCreatePushNotification(out PushNotification pushNotification);

                // Prompt Configuration Refresh based on the PushNotification
                _refresher.ProcessPushNotification(pushNotification);

                return Task.CompletedTask;
            };

            serviceBusProcessor.ProcessErrorAsync += (exceptionargs) =>
            {
                Console.WriteLine($"{exceptionargs.Exception}");
                return Task.CompletedTask;
            };

            await serviceBusProcessor.StartProcessingAsync();
        }
    }
}

يعيد الأسلوب ProcessPushNotification تعيين انتهاء صلاحية ذاكرة التخزين المؤقت إلى تأخير عشوائي قصير. يؤدي هذا إلى استدعاءات مستقبلية إلى RefreshAsync أو TryRefreshAsync لإعادة التحقق من صحة القيم المخزنة مؤقتا مقابل تكوين التطبيق وتحديثها حسب الضرورة. في هذا المثال، تقوم بالتسجيل لمراقبة التغييرات على المفتاح: TestApp:Settings:Message مع انتهاء صلاحية ذاكرة التخزين المؤقت ليوم واحد. وهذا يعني أنه لن يتم تقديم أي طلب إلى App Configuration قبل مرور يوم على آخر فحص. عن طريق استدعاء ProcessPushNotification، سيرسل التطبيق الخاص بك الطلبات إلى تكوين التطبيق في الثواني القليلة القادمة. سيقوم التطبيق الخاص بك بتحميل قيم التكوين الجديدة بعد وقت قصير من حدوث التغييرات في المتجر App Configuration دون الحاجة إلى الاستقصاء باستمرار عن التحديثات. في حالة فات تطبيقك إعلام التغيير لأي سبب من الأسباب، فإنه سيظل يتحقق من تغييرات التكوين مرة واحدة في اليوم.

يعد التأخير العشوائي القصير لانتهاء صلاحية ذاكرة التخزين المؤقت مفيدًا إذا كان لديك العديد من مثيلات التطبيق أو الخدمات المصغرة المتصلة بنفس متجر App Configuration باستخدام نموذج الدفع. دون هذا التأخير، يمكن لجميع مثيلات التطبيق الخاص بك إرسال طلبات إلى متجر App Configuration في وقت واحد بمجرد تلقي إعلام التغيير. يمكن أن يؤدي هذا إلى تقييد App Configuration Service لمتجرك. يتم تعيين تأخير انتهاء صلاحية ذاكرة التخزين المؤقت إلى رقم عشوائي بين 0 و30 ثانية كحد أقصى بشكل افتراضي، ولكن يمكنك تغيير القيمة القصوى من خلال المعلمة maxDelay الاختيارية إلى الأسلوب ProcessPushNotification.

ProcessPushNotification يأخذ الأسلوب كائنا PushNotification يحتوي على معلومات حول التغيير في تكوين التطبيق الذي قام بتشغيل إعلام الدفع. يساعد هذا في ضمان تحميل جميع تغييرات التكوين حتى حدث التشغيل في تحديث التكوين التالي. SetDirty لا يضمن الأسلوب التغيير الذي يقوم بتشغيل الإعلام المنبثق ليتم تحميله في تحديث تكوين فوري. إذا كنت تستخدم الأسلوب SetDirty لنموذج الدفع، نوصي باستخدام الأسلوب ProcessPushNotification بدلاً من ذلك.

يوصى بإنشاء التطبيق وتشغيله محليًا

1. قم بتعيين متغير بيئة يسمى AppConfigurationConnectionString، وقم بتعيينه على مفتاح الوصول إلى متجر App Configuration الخاص بك.

   واجهة أوامر Windows

   لإنشاء التطبيق وتشغيله محليًا باستخدام موجه أوامر Windows، قم بتشغيل الأمر التالي ثم أعد تشغيل موجه الأوامر للسماح بالتغيير أن يدخل حيز التنفيذ:

   setx AppConfigurationConnectionString "connection-string-of-your-app-configuration-store"
   

   بوويرشيل

   إذا كنت تستخدم Windows PowerShell، فقم بإجراء الأمر التالي:

   $Env:AppConfigurationConnectionString = "connection-string-of-your-app-configuration-store"
   

   ماك

   إذا كنت تستخدم macOS، فقم بتشغيل الأمر التالي:

   export AppConfigurationConnectionString='connection-string-of-your-app-configuration-store'
   

   Linux

   إذا كنت تستخدم macOS، فقم بتشغيل الأمر التالي:

   export AppConfigurationConnectionString='connection-string-of-your-app-configuration-store'
   

2. يوصى بتشغيل الأمر التالي لإنشاء تطبيق وحدة التحكم:

   dotnet build
   

3. بعد إنجاز الإنشاء بنجاح، يُرجى تشغيل الأمر التالي لتشغيل التطبيق محليًا:

   dotnet run
   

   

4. قم بتسجيل الدخول إلى بوابة Azure. حدد "All resources"، وحدد مثيل متجر تكوين التطبيق الذي قمت بإنشائه في البداية السريعة.

5. حدد Configuration Explorer، ثم حدث قيم المفاتيح التالية:

   مفتاح	القيمة
   TestApp:الإعدادات:رسالة	بيانات من تكوين تطبيق Azure - مُحدَّثة

6. انتظر بضع لحظات للسماح بمعالجة الحدث. سترى التكوين المحدث.

   

تنظيف الموارد

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

هام

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

1. سجل الدخول إلى مدخل Microsoft Azure، وحدد Resource groups.
2. في المربع تصفية حسب الاسم ، أدخل اسم مجموعة الموارد الخاصة بك.
3. في قائمة النتائج، حدد اسم مجموعة الموارد لاستعراض نظرة عامة.
4. حدد Delete resource group.
5. يُطلب منك تأكيد حذف مجموعة الموارد. أدخل اسم مجموعة الموارد للتأكيد وحدد "Delete".

بعد بضع لحظات، يتم حذف مجموعة الموارد وكافة مواردها.

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

في هذا البرنامج التعليمي، قمت بتمكين تطبيق .NET لتحديث إعدادات التكوين ديناميكيا من App Configuration. لمعرفة كيفية استخدام هوية Azure المدارة لتبسيط الوصول إلى تكوين التطبيق، تابع البرنامج التعليمي التالي.

تكامل الهوية المدارة