Tutorial: Menggunakan konfigurasi dinamis di aplikasi .NET

Artikel
02/20/2024

Pustaka penyedia .NET App Configuration mendukung pembaruan konfigurasi sesuai permintaan tanpa menyebabkan aplikasi dimulai ulang. Tutorial ini menunjukkan bagaimana Anda dapat menerapkan pembaruan konfigurasi dinamis dalam kode Anda. Tutorial ini dibangun pada aplikasi yang diperkenalkan di mulai cepat. Anda harus menyelesaikan Membuat aplikasi .NET dengan App Configuration sebelum melanjutkan.

Anda dapat menggunakan penyunting kode apa pun untuk melakukan langkah-langkah dalam tutorial ini. Visual Studio Code adalah opsi luar biasa yang tersedia di platform Windows, macOS, dan Linux.

Dalam tutorial ini, Anda akan mempelajari cara:

Siapkan aplikasi .NET Anda untuk memperbarui konfigurasinya sebagai respons terhadap perubahan di penyimpanan App Configuration.
Konsumsi konfigurasi terbaru di aplikasi Anda.

Prasyarat

Jika Anda tidak memiliki Langganan Azure, buat Akun gratis Azure sebelum memulai.

Selesaikan mulai cepat Buat aplikasi .NET dengan App Configuration.

Refresh konfigurasi berbasis aktivitas

Buka Program.cs dan perbarui file dengan kode berikut.

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!");

}

Dalam metode ConfigureRefresh, kunci dalam penyimpanan App Configuration Anda terdaftar untuk pemantauan perubahan. Metode Register memiliki parameter boolean opsional refreshAll yang dapat digunakan untuk menunjukkan apakah semua nilai konfigurasi harus di-refresh jika kunci terdaftar berubah. Dalam contoh ini, hanya kunci TestApp:Settings:Message yang akan di-refresh. Metode SetCacheExpiration ini menentukan waktu minimum yang harus berlalu sebelum permintaan baru dibuat ke App Configuration untuk memeriksa perubahan konfigurasi apa pun. Dalam contoh ini, Anda mengganti waktu kedaluwarsa default 30 detik, dengan menetapkan waktu 10 detik sebagai gantinya untuk tujuan demonstrasi.

Memanggil metode ConfigureRefresh saja tidak akan menyebabkan konfigurasi di-refresh secara otomatis. Anda memanggil metode TryRefreshAsync dari antarmuka IConfigurationRefresher untuk memicu refresh. Desain ini untuk menghindari permintaan yang dikirim ke App Configuration bahkan ketika aplikasi Anda menganggur. Anda mungkin ingin menyertakan TryRefreshAsync panggilan di mana Anda menganggap aplikasi Anda aktif. Misalnya, saat Anda memproses pesan masuk, pesanan, atau pengulangan tugas yang kompleks. Panggilan juga dapat berada dalam timer jika aplikasi Anda aktif sepanjang waktu. Dalam contoh ini, Anda memanggil TryRefreshAsync setiap kali Anda menekan tombol Enter. Bahkan jika panggilan TryRefreshAsync gagal karena alasan apa pun, aplikasi Anda terus menggunakan konfigurasi cache. Upaya lain dilakukan ketika waktu kedaluwarsa cache yang dikonfigurasi telah berlalu dan TryRefreshAsync panggilan dipicu oleh aktivitas aplikasi Anda lagi. Memanggil TryRefreshAsync tidak dapat dilakukan sebelum waktu kedaluwarsa cache yang dikonfigurasi berlalu, sehingga dampak performanya minimal, meskipun sering dipanggil.

Refresh konfigurasi menggunakan injeksi dependensi

Dalam kode sebelumnya, Anda menyimpan instans IConfigurationRefresher secara manual untuk memanggil TryRefreshAsync. Atau, jika Anda menggunakan injeksi dependensi untuk menyelesaikan layanan, Anda dapat mereferensikan langkah-langkah berikut.

Daftarkan layanan App Configuration yang diperlukan dengan memanggil AddAzureAppConfiguration di .IServiceCollection

Tambahkan kode berikut ke Program.cs.

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

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

Refresh konfigurasi Anda dengan menyelesaikan instans IConfigurationRefresherProvider dari koleksi layanan Anda dan memanggil TryRefreshAsync pada setiap penyegarannya.

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();
        }
    }
}

Membangun dan menjalankan aplikasi secara lokal

Set variabel lingkungan bernama ConnectionString, dan set ke kunci akses ke simpan Azure App Configuration Anda. Jika Anda menggunakan perintah Windows, jalankan perintah berikut dan hidupkan ulang perintah untuk memungkinkan perubahan berlaku:
```
 setx ConnectionString "connection-string-of-your-app-configuration-store"
```
Jika Anda menggunakan PowerShell Windows, jalankan perintah berikut:
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
Jika Anda menggunakan macOS atau Linux, jalankan perintah berikut:
```
 export ConnectionString='connection-string-of-your-app-configuration-store'
```
Jalankan perintah berikut untuk membuat aplikasi konsol:
```
 dotnet build
```
Setelah pembangunan berhasil diselesaikan, jalankan perintah berikut untuk menjalankan aplikasi secara lokal:
```
 dotnet run
```
Masuk ke portal Azure. Pilih Semua sumber daya, lalu pilih instans penyimpanan Azure App Configuration yang telah Anda buat di mulai cepat.
Pilih Konfigurasi Explorer, dan perbarui nilai kunci berikut:

Tombol Nilai

TestApp:Pengaturan:Pesan Data dari Azure App Configuration - Diperbarui
Tekan tombol Enter untuk memicu refresh, dan mencetak nilai yang diperbarui di jendela Perintah atau PowerShell.

Catatan

Karena waktu kedaluwarsa cache diatur ke 10 detik menggunakan metode SetCacheExpiration sambil menentukan konfigurasi untuk operasi penyegaran, nilai untuk pengaturan konfigurasi hanya akan diperbarui jika minimal 10 detik telah berlalu sejak penyegaran terakhir untuk pengaturan tersebut.

Tombol	Nilai
TestApp:Pengaturan:Pesan	Data dari Azure App Configuration - Diperbarui

Pengelogan dan pemantauan

Log adalah output setelah refresh konfigurasi dan berisi informasi terperinci tentang nilai kunci yang diambil dari penyimpanan App Configuration dan perubahan konfigurasi yang dibuat pada aplikasi Anda. Jika Anda memiliki aplikasi ASP.NET Core, lihat instruksi ini untuk Pengelogan dan Pemantauan di ASP.NET Core. Jika tidak, Anda dapat mengaktifkan pengelogan menggunakan instruksi untuk pengelogan dengan Azure SDK.

Log adalah output pada tingkat peristiwa yang berbeda. Tingkat default adalah Informational.

Tingkat Kejadian	Deskripsi
Verbose	Log menyertakan kunci dan label kunci-nilai yang dipantau aplikasi Anda untuk perubahan dari penyimpanan App Configuration Anda. Informasi ini juga mencakup apakah nilai kunci telah berubah dibandingkan dengan apa yang telah dimuat aplikasi Anda. Aktifkan log pada tingkat ini untuk memecahkan masalah aplikasi Anda jika perubahan konfigurasi tidak terjadi seperti yang diharapkan.
Informasi	Log menyertakan kunci pengaturan konfigurasi yang diperbarui selama refresh konfigurasi. Nilai pengaturan konfigurasi dihilangkan dari log untuk menghindari kebocoran data sensitif. Anda dapat memantau log pada tingkat ini untuk memastikan aplikasi Anda mengambil perubahan konfigurasi yang diharapkan.
Peringatan	Log mencakup kegagalan dan pengecualian yang terjadi selama refresh konfigurasi. Kejadian sesekali dapat diabaikan karena penyedia konfigurasi akan terus menggunakan data yang di-cache dan mencoba menyegarkan konfigurasi lain kali. Anda dapat memantau log pada tingkat ini untuk peringatan berulang yang mungkin menunjukkan potensi masalah. Misalnya, Anda memutar string koneksi tetapi lupa memperbarui aplikasi Anda.

Anda dapat mengaktifkan pengelogan di Verbose tingkat peristiwa dengan menentukan EventLevel.Verbose parameter, seperti yang dilakukan dalam contoh berikut. Instruksi ini juga berlaku untuk semua tingkat peristiwa lainnya. Contoh ini juga memungkinkan log hanya Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh untuk kategori.

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

Kategori pengelogan adalah Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, yang muncul sebelum setiap log. Berikut adalah beberapa contoh log di setiap tingkat peristiwa:

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

Catatan

Pengelogan tersedia jika Anda menggunakan versi 6.0.0 atau yang lebih baru dari salah satu paket berikut.

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

Membersihkan sumber daya

Jika Anda tidak ingin terus menggunakan sumber daya yang dibuat dalam artikel ini, hapus grup sumber daya yang Anda buat di sini untuk menghindari biaya.

Penting

Penghapusan grup sumber daya tidak bisa dipulihkan. Grup sumber daya dan semua sumber daya yang ada di dalamnya akan dihapus secara permanen. Pastikan Anda tidak menghapus grup atau sumber daya yang salah secara tidak sengaja. Jika Anda membuat sumber daya untuk artikel ini dalam grup sumber daya yang ada yang berisi sumber daya lain yang ingin disimpan, hapus setiap sumber daya satu per satu dari panelnya masing-masing, bukan menghapus grup sumber daya.

Masuk ke portal Azure, lalu pilih Grup sumber daya.
Dalam kotak Filter menurut nama, masukkan nama grup sumber daya Anda.
Dalam daftar hasil, pilih nama grup sumber daya untuk melihat gambaran umum.
Pilih Hapus grup sumber daya.
Anda akan diminta untuk mengonfirmasi penghapusan grup sumber daya. Masukkan nama grup sumber daya Anda untuk mengonfirmasi, dan pilih Hapus.

Setelah beberapa saat, grup sumber daya dan semua sumber dayanya akan dihapus.

Langkah berikutnya

Dalam tutorial ini, Anda mengaktifkan aplikasi .NET untuk menyegarkan pengaturan konfigurasi secara dinamis dari App Configuration. Untuk mempelajari cara menggunakan identitas terkelola Azure guna menyederhanakan akses ke App Configuration, lanjut ke tutorial berikutnya.

Integrasi identitas terkelola