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

مقالة
02/20/2024

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

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

للحصول على الوثائق المرجعية ASP.NET Core feature management API، راجع Microsoft.FeatureManagement Namespace.

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

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

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

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

إعداد إدارة الميزات

للوصول إلى مدير ميزات .NET، يجب أن يحتوي تطبيقك على مراجع إلى Microsoft.Azure.AppConfiguration.AspNetCore حزم و NuGet Microsoft.FeatureManagement.AspNetCore .

يتم تكوين مدير ميزات .NET من نظام التكوين الأصلي لإطار العمل. ونتيجة لذلك، يمكنك تعريف إعدادات علامة ميزة التطبيق الخاص بك باستخدام أي مصدر تكوين يدعم .NET، بما في ذلك الملف المحلي appsettings.json أو متغيرات البيئة.

بشكل افتراضي، يسترد مدير الميزات تكوين علامة الميزة من "FeatureManagement" قسم بيانات تكوين .NET. لاستخدام موقع التكوين الافتراضي، قم باستدعاء أسلوب AddFeatureManagement ل IServiceCollection الذي تم تمريره إلى أسلوب ConfigureServices لفئة بدء التشغيل .

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

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

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));

يمكنك استخدام عوامل تصفية الميزات لتمكين علامات الميزات الشرطية. لاستخدام عوامل تصفية الميزات المضمنة أو إنشاء ميزات خاصة بك، راجع تمكين الميزات الشرطية باستخدام عوامل تصفية الميزات.

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

أسهل طريقة لتوصيل تطبيق ASP.NET Core الخاص بك ب App Configuration هي من خلال موفر التكوين المضمن في حزمة Microsoft.Azure.AppConfiguration.AspNetCore NuGet. بعد تضمين مرجع إلى الحزمة اتبع الخطوات التالية لاستخدام حزمة NuGet هذه.

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

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
        .UseFeatureFlags());

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

program.cs داخل الفئة ، قم بتسجيل خدمات Azure App Configuration والبرامج الوسيطة على builder كائنات وapp:
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

في سيناريو نموذجي، سيتم تحديث قيم علامة الميزة بشكل دوري؛ لأنك تنشر وتمكن وميزات مختلفة للتطبيق الخاص بك. بشكل افتراضي، يتم تخزين قيم علامة الميزة مؤقتًا لمدة 30 ثانية؛ لذا فإن عملية التحديث التي يتم تشغيلها عند تلقي الوسيطة لطلب لن تقوم بتحديث القيمة حتى تنتهي صلاحية القيمة المخزنة مؤقتًا. توضح التعليمات البرمجية التالية كيفية تغيير وقت انتهاء صلاحية ذاكرة التخزين المؤقت أو الفاصل الزمني للاستقصاء إلى 5 دقائق عن طريق تعيين CacheExpirationInterval في استدعاء UseFeatureFlags.

config.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
            .UseFeatureFlags(featureFlagOptions => {
                featureFlagOptions.CacheExpirationInterval = TimeSpan.FromMinutes(5);
    }));

إعلان علامة الميزة

يحتوي كل إعلان علامة ميزة على جزأين: اسم وقائمة بعامل تصفية واحد أو أكثر يتم استخدامه لتقييم ما إذا كانت حالة الميزة قيد التشغيل (أي عندما تكون Trueقيمتها ). يحدد عامل التصفية معيارًا لموعد تشغيل ميزة.

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

يدعم مدير الميزات appsettings.json كمصدر تكوين لعلامات الميزات. يوضح المثال التالي كيفية إعداد علامات الميزة في ملف JSON:

{"FeatureManagement": {
        "FeatureA": true, // Feature flag set to on
        "FeatureB": false, // Feature flag set to off
        "FeatureC": {
            "EnabledFor": [
                {
                    "Name": "Percentage",
                    "Parameters": {
                        "Value": 50
                    }
                }
            ]
        }
    }
}

حسب الاصطلاح FeatureManagement ، يتم استخدام قسم من مستند JSON هذا لإعدادات علامة الميزة. يوضح المثال السابق ثلاث علامات ميزة مع عوامل التصفية الخاصة بها المعرفة في الخاصية EnabledFor :

FeatureAقيد التشغيل.
FeatureB متوقف عن التشغيل.
FeatureC يحدد عامل تصفية يسمى Percentage بخاصية Parameters . Percentage هو عامل تصفية قابل للتكوين. في هذا المثال، Percentage يحدد احتمال 50 بالمائة FeatureC للعلامة التي سيتم تشغيلها. للحصول على دليل إرشادي حول استخدام عوامل تصفية الميزات، راجع استخدام عوامل تصفية الميزات لتمكين علامات الميزة الشرطية.

استخدام إدخال التبعية للوصول إلى IFeatureManager

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

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

    public HomeController(ILogger<HomeController> logger, IFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

مراجع علامة الميزة

تعريف علامات الميز كمتغيرات سلسلة للإشارة إليها من التعليمات البرمجية:

public static class MyFeatureFlags
{
    public const string FeatureA = "FeatureA";
    public const string FeatureB = "FeatureB";
    public const string FeatureC = "FeatureC";
}

التحقق من علامة الميزة

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

IFeatureManager featureManager;
...
if (await featureManager.IsEnabledAsync(MyFeatureFlags.FeatureA))
{
    // Run the following code
}

إجراءات وحدة التحكم

باستخدام وحدات تحكم MVC، يمكنك استخدام السمة FeatureGate للتحكم في تمكين فئة وحدة تحكم كاملة أو إجراء معين. تتطلب FeatureA وحدة التحكم التالية HomeController أن تكون قيد التشغيل قبل تنفيذ أي إجراء تحتوي عليه فئة وحدة التحكم:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public class HomeController : Controller
{
    ...
}

يتطلب FeatureA الإجراء التالي Index أن يكون قيد التشغيل قبل تشغيله:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public IActionResult Index()
{
    return View();
}

عند حظر وحدة تحكم MVC أو إجراء بسبب إيقاف تشغيل علامة ميزة التحكم، يتم استدعاء واجهة IDisabledFeaturesHandler المسجلة. ترجع الواجهة الافتراضية IDisabledFeaturesHandler رمز حالة 404 إلى العميل بدون نص استجابة.

طرق عرض MVC

افتح _ViewImports.cshtml في دليل Views ، وأضف مساعد علامة مدير الميزات:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

في طرق عرض MVC، يمكنك استخدام <feature> علامة لعرض المحتوى استنادا إلى ما إذا كانت علامة الميزة ممكنة:

<feature name="FeatureA">
    <p>This can only be seen if 'FeatureA' is enabled.</p>
</feature>

لعرض محتوى بديل عند عدم استيفاء المتطلبات، يمكن استخدام السمة negate .

<feature name="FeatureA" negate="true">
    <p>This will be shown if 'FeatureA' is disabled.</p>
</feature>

يمكن أيضا استخدام علامة الميزة <feature> لإظهار المحتوى إذا تم تمكين أي من الميزات الموجودة في القائمة أو جميعها.

<feature name="FeatureA, FeatureB" requirement="All">
    <p>This can only be seen if 'FeatureA' and 'FeatureB' are enabled.</p>
</feature>
<feature name="FeatureA, FeatureB" requirement="Any">
    <p>This can be seen if 'FeatureA', 'FeatureB', or both are enabled.</p>
</feature>

مرشحات MVC

يمكنك إعداد فلاتر MVC بحيث يتم تنشيطها استنادًا إلى حالة علامة المعالم. تقتصر هذه الإمكانية على عوامل التصفية التي تنفذ IAsyncActionFilter. تضيف التعليمات البرمجية التالية عامل تصفية MVC المسمى ThirdPartyActionFilter. يتم تشغيل عامل التصفية هذا داخل مسار MVC فقط إذا FeatureA تم تمكينه.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options => {
        options.Filters.AddForFeature<ThirdPartyActionFilter>(MyFeatureFlags.FeatureA);
    });
}

البرامج الوسيطة

يمكنك أيضًا استخدام علامات الميز لإضافة فروع التطبيقات والبرامج الوسيطة بشكل مشروط. تدرج التعليمات البرمجية التالية مكون برنامج وسيط في مسار الطلب فقط عند FeatureA تمكين:

app.UseMiddlewareForFeature<ThirdPartyMiddleware>(MyFeatureFlags.FeatureA);

ينشئ هذا الرمز إيقاف القدرة الأكثر عمومية إلى فرع التطبيق بأكمله استنادًا إلى علامة ميزة:

app.UseForFeature(featureName, appBuilder => {
    appBuilder.UseMiddleware<T>();
});

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

في هذا البرنامج التعليمي، تعلمت كيفية تنفيذ علامات الميزات في تطبيق ASP.NET Core باستخدام Microsoft.FeatureManagement المكتبات. لمزيد من المعلومات حول دعم إدارة الميزات في ASP.NET Core و App Configuration، راجع الموارد التالية:

Share via