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

مقالة
02/20/2024

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

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

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

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

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

قم بإضافة مفتاح الحارس

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

في مدخل Microsoft Azure، افتح متجر App Configuration وحدد Configuration Explorer > Create > Key-value.
لمفتاح، أدخل TestApp:Settings:Sentinel. ضمن Value، أدخل 1. اترك التسميةونوع المحتوى فارغين.
حدد تطبيق.

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

افتح Program.cs، وقم بتحديث الأسلوب الذي AddAzureAppConfiguration أضفته مسبقا أثناء التشغيل السريع.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString)
           // Load all keys that start with `TestApp:` and have no label
           .Select("TestApp:*", LabelFilter.Null)
           // Configure to reload configuration if the registered sentinel key is modified
           .ConfigureRefresh(refreshOptions =>
                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
});
```
Select يتم استخدام الأسلوب لتحميل كافة قيم المفاتيح التي يبدأ اسم المفتاح بها TestApp: والتي لا تحتوي على تسمية. يمكنك استدعاء Select الأسلوب أكثر من مرة لتحميل التكوينات ببادئات أو تسميات مختلفة. إذا قمت بمشاركة متجر App Configuration واحد مع تطبيقات متعددة، فإن هذا الأسلوب يساعد على تحميل التكوين ذي الصلة بتطبيقك الحالي فقط بدلا من تحميل كل شيء من متجرك.

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

تلميح

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

أضف البرنامج الوسيط ل 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
// ... ...

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 مفتاح sentinel أو أي مفاتيح أخرى قمت بتسجيلها للتحديث في ConfigureRefresh المكالمة. يتم تشغيل البرنامج الوسيط عند كل طلب وارد إلى تطبيقك. ومع ذلك، سوف تقوم البرامج الوسيطة بإرسال طلبات فقط للتحقق من القيمة في تكوين التطبيق عند مرور وقت انتهاء صلاحية ذاكرة التخزين المؤقت التي قمت بتعيينها.

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

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

لإنشاء التطبيق باستخدام .NET CLI، قم بتشغيل الأمر التالي في الأمر shell:
```
    dotnet build
```
بعد اكتمال البناء بنجاح، قم بتشغيل الأمر التالي لتشغيل تطبيق الويب محلياً:
```
    dotnet run
```
افتح نافذة مستعرض، ثم انتقل إلى عنوان URL الموضح في dotnet run الإخراج.
قم بتسجيل الدخول إلى بوابة Azure. حدد All resources، وحدد App Configuration store الذي أنشأته في التشغيل السريع.

حدد مستكشف التكوين، وقم بتحديث قيم المفاتيح التالية. تذكر تحديث مفتاح الحارس أخيرًا.

مفتاح	القيمة
TestApp:Settings:BackgroundColor	green
TestApp:Settings:FontColor	lightGray
TestApp:الإعدادات:رسالة	بيانات من Azure App Configuration - الآن مع تحديثات حية!
TestApp: الإعدادات: Sentinel	2

قم بتحديث المتصفح عدة مرات. عند انتهاء صلاحية ذاكرة التخزين المؤقت بعد 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

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

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

هام

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

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

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

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

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

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

Share via