Tutorial: Menggunakan bendera fitur di aplikasi ASP.NET Core

Artikel
02/28/2024

Pustaka Manajemen Fitur .NET menyediakan dukungan idiomatik untuk menerapkan bendera fitur dalam aplikasi .NET atau ASP.NET Core. Pustaka ini memungkinkan Anda untuk secara deklaratif menambahkan bendera fitur ke kode sehingga Anda tidak perlu menulis kode secara manual untuk mengaktifkan atau menonaktifkan fitur dengan pernyataan if.

Pustaka Feature Management juga mengelola siklus hidup bendera fitur di belakang layar. Misalnya, pustaka merefresh dan menyimpan status bendera, atau menjamin status bendera bersifat abadi selama panggilan permintaan. Selain itu, pustaka ASP.NET Core menawarkan integrasi secara langsung, termasuk tindakan pengontrol MVC, tampilan, rute, dan middleware.

Untuk dokumentasi referensi API manajemen fitur ASP.NET Core, lihat Namespace Layanan Microsoft.FeatureManagement.

Dalam tutorial ini, Anda akan belajar cara:

Tambahkan bendera fitur di bagian kunci aplikasi Anda untuk mengontrol ketersediaan fitur.
Integrasikan dengan Azure App Configuration saat Anda menggunakannya untuk mengelola bendera fitur.

Prasyarat

Tambahkan bendera fitur ke Mulai Cepat aplikasi ASP.NET Core menunjukkan contoh sederhana tentang cara menggunakan bendera fitur dalam aplikasi ASP.NET Core. Tutorial ini menunjukkan opsi persiapan tambahan dan kemampuan pustaka Manajemen Fitur. Anda dapat menggunakan aplikasi sampel yang dibuat dalam mulai cepat untuk mencoba kode sampel yang ditunjukkan dalam tutorial ini.

Menyiapkan manajemen fitur

Untuk mengakses pengelola fitur .NET, aplikasi Anda harus memiliki referensi ke Microsoft.Azure.AppConfiguration.AspNetCore paket NuGet dan Microsoft.FeatureManagement.AspNetCore .

Pengelola fitur .NET dikonfigurasi dari sistem konfigurasi asli kerangka kerja. Akibatnya, Anda dapat menentukan pengaturan bendera fitur aplikasi dengan menggunakan sumber konfigurasi apa pun yang didukung .NET, termasuk file lokal appsettings.json atau variabel lingkungan.

Secara default, pengelola fitur mengambil konfigurasi bendera fitur dari bagian "FeatureManagement" data konfigurasi .NET. Untuk menggunakan lokasi konfigurasi default, panggil metode AddFeatureManagement dari IServiceCollection yang diteruskan ke metode ConfigureServices dari kelas Startup.

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

Anda dapat menentukan bahwa konfigurasi manajemen fitur harus diambil dari bagian konfigurasi yang berbeda dengan memanggil Configuration.GetSection dan meneruskan nama bagian yang diinginkan. Contoh berikut ini memberi tahu pengelola fitur untuk membaca dari bagian lain yang disebut "MyFeatureFlags" sebagai gantinya:

using Microsoft.FeatureManagement;

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

Jika Anda menggunakan filter di bendera fitur, Anda harus menyertakan namespace Microsoft.FeatureManagement.FeatureFilters dan menambahkan panggilan ke AddFeatureFilter yang menentukan nama jenis filter yang ingin Anda gunakan sebagai jenis generik metode. Untuk mengetahui informasi selengkapnya tentang menggunakan filter fitur untuk mengaktifkan dan menonaktifkan fungsionalitas secara dinamis, lihat Mengaktifkan peluncuran bertahap fitur untuk audiens yang ditargetkan.

Contoh berikut menunjukkan cara menggunakan filter fitur bawaan yang disebut PercentageFilter:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement()
    .AddFeatureFilter<PercentageFilter>();

Daripada mengkodekan bendera fitur Anda ke dalam aplikasi, kami sarankan menyimpan bendera fitur di luar aplikasi dan mengelola bendera fitur secara terpisah. Dengan melakukan hal tersebut memungkinkan Anda untuk mengubah status bendera kapan saja dan membuat perubahan tersebut berlaku di aplikasi dengan segera. Layanan Azure App Configuration menyediakan UI portal khusus untuk mengelola semua bendera fitur Anda. Layanan Azure App Configuration juga mengirimkan bendera fitur ke aplikasi Anda secara langsung melalui pustaka klien .NET-nya.

Cara termudah untuk menyambungkan aplikasi ASP.NET Core Anda ke Azure App Configuration adalah melalui penyedia konfigurasi yang termasuk dalam paket Microsoft.Azure.AppConfiguration.AspNetCore NuGet. Setelah menyertakan referensi ke paket, ikuti langkah-langkah ini untuk menggunakan paket NuGet ini.

Buka file Program.cs dan tambahkan kode berikut.

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

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

Perbarui konfigurasi middleware dan layanan untuk aplikasi Anda menggunakan kode berikut.

program.cs Di dalam kelas , daftarkan layanan Azure App Configuration dan middleware pada builder objek dan app :
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

Dalam skenario umum, Anda akan memperbarui nilai bendera fitur secara berkala saat Anda menyebarkan dan mengaktifkan serta berbagai fitur aplikasi Anda. Secara default, nilai bendera fitur disimpan untuk jangka waktu 30 detik, sehingga operasi penyegaran yang dipicu ketika middleware menerima permintaan tidak akan memperbarui nilai sampai nilai yang disimpan kedaluwarsa. Kode berikut menunjukkan cara mengubah waktu kedaluwarsa cache atau interval poling menjadi 5 menit dengan mengatur CacheExpirationInterval dalam panggilan ke UseFeatureFlags.

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

Deklarasi bendera fitur

Masing-masing deklarasi bendera fitur memiliki dua bagian: nama dan daftar dari satu atau beberapa filter yang digunakan untuk mengevaluasi apakah status fitur aktif (artinya, saat nilai fitur True). Filter menentukan kriteria kapan fitur harus diaktifkan.

Saat bendera fitur memiliki beberapa filter, daftar filter dilewati secara berurutan hingga salah satu filter menentukan fitur harus diaktifkan. Pada titik tersebut, bendera fitur aktif, dan hasil filter yang tersisa dilewati. Jika tidak ada filter yang menunjukkan fitur harus diaktifkan, artinya bendera fitur nonaktif.

Manajer fitur mendukung appsettings.json sebagai sumber konfigurasi untuk bendera fitur. Contoh berikut menunjukkan cara menyiapkan bendera fitur dalam file JSON:

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

Menurut konvensi, bagian FeatureManagement dari dokumen JSON ini digunakan untuk pengaturan bendera fitur. Contoh sebelumnya menampilkan tiga bendera fitur dengan filter yang ditentukan dalam properti EnabledFor:

FeatureA adalah aktif.
FeatureB adalah nonaktif.
FeatureC menentukan filter bernama Percentage dengan properti Parameters. Percentage adalah filter yang dapat dikonfigurasi. Dalam contoh ini, Percentage menentukan peluang 50 persen agar bendera FeatureC menjadi aktif. Untuk panduan cara menggunakan filter fitur, lihat Menggunakan filter fitur untuk mengaktifkan bendera fitur kondisional.

Gunakan injeksi dependensi untuk mengakses IFeatureManager

Untuk beberapa operasi, seperti memeriksa nilai bendera fitur secara manual, Anda perlu mendapatkan instans IFeatureManager. Di MVC ASP.NET Core, Anda dapat mengakses pengelola fitur IFeatureManager melalui injeksi dependensi. Dalam contoh berikut, argumen jenis IFeatureManager ditambahkan ke tanda tangan konstruktor untuk pengontrol. Runtime secara otomatis menyelesaikan referensi dan menyediakan implementasi antarmuka saat memanggil konstruktor. Jika Anda menggunakan templat aplikasi di mana pengontrol sudah memiliki satu atau beberapa argumen injeksi dependensi di konstruktor, seperti ILogger, Anda dapat menambahkan IFeatureManager sebagai argumen tambahan:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

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

Referensi bendera fitur

Tentukan bendera fitur sebagai variabel string untuk mereferensikan bendera fitur dari kode:

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

Pemeriksaan bendera fitur

Pola umum manajemen fitur adalah untuk memeriksa apakah bendera fitur diatur ke aktif dan jika demikian, jalankan bagian kode. Misalnya:

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

Tindakan pengontrol

Dengan pengontrol MVC, Anda dapat menggunakan atribut FeatureGate untuk mengontrol apakah seluruh kelas pengontrol atau tindakan tertentu diaktifkan. Pengontrol HomeController berikut memerlukan FeatureA untuk aktif sebelum tindakan apa pun yang ada di kelas pengontrol dapat dijalankan:

using Microsoft.FeatureManagement.Mvc;

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

Tindakan Index berikut mengharuskan FeatureA untuk aktif sebelum dapat dijalankan:

using Microsoft.FeatureManagement.Mvc;

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

Ketika pengontrol atau tindakan MVC diblokir karena bendera fitur yang mengontrol adalah nonaktif, antarmuka yang didaftarkan IDisabledFeaturesHandler dipanggil. Antarmuka IDisabledFeaturesHandler default akan menampilkan kode status 404 ke klien tanpa isi respons.

Tampilan MVC

Buka _ViewImports.cshtml di direktori Tampilan, dan tambahkan pembantu tag pengelola fitur:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

Dalam tampilan MVC, Anda dapat menggunakan tag <feature> untuk merender konten berdasarkan apakah bendera fitur diaktifkan:

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

Untuk menampilkan konten alternatif saat persyaratan tidak terpenuhi, atribut negate dapat digunakan.

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

Tag fitur <feature> juga dapat digunakan untuk menampilkan konten jika salah satu atau semua fitur dalam daftar diaktifkan.

<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>

Filter MVC

Anda dapat menyiapkan filter MVC agar diaktifkan berdasarkan status bendera fitur. Kemampuan ini terbatas pada filter yang menerapkan IAsyncActionFilter. Kode berikut menambahkan filter MVC bernama ThirdPartyActionFilter. Filter ini dipicu dalam alur MVC hanya jika FeatureA diaktifkan.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

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

Middleware

Anda juga dapat menggunakan bendera fitur untuk menambahkan cabang aplikasi dan middleware secara kondisional. Kode berikut menyisipkan komponen middleware dalam alur permintaan hanya saat FeatureA diaktifkan:

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

Kode ini membangun kemampuan yang lebih umum untuk mencabangkan seluruh aplikasi berdasarkan bendera fitur:

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

Langkah berikutnya

Dalam tutorial ini, Anda mempelajari cara menerapkan bendera fitur di aplikasi ASP.NET Core Anda menggunakan pustaka Microsoft.FeatureManagement. Untuk mengetahui informasi selengkapnya tentang dukungan manajemen fitur di ASP.NET Core dan Azure App Configuration, lihat sumber daya berikut: