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

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

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

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

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

إنهاء التشغيل السريع: إنشاء تطبيق ASP.NET Core باستخدام App Configuration.

إعادة تحميل البيانات من App Configuration

1. افتح Program.cs، وقم بتحديث الأسلوب الذي AddAzureAppConfiguration أضفته أثناء التشغيل السريع. يمكنك الاتصال بتكوين التطبيق باستخدام معرف Microsoft Entra (مستحسن) أو سلسلة الاتصال. يوضح مقتطف التعليمات البرمجية التالي استخدام معرف Microsoft Entra.

   يمكنك استخدام DefaultAzureCredential للمصادقة على متجر App Configuration. أثناء إكمال التشغيل السريع المدرج في المتطلبات الأساسية، قمت بالفعل بتعيين بيانات الاعتماد الخاصة بك دور App Configuration Data Reader.

   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(new Uri(endpoint), new DefaultAzureCredential())
              // Load all keys that start with `TestApp:` and have no label.
              .Select("TestApp:*", LabelFilter.Null)
              // Reload configuration if any selected key-values have changed.
              .ConfigureRefresh(refreshOptions =>
                  refreshOptions.RegisterAll());
   });
   

   Select يتم استخدام الأسلوب لتحميل كافة قيم المفاتيح التي يبدأ اسم المفتاح بها TestApp: والتي لا تحتوي على تسمية. يمكنك استدعاء Select الأسلوب أكثر من مرة لتحميل التكوينات ببادئات أو تسميات مختلفة. إذا قمت بمشاركة متجر App Configuration واحد مع تطبيقات متعددة، فإن هذا الأسلوب يساعد على تحميل التكوين ذي الصلة بتطبيقك الحالي فقط بدلا من تحميل كل شيء من متجرك.

   ConfigureRefresh داخل الأسلوب، يمكنك استدعاء RegisterAll الأسلوب لإرشاد موفر تكوين التطبيق لإعادة تحميل التكوين بأكمله كلما اكتشف تغييرا في أي من قيم المفاتيح المحددة (تلك التي تبدأ ب TestApp: وليس لها تسمية). لمزيد من المعلومات حول مراقبة تغييرات التكوين، راجع أفضل الممارسات لتحديث التكوين.

   تلميح

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

2. أضف البرنامج الوسيط ل Azure App Configuration إلى مجموعة الخدمات لتطبيقك.

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

   // Existing code in Program.cs
   // ... ...
   
   builder.Services.AddRazorPages();
   
   // Add Azure App Configuration middleware to the container of services.
   builder.Services.AddAzureAppConfiguration();
   
   // Bind configuration "TestApp:Settings" section to the Settings object
   builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

3. UseAzureAppConfiguration استدعاء الأسلوب . فهو يمكن تطبيقك من استخدام البرنامج الوسيط App Configuration لتحديث التكوين لك تلقائيا.

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

   // Existing code in Program.cs
   // ... ...
   
   var app = builder.Build();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/Error");
       app.UseHsts();
   }
   
   // Use Azure App Configuration middleware for dynamic configuration refresh.
   app.UseAzureAppConfiguration();
   
   // The rest of existing code in program.cs
   // ... ...
   

لقد قمت بإعداد تطبيقك لاستخدام نمط الخيارات في ASP.NET Core أثناء التشغيل السريع. عند تحديث التكوين الأساسي لتطبيقك من App Configuration، يتم تحديث الكائن الذي Settings تم كتابته بقوة عبر IOptionsSnapshot<T> تلقائيا. لاحظ أنه لا يجب عليك استخدام IOptions<T> إذا كان تحديث التكوين الديناميكي مطلوبا لأنه لا يقرأ بيانات التكوين بعد بدء التطبيق.

تحديث التكوين المستند إلى الطلب

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

• إذا فشل طلب تكوين التطبيق للكشف عن التغيير، فسيستمر تطبيقك في استخدام التكوين المخزن مؤقتا. سيتم إجراء محاولات جديدة للتحقق من وجود تغييرات بشكل دوري أثناء وجود طلبات واردة جديدة لتطبيقك.
• يحدث تحديث التكوين بشكل غير متزامن لمعالجة الطلبات الواردة لتطبيقك. لن يمنع أو يبطئ الطلب الوارد الذي قام بتشغيل التحديث. قد لا يحصل الطلب الذي قام بتشغيل التحديث على قيم التكوين المحدثة، ولكن الطلبات اللاحقة ستحصل على قيم تكوين جديدة.
• لضمان تشغيل البرنامج الوسيط، قم باستدعاء app.UseAzureAppConfiguration() الأسلوب في أقرب وقت مناسب في مسار الطلب الخاص بك حتى لا يتخطى برنامج وسيط آخر ذلك في تطبيقك.

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

1. لإنشاء التطبيق باستخدام .NET CLI، قم بتشغيل الأمر التالي في الأمر shell:

       dotnet build
   

2. بعد اكتمال البناء بنجاح، قم بتشغيل الأمر التالي لتشغيل تطبيق الويب محلياً:

       dotnet run
   

3. افتح نافذة مستعرض، ثم انتقل إلى عنوان URL الموضح في dotnet run الإخراج.

   

4. قم بتسجيل الدخول إلى بوابة Azure. حدد All resources، وحدد App Configuration store الذي أنشأته في التشغيل السريع.

5. حدد مستكشف التكوين، وقم بتحديث قيم المفاتيح التالية.

   مفتاح	القيمة
   TestApp: الإعدادات: BackgroundColor	أخضر
   TestApp:الإعدادات:FontColor	رمادي فاتح
   TestApp:الإعدادات:رسالة	بيانات من Azure App Configuration - الآن مع تحديثات حية!

6. قم بتحديث المتصفح عدة مرات. عندما ينقضي الفاصل الزمني للتحديث بعد 30 ثانية، تظهر الصفحة مع محتوى محدث.

   

التسجيل والمراقبة

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

• تتم إضافة افتراضي ILoggerFactory تلقائيا عند services.AddAzureAppConfiguration() استدعاؤه. يستخدم موفر App Configuration هذا ILoggerFactory لإنشاء مثيل من ILogger، والذي يقوم بإخراج هذه السجلات. يستخدم ILogger ASP.NET Core للتسجيل بشكل افتراضي، لذلك لا تحتاج إلى إجراء تغييرات إضافية على التعليمات البرمجية لتمكين التسجيل لموفر App Configuration.

• يتم إخراج السجلات على مستويات سجل مختلفة. المستوى الافتراضي هو Information.

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

  يمكنك تمكين التسجيل على Debug مستوى السجل عن طريق إضافة المثال التالي إلى الملف.appsettings.json ينطبق هذا المثال على جميع مستويات السجل الأخرى أيضا.

  "Logging": {
      "LogLevel": {
          "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
      }
  }
  

• فئة التسجيل هي Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh، والتي تظهر قبل كل سجل. فيما يلي بعض الأمثلة على السجلات على كل مستوى سجل:

  dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'
  
  info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Setting updated. Key:'ExampleKey'
  
  warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      A refresh operation failed while resolving a Key Vault reference.
  Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.net/secrets/ExampleSecret'
  

استخدام ILogger هو الأسلوب المفضل في التطبيقات ASP.NET ويتم إعطاء الأولوية كمصدر تسجيل إذا كان مثيل ILoggerFactory موجود. ومع ذلك، إذا ILoggerFactory لم يكن متوفرا، يمكن تمكين السجلات وتكوينها بدلا من ذلك من خلال إرشادات تطبيقات .NET Core. لمزيد من المعلومات، راجع تسجيل الدخول إلى .NET Core و ASP.NET Core.

إشعار

يتوفر التسجيل إذا كنت تستخدم الإصدار 6.0.0 أو أحدث من أي من الحزم التالية.

• Microsoft.Extensions.Configuration.AzureAppConfiguration
• Microsoft.Azure.AppConfiguration.AspNetCore
• Microsoft.Azure.AppConfiguration.Functions.Worker

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

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

هام

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

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

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

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

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

الوصول إلى تكوين التطبيق باستخدام هوية مُدارة