Bagikan melalui

Tutorial: Menggunakan konfigurasi dinamis di aplikasi ASP.NET Core

  • Artikel

Tutorial ini menunjukkan bagaimana Anda dapat mengaktifkan pembaruan konfigurasi dinamis di aplikasi ASP.NET Core. Tutorial dibangun pada aplikasi web yang diperkenalkan di panduan mulai cepat. Aplikasi Anda akan memanfaatkan pustaka penyedia App Configuration untuk kemampuan penembolokan dan refresh konfigurasi bawaannya. Sebelum melanjutkan, selesaikan Membuat aplikasi ASP.NET Core dengan App Configuration terlebih dahulu.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Siapkan aplikasi Anda untuk memperbarui konfigurasinya sebagai respons terhadap perubahan di penyimpanan App Configuration.
  • Masukkan konfigurasi terbaru ke dalam aplikasi Anda.

Prasyarat

Selesaikan mulai cepat: Membuat aplikasi ASP.NET Core dengan App Configuration.

Menambahkan kunci sentinel

Kunci sentinel adalah kunci yang Anda perbarui setelah menyelesaikan perubahan semua kunci lainnya. Aplikasi Anda memantau kunci sentinel. Saat perubahan terdeteksi, aplikasi Anda me-refresh semua nilai konfigurasi. Pendekatan ini membantu memastikan konsistensi konfigurasi di aplikasi Anda dan mengurangi jumlah keseluruhan permintaan yang dibuat ke penyimpanan App Configuration Anda, dibandingkan dengan memantau semua kunci untuk perubahan.

  1. Di portal Azure, buka penyimpanan App Configuration Anda dan pilih Configuration Explorer > Create > Key-value.
  2. Untuk Kunci, masukkan TestApp:Settings:Sentinel. Untuk Nilai, masukkan 1. Biarkan Label dan Jenis konten kosong.
  3. Pilih Terapkan.

Memuat ulang data dari Azure App Configuration

  1. Buka Program.cs, dan perbarui metode yang AddAzureAppConfiguration Anda tambahkan sebelumnya selama mulai cepat.

    // Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString)
           // Load all keys that start with `TestApp:` and have no label
           .Select("TestApp:*", LabelFilter.Null)
           // Configure to reload configuration if the registered sentinel key is modified
           .ConfigureRefresh(refreshOptions =>
                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
});

    Metode Select ini digunakan untuk memuat semua nilai kunci yang nama kuncinya dimulai dengan TestApp: dan yang tidak memiliki label. Anda dapat memanggil Select metode lebih dari sekali untuk memuat konfigurasi dengan awalan atau label yang berbeda. Jika Anda berbagi satu penyimpanan App Configuration dengan beberapa aplikasi, pendekatan ini membantu memuat konfigurasi hanya relevan dengan aplikasi Anda saat ini alih-alih memuat semuanya dari penyimpanan Anda.

    Dalam metode ini ConfigureRefresh , Anda mendaftarkan kunci yang ingin Anda pantau untuk perubahan di penyimpanan App Configuration Anda. Parameter refreshAll ke Register metode menunjukkan bahwa semua konfigurasi yang Anda tentukan oleh Select metode akan dimuat ulang jika kunci terdaftar berubah.

    Tip

    Anda dapat menambahkan panggilan ke refreshOptions.SetCacheExpiration metode untuk menentukan waktu minimum antara refresh konfigurasi. Dalam contoh ini, Anda menggunakan nilai default 30 detik. Sesuaikan dengan nilai yang lebih tinggi jika Anda perlu mengurangi jumlah permintaan yang dibuat ke penyimpanan App Configuration Anda.

  2. Tambahkan middleware Azure App Configuration ke kumpulan 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
// ... ...

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

    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 menyiapkan aplikasi untuk menggunakan pola opsi di ASP.NET Core selama mulai cepat. Saat konfigurasi mendasar aplikasi Anda diperbarui dari App Configuration, objek anda yang sangat di ketik Settings yang diperoleh melalui IOptionsSnapshot<T> diperbarui secara otomatis. Perhatikan bahwa Anda tidak boleh menggunakan IOptions<T> pembaruan konfigurasi dinamis jika diinginkan karena tidak membaca data konfigurasi setelah aplikasi dimulai.

Refresh konfigurasi berbasis permintaan

Refresh konfigurasi dipicu oleh permintaan masuk ke aplikasi web Anda. Tidak ada refresh yang akan terjadi jika aplikasi Anda diam. Saat aplikasi Anda aktif, middleware App Configuration memantau kunci sentinel, atau kunci lain yang Anda daftarkan untuk refresh dalam ConfigureRefresh panggilan. Middleware dipicu pada setiap permintaan masuk ke aplikasi Anda. Namun, middleware hanya akan mengirim permintaan untuk memeriksa nilai dalam App Configuration saat waktu kedaluwarsa cache yang Anda tetapkan telah berlalu.

  • Jika permintaan ke App Configuration untuk deteksi perubahan gagal, aplikasi Anda akan terus menggunakan konfigurasi cache. Upaya baru untuk memeriksa perubahan akan dilakukan secara berkala sementara ada permintaan masuk baru ke aplikasi Anda.
  • Refresh konfigurasi terjadi secara asinkron dengan pemrosesan permintaan masuk aplikasi Anda. Ini tidak akan memblokir atau memperlambat permintaan masuk yang memicu refresh. Permintaan yang memicu refresh mungkin tidak mendapatkan nilai konfigurasi yang diperbarui, tetapi nantinya permintaan akan mendapatkan nilai konfigurasi baru.
  • Untuk memastikan middleware dipicu, panggil app.UseAzureAppConfiguration() metode sedini mungkin di alur permintaan Anda sehingga middleware lain tidak akan melewatinya di aplikasi Anda.

Membangun dan menjalankan aplikasi secara lokal

  1. Untuk membangun aplikasi dengan menggunakan .NET CLI, jalankan perintah berikut di shell perintah:

        dotnet build

  2. Setelah pembangunan berhasil diselesaikan, jalankan perintah berikut dengan tujuan menjalankan aplikasi secara lokal:

        dotnet run

  3. Buka jendela browser, dan buka URL yang diperlihatkan dalam output dotnet run.

    Membuka aplikasi mulai cepat secara lokal

  4. Masuk ke portal Azure. Pilih Semua sumber daya, lalu pilih instans penyimpanan Azure App Configuration yang Anda buat di mulai cepat.

  5. Pilih Penjelajah konfigurasi, dan perbarui nilai kunci berikut. Ingatlah untuk memperbarui tombol sentinel pada akhirnya.

    Tombol Nilai
    TestApp:Settings:BackgroundColor hijau
    TestApp:Settings:FontColor lightGray
    TestApp:Pengaturan:Pesan Data dari Azure App Configuration - sekarang dengan pembaruan langsung!
    TestApp:Pengaturan:Sentinel 2

  6. Refresh browser beberapa kali. Saat cache kedaluwarsa setelah 30 detik, halaman akan ditampilkan dengan konten yang diperbarui.

    Membuka aplikasi mulai cepat yang diperbarui secara lokal

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.

  • Default ILoggerFactory ditambahkan secara otomatis saat services.AddAzureAppConfiguration() dipanggil. Penyedia App Configuration menggunakan ini ILoggerFactory untuk membuat instans ILogger, yang menghasilkan log ini. ASP.NET Core menggunakan ILogger untuk pengelogan secara default, sehingga Anda tidak perlu membuat perubahan kode tambahan untuk mengaktifkan pengelogan untuk penyedia App Configuration.

  • Log adalah output pada tingkat log yang berbeda. Tingkat default adalah Information.

    Tingkat log Deskripsi
    Debug 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 Debug di tingkat log dengan menambahkan contoh berikut ke file Anda appsettings.json . Contoh ini juga berlaku untuk semua tingkat log lainnya.

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

  • Kategori pengelogan adalah Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, yang muncul sebelum setiap 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 disukai dalam aplikasi ASP.NET dan diprioritaskan sebagai sumber pengelogan ILoggerFactory jika instans ada. Namun, jika ILoggerFactory tidak tersedia, log dapat diaktifkan dan dikonfigurasi melalui instruksi untuk aplikasi .NET Core. Untuk informasi selengkapnya, lihat pengelogan di .NET Core dan ASP.NET Core.

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.

  1. Masuk ke portal Azure, lalu pilih Grup sumber daya.
  2. Dalam kotak Filter menurut nama, masukkan nama grup sumber daya Anda.
  3. Dalam daftar hasil, pilih nama grup sumber daya untuk melihat gambaran umum.
  4. Pilih Hapus grup sumber daya.
  5. 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 ASP.NET Core untuk me-refresh pengaturan konfigurasi dari Azure App Configuration secara dinamis. Untuk mempelajari cara menggunakan identitas terkelola Azure untuk mempermudah akses ke Azure App Configuration, lanjutkan ke tutorial berikutnya.

Mengakses App Configuration menggunakan identitas terkelola