Tutorial: Gunakan konfigurasi dinamis dalam aplikasi ASP.NET Core

Tutorial ini menunjukkan cara Anda dapat mengaktifkan pembaruan konfigurasi dinamis dalam aplikasi ASP.NET Core. Ini dibangun di atas aplikasi web yang diperkenalkan dalam panduan cepat. Aplikasi Anda akan memanfaatkan library penyedia Konfigurasi Aplikasi untuk kemampuan penembolokan dan penyegaran konfigurasi bawaan. Sebelum Anda melanjutkan, selesaikan Create an ASP.NET Core app with App Configuration terlebih dahulu.

Dalam tutorial ini, Anda akan belajar cara:

Siapkan aplikasi Anda untuk memperbarui konfigurasinya sebagai respons terhadap perubahan di toko Konfigurasi Aplikasi.
Suntikkan konfigurasi terbaru ke aplikasi Anda.

Prasyarat

Selesaikan panduan cepat: Membuat aplikasi ASP.NET Core dengan Konfigurasi Aplikasi.

Muat Ulang Data dari Konfigurasi Aplikasi

Buka Program.cs, dan perbarui metode yang AddAzureAppConfiguration Anda tambahkan selama mulai cepat. Anda dapat terhubung ke App Configuration baik menggunakan Microsoft Entra ID (disarankan) atau string koneksi. Cuplikan kode berikut menunjukkan penggunaan Microsoft Entra ID.

Anda menggunakan DefaultAzureCredential untuk mengautentikasi ke toko Konfigurasi Aplikasi Anda. Saat menyelesaikan panduan memulai cepat yang tercantum dalam prasyarat, Anda sudah menetapkan kredensial Anda dengan peran App Configuration Data Reader.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
           // Load all keys that start with `TestApp:` and have no label.
           .Select("TestApp:*", LabelFilter.Null)
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
});
```
Metode ini Select digunakan untuk memuat semua nilai kunci yang nama kuncinya dimulai dengan TestApp: dan yang tidak memiliki label. Anda dapat memanggil metode lebih Select dari sekali untuk memuat konfigurasi dengan awalan atau label yang berbeda. Jika Anda membagikan satu penyimpanan konfigurasi aplikasi dengan beberapa aplikasi, pendekatan ini membantu memuat konfigurasi yang hanya relevan dengan aplikasi Anda saat ini, daripada memuat semuanya dari penyimpanan Anda.

Di dalam metode ConfigureRefresh, Anda memanggil metode RegisterAll untuk menginstruksikan penyedia App Configuration agar memuat ulang seluruh konfigurasi setiap kali mendeteksi perubahan pada salah satu nilai kunci yang dipilih (yang dimulai dengan TestApp: dan tidak memiliki label). Untuk informasi selengkapnya tentang memantau perubahan konfigurasi, lihat Praktik terbaik untuk refresh konfigurasi.

Petunjuk / Saran

Anda dapat menambahkan panggilan ke metode refreshOptions.SetRefreshInterval untuk menentukan waktu minimum antara pembaruan konfigurasi. Dalam contoh ini, Anda menggunakan nilai default 30 detik. Sesuaikan ke nilai yang lebih tinggi jika Anda perlu mengurangi jumlah permintaan yang dibuat ke toko Konfigurasi Aplikasi Anda.

Tambahkan middleware Azure App Configuration ke koleksi layanan aplikasi Anda.

Perbarui Program.cs dengan kode berikut.

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

builder.Services.AddRazorPages();

// Add Azure App Configuration middleware to the container of services.
builder.Services.AddAzureAppConfiguration();

// Bind configuration "TestApp:Settings" section to the Settings object
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

var app = builder.Build();

// The rest of existing code in program.cs
// ... ...

Panggil metode UseAzureAppConfiguration. Ini memungkinkan aplikasi Anda menggunakan App Configuration middleware untuk memperbarui konfigurasi secara otomatis untuk Anda.

Perbarui Program.cs dengan kode berikut.

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

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();

// The rest of existing code in program.cs
// ... ...

Anda telah mengatur aplikasi Anda untuk menggunakan pola opsi dalam ASP.NET Core selama pengantar cepat. Ketika konfigurasi dasar aplikasi Anda diperbarui dari Konfigurasi Aplikasi, objek Settings yang bertipe kuat yang diperoleh melalui IOptionsSnapshot<T> akan diperbarui secara otomatis. Perlu diketahui bahwa Anda sebaiknya tidak menggunakan IOptions<T> jika pembaruan konfigurasi dinamis diinginkan, karena aplikasi tidak membaca data konfigurasi setelah aplikasi dimulai.

Penyegaran konfigurasi yang didorong oleh permintaan

Pembaruan konfigurasi dipicu oleh permintaan yang masuk ke aplikasi web Anda. Tidak ada penyegaran yang akan terjadi jika aplikasi Anda tidak aktif. Saat aplikasi Anda aktif, middleware App Configuration memantau kunci apa pun yang Anda daftarkan untuk pembaruan dalam pemanggilan ConfigureRefresh. Middleware dijalankan setiap kali ada permintaan masuk ke aplikasi Anda. Namun, middleware hanya akan mengirim permintaan untuk memeriksa nilai di App Configuration saat interval refresh yang Anda tetapkan telah berlalu.

Jika permintaan ke Konfigurasi Aplikasi untuk deteksi perubahan gagal, aplikasi Anda akan terus menggunakan konfigurasi yang disimpan dalam cache. Upaya baru untuk memeriksa perubahan akan dilakukan secara berkala selama ada permintaan masuk baru ke aplikasi Anda.
Pembaharuan konfigurasi terjadi secara asinkron terhadap pemrosesan permintaan masuk aplikasi Anda. Itu tidak akan memblokir atau memperlambat permintaan masuk yang memicu penyegaran. Permintaan yang memicu pembaruan mungkin tidak mendapatkan nilai konfigurasi terbaru, tetapi permintaan berikutnya akan mendapatkan nilai konfigurasi baru.
Untuk memastikan middleware diaktifkan, panggil metode app.UseAzureAppConfiguration() sedini mungkin yang sesuai dalam pipeline permintaan Anda agar middleware lainnya tidak melewatkannya dalam aplikasi Anda.

Bangun dan jalankan aplikasi secara lokal.

Untuk membangun aplikasi menggunakan .NET CLI, jalankan perintah berikut di shell perintah:
```
    dotnet build
```
Setelah proses build berhasil diselesaikan, jalankan perintah berikut untuk menjalankan aplikasi web secara lokal:
```
    dotnet run
```
Buka jendela browser, dan pergi ke URL yang ditampilkan dalam keluaran dotnet run.
Masuk ke portal Azure. Pilih Semua sumber daya, dan pilih penyimpanan App Configuration yang Anda buat dalam penyelesaian cepat.

Pilih Penjelajah konfigurasi, dan perbarui nilai kunci berikut.

Kunci	Nilai
TestApp:Pengaturan:BackgroundColor	hijau
TestApp:Pengaturan:FontColor	Abu-abu muda
TestApp:Pengaturan:Pesan	Data dari Konfigurasi Aplikasi Azure - kini dengan pembaruan langsung!

Muat ulang peramban beberapa kali. Saat interval refresh berlalu setelah 30 detik, halaman akan ditampilkan dengan konten yang diperbarui.

Pencatatan dan pemantauan

Log dikeluarkan setelah penyegaran konfigurasi dan berisi informasi rinci tentang pasangan kunci-nilai yang diambil dari penyimpanan Konfigurasi Aplikasi Anda serta perubahan konfigurasi yang dilakukan pada aplikasi Anda.

Default ILoggerFactory ditambahkan secara otomatis ketika services.AddAzureAppConfiguration() dipanggil. Penyedia Konfigurasi Aplikasi menggunakan ILoggerFactory ini untuk membuat instance dari ILogger, yang menghasilkan log tersebut. ASP.NET Core menggunakan ILogger untuk pencatatan secara default, sehingga Anda tidak perlu mengubah kode tambahan untuk mengaktifkan pencatatan bagi penyedia Konfigurasi Aplikasi.

Log dihasilkan pada level log yang berbeda. Tingkat default adalah Information.

Tingkat Log	Deskripsi
Memperbaiki Kesalahan	Log mencakup kunci dan label dari pasangan nilai-kunci yang aplikasi Anda pantau untuk perubahan dari penyimpanan Konfigurasi Aplikasi Anda. Informasi ini juga mencakup apakah nilai-kunci telah berubah dibandingkan dengan apa yang telah dimuat oleh aplikasi Anda. Aktifkan log pada level ini untuk memecahkan masalah aplikasi Anda jika terjadi perubahan konfigurasi yang tidak sesuai harapan.
Informasi	Log mencakup kunci dari pengaturan konfigurasi yang diperbarui selama penyegaran konfigurasi. Nilai dari 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 penyegaran konfigurasi. Kejadian sesekali dapat diabaikan karena penyedia konfigurasi akan terus menggunakan data yang disimpan dalam cache dan mencoba untuk menyegarkan konfigurasi pada kesempatan berikutnya. Anda dapat memantau log pada tingkat ini untuk peringatan berulang yang mungkin menunjukkan masalah potensial. Sebagai contoh, Anda mengganti string koneksi tetapi lupa memperbarui aplikasi Anda.

Anda dapat mengaktifkan pencatatan pada tingkat log Debug dengan menambahkan contoh berikut ke dalam file appsettings.json Anda. Contoh ini berlaku untuk semua tingkat log lainnya juga.

"Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

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

dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Setting updated. Key:'ExampleKey'

warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    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'

Menggunakan ILogger adalah metode yang diutamakan dalam aplikasi ASP.NET dan diprioritaskan sebagai sumber logging jika ada instance dari ILoggerFactory. Namun, jika ILoggerFactory tidak tersedia, log dapat diaktifkan dan dikonfigurasi melalui instruksi untuk aplikasi .NET Core. Untuk informasi lebih lanjut, lihat logging in .NET Core dan ASP.NET Core.

Catatan

Logging tersedia jika Anda menggunakan versi 6.0.0 atau 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

Menghapus grup sumber daya tidak dapat dibatalkan. Grup sumber daya dan semua sumber daya di dalamnya dihapus secara permanen. Pastikan Anda tidak menghapus grup atau sumber daya yang salah secara tidak sengaja. Jika Anda membuat sumber daya untuk artikel ini di dalam grup sumber daya yang berisi sumber daya lain yang ingin Anda pertahankan, hapus setiap sumber daya satu per satu dari panel masing-masing, daripada menghapus grup sumber daya tersebut.

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 diminta untuk mengonfirmasi penghapusan grup sumber daya. Masukkan nama grup sumber daya Anda untuk mengonfirmasi, lalu pilih Hapus.

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

Langkah selanjutnya

Dalam tutorial ini, Anda mengaktifkan aplikasi web ASP.NET Core Anda untuk secara dinamis memperbarui pengaturan konfigurasi dari Konfigurasi Aplikasi. Untuk mempelajari cara menggunakan identitas yang dikelola oleh Azure untuk mempermudah akses ke Konfigurasi Aplikasi, lanjutkan ke tutorial berikutnya.

Akses Konfigurasi Aplikasi menggunakan identitas terkelola

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-21