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

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

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

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

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

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

إذا لم يكن لديك حساب Azure، فأنشئ حساباً مجانياً قبل أن تبدأ.

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

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

افتح Program.cs وقم بتحديث الملف بالتعليمات البرمجية التالية. يمكنك الاتصال بتكوين التطبيق باستخدام معرف Microsoft Entra (مستحسن) أو سلسلة الاتصال. يوضح مقتطف التعليمات البرمجية التالي استخدام معرف Microsoft Entra.

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

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(TimeSpan.FromSeconds(10));
           })

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

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

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

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

تحديث التكوين باستخدام إدخال التبعية

في التعليمات البرمجية السابقة، تقوم يدويا بحفظ مثيل IConfigurationRefresher لاستدعاء TryRefreshAsync. بدلا من ذلك، إذا كنت تستخدم إدخال التبعية لحل خدماتك، يمكنك الرجوع إلى الخطوات التالية.

قم بتسجيل خدمات App Configuration المطلوبة عن طريق استدعاء AddAzureAppConfiguration على .IServiceCollection

أضف التعليمات البرمجية التالية إلى Program.cs.
```
// Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();
```

قم بتحديث التكوين الخاص بك عن طريق حل مثيل من IConfigurationRefresherProvider مجموعة الخدمة الخاصة بك واستدعاء TryRefreshAsync على كل من التحديثات الخاصة به.

class SampleConfigRefresher
{
    private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;

    public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
    {
        _refreshers = refresherProvider.Refreshers;
    }

    public async Task RefreshConfiguration()
    {
        foreach (var refresher in _refreshers)
        {
            _ = refresher.TryRefreshAsync();
        }
    }
}

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

قم بتعيين متغير بيئة يسمى Endpoint إلى نقطة النهاية لمتجر App Configuration الموجود ضمن نظرة عامة على متجرك في مدخل Microsoft Azure.

إذا كنت تستخدم موجه الأوامر Windows، فشغل الأمر التالي، ثم أعد تشغيل موجه الأوامر للسماح للتغيير بتنفيذ الأمر:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
إذا كنت تستخدم PowerShell، فقم بتشغيل الأمر التالي:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
إذا كنت تستخدم macOS أو Linux، فقم بإجراء الأمر التالي:
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
يوصى بتشغيل الأمر التالي لإنشاء تطبيق وحدة التحكم:
```
 dotnet build
```
بعد إنجاز الإنشاء بنجاح، يُرجى تشغيل الأمر التالي لتشغيل التطبيق محليًا:
```
 dotnet run
```
قم بتسجيل الدخول إلى بوابة Azure. حدد All resources، وحدد مثيل متجر App Configuration الذي قمت بإنشائه في التشغيل السريع.
حدد Configuration Explorer، وقم بتحديث قيم المفاتيح التالية:

المفتاح القيمة

TestApp:الإعدادات:رسالة البيانات من Azure App Configuration - محدثة
اضغط على المفتاح Enter لتشغيل تحديث وطباعة القيمة المحدثة في نافذة موجه الأوامر أو PowerShell.

إشعار

نظرا لتعيين الفاصل الزمني للتحديث إلى 10 ثوان باستخدام SetRefreshInterval الأسلوب أثناء تحديد التكوين لعملية التحديث، سيتم تحديث قيمة إعداد التكوين فقط إذا انقضت 10 ثوان على الأقل منذ آخر تحديث لهذا الإعداد.

المفتاح	القيمة
TestApp:الإعدادات:رسالة	البيانات من Azure App Configuration - محدثة

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

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

يتم إخراج السجلات على مستويات أحداث مختلفة. المستوى الافتراضي هو Informational.

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

يمكنك تمكين التسجيل على Verbose مستوى الحدث عن طريق تحديد المعلمة EventLevel.Verbose ، كما هو الحال في المثال التالي. تنطبق هذه الإرشادات على جميع مستويات الأحداث الأخرى أيضا. يتيح هذا المثال أيضا سجلات للفئة Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh فقط.

using var listener = new AzureEventSourceListener((eventData, text) =>
{
    if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
    {
        Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
    }
}, EventLevel.Verbose);

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

[Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

[Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Setting updated. Key:'ExampleKey'

[Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
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'

إشعار

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

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

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

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

مهم

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

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

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

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

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-03-19