Share via

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

  • مقالة

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

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

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

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

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

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

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

تحديث ضبط الإعدادات القائم على النشاط

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

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(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، يُسجَّل مفتاح داخل متجر إعدادات التطبيق لمراقبة التغييرات. يحتوي الأسلوب Registerعلى معلمة متغير منطقي اختياري يمكن refreshAll استخدامها للإشارة إلى ما إذا كان يجب تحديث كافة قيم الإعدادات إذا تغير المفتاح المسجل. في هذا المثال، سيتم تحديث TestApp:Settings:Message الرئيسي فقط. SetCacheExpirationيحدد الأسلوب الحد الأدنى من الوقت الذي يجب أن ينقضي قبل إجراء طلب جديد إلى App Configuration للتحقق من أي تغييرات في التكوين. في هذا المثال، تجاوزت وقت انتهاء الصلاحية الافتراضي وهو 30 ثانية، مع تحديد وقت قدره 10 ثوانٍ بدلاً من ذلك لأغراض العرض التوضيحي.

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

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

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

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

    أضف التعليمات البرمجية التالية إلى Program.cs.

    // Existing code in Program.cs
// ... ...

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

  2. قم بتحديث التكوين الخاص بك عن طريق حل مثيل من 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();
        }
    }
}

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

  1. تعيين environment variable يُسمَّى ConnectionString، وتعيينه إلى مفتاح الوصول إلى متجر App Configuration. إذا كنت تستخدم موجه الأوامر Windows، فشغل الأمر التالي، ثم أعد تشغيل موجه الأوامر للسماح للتغيير بتنفيذ الأمر:

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

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

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

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

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

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

     dotnet build

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

     dotnet run

    Quickstart app launch local

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

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

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

  6. اضغط على مفتاح Enter لتشغيل التحديث وطباعة القيمة المحدثة في نافذة موجه الأوامر أو PowerShell.

    Quickstart app refresh local

    إشعار

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

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

يتم إخراج السجلات عند تحديث التكوين وتحتوي على معلومات مفصلة حول قيم المفاتيح التي تم استردادها من متجر 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

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

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

هام

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

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

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

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

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

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