Tutorial: Menggunakan konfigurasi dinamis di aplikasi .NET
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 memanggilTryRefreshAsync
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.
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 menentukanEventLevel.Verbose
parameter, seperti yang dilakukan dalam contoh berikut. Instruksi ini juga berlaku untuk semua tingkat peristiwa lainnya. Contoh ini juga memungkinkan log hanyaMicrosoft-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.