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. Ini dibangun pada aplikasi yang diperkenalkan dalam 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 belajar cara:

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

Prasyarat

Jika Anda tidak memiliki akun Azure, buat akun gratis sebelum memulai.

Selesaikan panduan cepat Konfigurasi Aplikasi .NET dengan App Configuration.

Pembaruan konfigurasi berbasis aktivitas

Buka Program.cs dan perbarui file dengan kode berikut. 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 penyimpanan App Configuration Anda. Saat menyelesaikan panduan cepat yang terdaftar dalam prasyarat, Anda sudah menugaskan kredensial Anda peran Pengonfigurasi Data Pembaca Aplikasi.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(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!");

}

ConfigureRefresh Di dalam metode , Anda memanggil RegisterAll metode untuk menginstruksikan penyedia App Configuration untuk memuat ulang seluruh konfigurasi setiap kali mendeteksi perubahan dalam salah satu nilai kunci yang dipilih (dalam hal ini, hanya TestApp:Settings:Message). Untuk informasi selengkapnya tentang memantau perubahan konfigurasi, lihat Praktik terbaik untuk refresh konfigurasi.

Metode SetRefreshInterval menentukan waktu minimum yang harus berlalu sebelum permintaan baru dibuat ke App Configuration untuk memeriksa perubahan konfigurasi apa pun. Dalam contoh ini, Anda mengambil alih waktu kedaluwarsa default 30 detik, menentukan waktu 10 detik sebagai gantinya untuk tujuan demonstrasi.

Memanggil ConfigureRefresh metode saja tidak akan menyebabkan konfigurasi di-refresh secara otomatis. Anda memanggil TryRefreshAsync metode 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, bisa ketika Anda memproses pesan masuk, pesanan, atau perulangan tugas yang kompleks. Ini 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 interval refresh yang dikonfigurasi telah berlalu dan TryRefreshAsync panggilan dipicu oleh aktivitas aplikasi Anda lagi. TryRefreshAsync Panggilan adalah no-op sebelum interval refresh yang dikonfigurasi berlalu, sehingga dampak performanya minimal, bahkan jika 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 pada IServiceCollection Anda.

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

Atur variabel lingkungan bernama Titik Akhir ke titik akhir penyimpanan App Configuration Anda yang ditemukan di bawah Gambaran Umum penyimpanan Anda di portal Azure.

Jika Anda menggunakan perintah Windows, jalankan perintah berikut dan hidupkan ulang perintah untuk memungkinkan perubahan berlaku:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Jika Anda menggunakan PowerShell, jalankan perintah berikut:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Jika Anda menggunakan macOS atau Linux, jalankan perintah berikut:
```
export Endpoint='<endpoint-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 App Configuration yang Anda buat dalam panduan memulai cepat.
Pilih Penjelajah Konfigurasi, dan perbarui nilai kunci berikut:

Kunci Nilai

TestApp:Pengaturan:Pesan Data dari Azure App Configuration telah diperbarui
Tekan tombol Enter untuk memicu refresh dan mencetak nilai yang diperbarui di jendela Command Prompt atau PowerShell.

Nota

Karena interval refresh diatur ke 10 detik menggunakan SetRefreshInterval metode saat menentukan konfigurasi untuk operasi refresh, nilai untuk pengaturan konfigurasi hanya akan diperbarui jika setidaknya 10 detik telah berlalu sejak refresh terakhir untuk pengaturan tersebut.

Kunci	Nilai
TestApp:Pengaturan:Pesan	Data dari Azure App Configuration telah diperbarui

Pengelogan dan pemantauan

Log-data dihasilkan saat penyegaran konfigurasi dan berisi informasi terperinci tentang pasangan kunci-nilai yang diambil dari penyimpanan Konfigurasi Aplikasi Anda serta perubahan konfigurasi yang dilakukan 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 dihasilkan pada berbagai tingkat peristiwa. Tingkat default adalah Informational.

Tingkat Peristiwa	Deskripsi
Verbositas	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 sudah dimuat oleh aplikasi Anda. Aktifkan log pada level ini untuk memecahkan masalah aplikasi Anda jika terjadi perubahan konfigurasi yang tidak sesuai harapan.
Bersifat Informatif	Log mencakup kunci dari pengaturan konfigurasi yang diperbarui selama penyegaran konfigurasi. Nilai pengaturan konfigurasi dihilangkan dari log untuk menghindari kebocoran data sensitif. Anda dapat memantau log di 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 di-cache dan berusaha untuk menyegarkan konfigurasi pada lain waktu. Anda bisa memantau log pada level ini untuk peringatan berulang yang mungkin menunjukkan masalah potensial. Misalnya, Anda mengganti 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 pencatatan log hanya untuk kategori Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh.

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 pencatatan adalah Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, yang muncul sebelum setiap pencatatan. 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'

Nota

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

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 selanjutnya

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-05-20