Kasus Penggunaan Konfigurasi di ASP.NET Core

Untuk mendapatkan konfigurasi aplikasi, biasanya menggunakan metode akses kata kunci (nilai-kunci). Tapi ini tidak selalu nyaman. terkadang Anda perlu menggunakan objek yang sudah jadi dalam kode Anda dengan nilai yang sudah ditetapkan, dan dengan kemampuan untuk memperbarui nilai tanpa memulai ulang aplikasi. Contoh ini menyediakan template untuk menggunakan konfigurasi sebagai middleware untuk aplikasi ASP.NET Core.



Kami menyarankan Anda untuk membiasakan diri dengan materi: Metanit - Konfigurasi , Cara Kerja Konfigurasi di .NET Core .

Rumusan masalah

Anda perlu menerapkan aplikasi ASP NET Core dengan kemampuan untuk memperbarui konfigurasi dalam format JSON saat runtime. Selama pembaruan konfigurasi, sesi yang sedang berjalan harus terus bekerja dengan opsi konfigurasi sebelumnya. Setelah memperbarui konfigurasi, objek yang digunakan harus diperbarui / diganti dengan yang baru.



Konfigurasi harus deserialized, tidak boleh ada akses langsung ke objek IConfiguration dari pengontrol. Nilai baca harus diperiksa kebenarannya, jika tidak ada, mereka harus diganti dengan nilai default. Implementasinya harus bekerja di kontainer Docker.

Pekerjaan konfigurasi klasik

GitHub: ConfigurationTemplate_1



Proyek ini didasarkan pada template ASP NET Core MVC. Penyedia konfigurasi JsonConfigurationProvider digunakan untuk bekerja dengan file konfigurasi JSON . Untuk menambahkan kemampuan memuat ulang konfigurasi aplikasi selama operasi, tambahkan parameter: "reloadOnChange: true".



Di file Startup.cs, ganti:

public Startup(IConfiguration configuration)
 {
   Configuration = configuration;
 }

Di

public Startup(IConfiguration configuration)
 {         
   var builder = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);
   configuration = builder.Build();
   Configuration = configuration;
  }

.AddJsonFile - menambahkan file JSON, reloadOnChange: true menunjukkan bahwa ketika parameter file konfigurasi diubah, mereka akan dimuat ulang tanpa perlu memuat ulang aplikasi.



Konten file appsettings.json :

{
  "AppSettings": {
    "Parameter1": "Parameter1 ABC",
    "Parameter2": "Parameter2 ABC"  
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Pengontrol aplikasi akan menggunakan layanan: ServiceABC alih-alih mengakses konfigurasi secara langsung. ServiceABC adalah kelas yang mengambil nilai awal dari file konfigurasi. Dalam contoh ini, kelas ServiceABC hanya berisi satu properti Judul . Konten



file ServiceABC.cs :

public class ServiceABC
{
  public string Title;
  public ServiceABC(string title)
  {
     Title = title;
  }
  public ServiceABC()
  { }
}

Untuk menggunakan ServiceABC, Anda perlu menambahkannya sebagai layanan middleware ke aplikasi Anda. Tambahkan layanan sebagai AddTransient, yang dibuat setiap kali Anda mengaksesnya, menggunakan ekspresi:

services.AddTransient<IYourService>(o => new YourService(param));

Bagus untuk layanan ringan yang tidak menghabiskan memori atau sumber daya. Membaca parameter konfigurasi di Startup.cs dilakukan menggunakan IConfiguration , yang menggunakan string kueri yang menentukan jalur lengkap lokasi nilai, contoh: AppSettings: Parameter1.



Di file Startup.cs, tambahkan:

public void ConfigureServices(IServiceCollection services)
{
  //  "Parameter1"    ServiceABC
  var settingsParameter1 = Configuration["AppSettings:Parameter1"];
  //  "Parameter1"            
  services.AddScoped(s=> new ServiceABC(settingsParameter1));
  //next
  services.AddControllersWithViews();
}

Contoh penggunaan layanan ServiceABC di pengontrol, nilai Parameter1 akan ditampilkan di halaman html.



Untuk menggunakan layanan dalam pengontrol, tambahkan ke konstruktor, file HomeController.cs

public class HomeController : Controller
{
  private readonly ILogger<HomeController> _logger;
  private readonly ServiceABC _serviceABC;
  public HomeController(ILogger<HomeController> logger, ServiceABC serviceABC)
    {
      _logger = logger;
      _serviceABC = serviceABC;
    }
  public IActionResult Index()
    {
      return View(_serviceABC);
    }

Tambahkan visibilitas layanan File ServiceABC _ViewImports.cshtml

@using ConfigurationTemplate_1.Services

Ubah Index.cshtml untuk menampilkan opsi halaman Parameter1 .

@model ServiceABC
@{
    ViewData["Title"] = "Home Page";
}
    <div class="text-center">
        <h1>   ASP.NET Core</h1>
        <h4>   </h4>
    </div>
<div>        
    <p> ServiceABC,  
          Parameter1 = @Model.Title</p>
</div>

Mari mulai aplikasinya:

Hasil

Pendekatan ini memecahkan sebagian masalah. Solusi ini tidak mengizinkan penerapan perubahan konfigurasi saat aplikasi sedang berjalan. layanan menerima nilai file konfigurasi hanya pada saat permulaan, dan kemudian hanya bekerja dengan contoh ini. Akibatnya, perubahan selanjutnya pada file konfigurasi tidak akan mengakibatkan perubahan pada aplikasi.

Menggunakan IConfiguration sebagai Singleton

GitHub: ConfigurationTemplate_2



Opsi kedua adalah meletakkan IConfiguration (sebagai Singleton) dalam layanan. Akibatnya, IConfiguration dapat dipanggil dari pengontrol dan layanan lainnya. Saat menggunakan AddSingleton, layanan dibuat sekali, dan saat menggunakan aplikasi, panggilan pergi ke instance yang sama. Gunakan metode ini dengan sangat hati-hati, karena kebocoran memori dan masalah multithreading dapat terjadi.



Mari kita ganti kode dari contoh sebelumnya di Startup.cs dengan yang baru, di mana

services.AddSingleton<IConfiguration>(Configuration);

menambahkan IConfiguration sebagai Singleton ke layanan.

public void ConfigureServices(IServiceCollection services)
{
  //  IConfiguration     
  services.AddSingleton<IConfiguration>(Configuration);
  //  "ServiceABC"                          
  services.AddScoped<ServiceABC>();
  //next
  services.AddControllersWithViews();
}

Ubah konstruktor layanan ServiceABC untuk menerima IConfiguration

public class ServiceABC
{        
  private readonly IConfiguration _configuration;
  public string Title => _configuration["AppSettings:Parameter1"];        
  public ServiceABC(IConfiguration Configuration)
    {
      _configuration = Configuration;
    }
  public ServiceABC()
    { }
}

Mari kita mulai dengan aplikasi:







The ServiceABC layanan ditambahkan ke wadah menggunakan AddScoped berarti bahwa sebuah instance dari kelas akan dibuat pada setiap permintaan halaman. Hasilnya, sebuah instance dari kelas ServiceABC akan dibuat pada setiap permintaan http bersama dengan memuat ulang konfigurasi IConfiguration , dan perubahan baru di appsettings.json akan diterapkan.

Jadi, jika selama pengoperasian aplikasi, ubah parameter Parameter1 menjadi “BARU !!! Parameter1 ABC ”, saat berikutnya Anda mengakses halaman awal, nilai parameter baru akan ditampilkan.



Mari segarkan halaman setelah mengubah file appsettings.json :

Hasil

Kerugian dari pendekatan ini adalah pembacaan manual setiap parameter. Dan jika Anda menambahkan validasi parameter, maka pemeriksaan akan dilakukan bukan setelah mengubah file appsettings.json, tetapi setiap kali Anda menggunakan ServiceABC , yang merupakan tindakan yang tidak perlu. Dalam kasus terbaik, parameter harus divalidasi hanya sekali setelah setiap perubahan file.

Deserialisasi konfigurasi dengan validasi (opsi IOptions)

GitHub: ConfigurationTemplate_3

Baca tentang Opsi di sini .



Opsi ini menghilangkan kebutuhan untuk menggunakan ServiceABC . Sebaliknya, kelas AppSettings digunakan , yang berisi pengaturan dari file konfigurasi dan objek ClientConfig . Objek ClientConfig perlu diinisialisasi setelah mengubah konfigurasi, karena objek yang sudah jadi digunakan dalam pengontrol.

ClientConfig adalah kelas yang berinteraksi dengan sistem eksternal, kodenya tidak dapat diubah. Jika Anda hanya melakukan deserialisasi data kelas AppSettings , maka ClientConfigakan menjadi nol. Oleh karena itu, perlu berlangganan acara konfigurasi baca dan menginisialisasi objek ClientConfig di penangan .



Untuk mentransfer konfigurasi tidak dalam bentuk key-value pair, tetapi sebagai objek kelas tertentu, kita akan menggunakan antarmuka IOptions . Selain itu, IOptions, berbeda dengan ConfigurationManager, memungkinkan Anda untuk melakukan deserialisasi bagian individual. Untuk membuat objek ClientConfig , Anda perlu menggunakan IPostConfigureOptions , yang dijalankan setelah semua konfigurasi telah diproses. IPostConfigureOptions akan dijalankan setiap kali konfigurasi dibaca, paling baru.



Mari buat ClientConfig.cs :

public class ClientConfig
{
  private string _parameter1;
  private string _parameter2;
  public string Value => _parameter1 + " " + _parameter2;
  public ClientConfig(ClientConfigOptions configOptions)
    {
      _parameter1 = configOptions.Parameter1;
      _parameter2 = configOptions.Parameter2;
    }
}

Ini akan mengambil parameter sebagai konstruktor dalam bentuk objek ClientConfigOptions :

public class ClientConfigOptions
{
  public string Parameter1;
  public string Parameter2;
} 

Mari buat kelas pengaturan AppSettings , dan tentukan metode ClientConfigBuild () di dalamnya , yang akan membuat objek ClientConfig .



File AppSettings.cs :

public class AppSettings
{        
  public string Parameter1 { get; set; }
  public string Parameter2 { get; set; }        
  public ClientConfig clientConfig;
  public void ClientConfigBuild()
    {
      clientConfig = new ClientConfig(new ClientConfigOptions()
        {
          Parameter1 = this.Parameter1,
          Parameter2 = this.Parameter2
        }
        );
      }
}

Mari buat penangan konfigurasi yang akan diproses terakhir kali. Untuk melakukan ini, ini harus diwarisi dari IPostConfigureOptions . PostConfig yang terakhir dipanggil akan mengeksekusi ClientConfigBuild () , yang akan membuat ClientConfig . ConfigureAppSettingsOptions.cs



file :

public class ConfigureAppSettingsOptions: IPostConfigureOptions<AppSettings>
{
  public ConfigureAppSettingsOptions()
    { }
  public void PostConfigure(string name, AppSettings options)
    {            
      options.ClientConfigBuild();
    }
}

Sekarang tinggal membuat perubahan hanya di Startup.cs , perubahan hanya akan mempengaruhi fungsi ConfigureServices (IServiceCollection services) .



Pertama, mari kita baca bagian AppSettings di appsettings.json

// configure strongly typed settings objects
var appSettingsSection = Configuration.GetSection("AppSettings");
services.Configure<AppSettings>(appSettingsSection);

Selanjutnya, untuk setiap permintaan, salinan AppSettings akan dibuat untuk kemungkinan memanggil pasca-pemrosesan:

services.AddScoped(sp => sp.GetService<IOptionsSnapshot<AppSettings>>().Value);

Mari tambahkan pasca-pemrosesan kelas AppSettings sebagai layanan:

services.AddSingleton<IPostConfigureOptions<AppSettings>, ConfigureAppSettingsOptions>();

Menambahkan kode ke Startup.cs

public void ConfigureServices(IServiceCollection services)
{
  // configure strongly typed settings objects
  var appSettingsSection = Configuration.GetSection("AppSettings");
  services.Configure<AppSettings>(appSettingsSection);
  services.AddScoped(sp => sp.GetService<IOptionsSnapshot<AppSettings>>().Value);                                    
  services.AddSingleton<IPostConfigureOptions<AppSettings>, ConfigureAppSettingsOptions>();            
  //next
  services.AddControllersWithViews();
}

Untuk mendapatkan akses ke konfigurasi, cukup dengan memasukkan AppSettings dari pengontrol .



File HomeController.cs :

public class HomeController : Controller
{
  private readonly ILogger<HomeController> _logger;
  private readonly AppSettings _appSettings;
  public HomeController(ILogger<HomeController> logger, AppSettings appSettings)
    {
      _logger = logger;
      _appSettings = appSettings;
    }

Mari kita ubah Index.cshtml untuk menampilkan parameter Value dari objek lientConfig

@model AppSettings
@{
    ViewData["Title"] = "Home Page";
}
<div class="text-center">
    <h1>   ASP.NET Core</h1>
    <h4>    ( IOptions)</h4>
</div>
<div>
    <p>
         ClientConfig,  
         = @Model.clientConfig.Value
    </p>
</div>

Mari kita mulai aplikasi: Jika selama pengoperasian aplikasi, ubah parameter Parameter1 menjadi “BARU !!! Parameter1 ABC "dan Parameter2 menjadi" NEW !!! Parameter2 ABC ", maka lain kali Anda mengakses halaman awal, properti Value baru akan ditampilkan :

Hasil

Pendekatan ini memungkinkan Anda untuk melakukan deserialisasi semua nilai konfigurasi tanpa mengulang parameter secara manual. Setiap permintaan http bekerja dengan instance AppSettings dan lientConfignya sendiri, yang menghilangkan situasi tabrakan. IPostConfigureOptions memastikan bahwa itu dijalankan terakhir ketika semua opsi telah dibaca ulang. Kerugian dari solusi ini adalah pembuatan instance ClientConfig yang konstan untuk setiap permintaan, yang tidak praktis karena pada kenyataannya, ClientConfig hanya boleh dibuat ulang setelah konfigurasi berubah.

Deserialisasi konfigurasi dengan validasi (tanpa menggunakan IOptions)

GitHub: ConfigurationTemplate_4



menggunakan pendekatan menggunakan IPostConfigureOptions mengarah ke pembuatan objek ClientConfig setiap kali Anda menerima permintaan dari klien. Ini tidak cukup rasional karena setiap permintaan bekerja dengan status ClientConfig awal, yang hanya berubah jika file konfigurasi appsettings.json diubah. Untuk melakukan ini, kita akan meninggalkan IPostConfigureOptions dan membuat penangan konfigurasi yang akan dipanggil hanya ketika appsettings.json berubah, akibatnya ClientConfig hanya akan dibuat sekali, dan kemudian instance ClientConfig yang sudah dibuat akan diberikan untuk setiap permintaan.



Buat kelas SingletonAppSettingskonfigurasi (Singleton) dari mana turunan pengaturan akan dibuat untuk setiap permintaan.



File SingletonAppSettings.cs :

public class SingletonAppSettings
{
  public AppSettings appSettings;  
  private static readonly Lazy<SingletonAppSettings> lazy = new Lazy<SingletonAppSettings>(() => new SingletonAppSettings());
  private SingletonAppSettings()
    { }
  public static SingletonAppSettings Instance => lazy.Value;
}

Mari kembali ke kelas Startup dan tambahkan referensi ke antarmuka IServiceCollection .

Ini akan digunakan dalam metode penanganan konfigurasi

public IServiceCollection Services { get; set; }

Mari kita ubah ConfigureServices (layanan IServiceCollection) dan teruskan referensi ke IServiceCollection .



File Startup.cs :

public void ConfigureServices(IServiceCollection services)
{
  Services = services;
  //  AppSettings  
  var appSettings = Configuration.GetSection("AppSettings").Get<AppSettings>();
  appSettings.ClientConfigBuild();

Mari buat konfigurasi Singleton dan tambahkan ke kumpulan layanan:

SingletonAppSettings singletonAppSettings = SingletonAppSettings.Instance;
singletonAppSettings.appSettings = appSettings;
services.AddSingleton(singletonAppSettings);     

Mari tambahkan objek AppSettings sebagai Scoped, dengan setiap permintaan salinan dari Singleton akan dibuat:

services.AddScoped(sp => sp.GetService<SingletonAppSettings>().appSettings);

Sepenuhnya ConfigureServices (layanan IServiceCollection) :

public void ConfigureServices(IServiceCollection services)
{
  Services = services;
  //  AppSettings  
  var appSettings = Configuration.GetSection("AppSettings").Get<AppSettings>();
  appSettings.ClientConfigBuild();
  SingletonAppSettings singletonAppSettings = SingletonAppSettings.Instance;
  singletonAppSettings.appSettings = appSettings;
  services.AddSingleton(singletonAppSettings);             
  services.AddScoped(sp => sp.GetService<SingletonAppSettings>().appSettings);
  //next
  services.AddControllersWithViews();
}

Sekarang tambahkan penangan untuk konfigurasi di Configure (aplikasi IApplicationBuilder, IWebHostEnvironment env) . Token digunakan untuk melacak perubahan di file appsettings.json. OnChange adalah fungsi yang dipanggil saat file berubah. Penangan konfigurasi OnChange () :

ChangeToken.OnChange(() => Configuration.GetReloadToken(), onChange);

Pertama, kita membaca file appsettings.json dan deserialisasi kelas AppSettings . Kemudian, dari service collection, kita mendapatkan referensi ke Singleton yang menyimpan objek AppSettings , dan menggantinya dengan yang baru.

private void onChange()
{                        
  var newAppSettings = Configuration.GetSection("AppSettings").Get<AppSettings>();
  newAppSettings.ClientConfigBuild();
  var serviceAppSettings = Services.BuildServiceProvider().GetService<SingletonAppSettings>();
  serviceAppSettings.appSettings = newAppSettings;
  Console.WriteLine($"AppSettings has been changed! {DateTime.Now}");
}

Mari kita







mulai aplikasinya: Setelah memilih mode peluncuran sebagai aplikasi konsol, di jendela aplikasi Anda dapat melihat pesan tentang pemicuan peristiwa perubahan file konfigurasi:







Dan nilai baru:

Hasil

Opsi ini lebih baik daripada menggunakan IPostConfigureOptions karena memungkinkan Anda membuat objek hanya setelah mengubah file konfigurasi, dan tidak pada setiap permintaan. Hasilnya adalah pengurangan waktu respons server. Setelah token dipicu, status token disetel ulang.

Menambahkan default dan memvalidasi konfigurasi

GitHub: ConfigurationTemplate_5



Pada contoh sebelumnya, jika file appsettings.json tidak ada, aplikasi akan mengeluarkan pengecualian, jadi mari kita buat file konfigurasi opsional dan tambahkan pengaturan default. Saat Anda memublikasikan aplikasi proyek yang dibuat dari template di Visula Studio, file appsettings.json akan ditempatkan di folder yang sama bersama dengan semua biner, yang tidak nyaman saat diterapkan ke Docker. File appsettings.json telah dipindahkan ke config / :

.AddJsonFile("config/appsettings.json")

Untuk dapat meluncurkan aplikasi tanpa appsettings.json, ubah parameter optiona l menjadi true , yang dalam hal ini berarti keberadaan appsettings.json bersifat opsional.



File Startup.cs :

public Startup(IConfiguration configuration)
{
  var builder = new ConfigurationBuilder()
     .AddJsonFile("config/appsettings.json", optional: true, reloadOnChange: true);
  configuration = builder.Build();
  Configuration = configuration;
}

Tambahkan ke public void ConfigureServices (IServiceCollection services) ke baris deserialization konfigurasi untuk kasus penanganan tidak adanya file appsettings.json:

 var appSettings = Configuration.GetSection("AppSettings").Get<AppSettings>() ?? new AppSettings();

Mari tambahkan validasi konfigurasi berdasarkan antarmuka IValidatableObject . Jika parameter konfigurasi tidak ada, nilai default akan digunakan.



Mari kita mewarisi kelas AppSettings dari IValidatableObject dan mengimplementasikan metode:

public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)

File AppSettings.cs :

public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
  List<ValidationResult> errors = new List<ValidationResult>();
  if (string.IsNullOrWhiteSpace(this.Parameter1))
    {
      errors.Add(new ValidationResult("   Parameter1.  " +
        "   DefaultParameter1 ABC"));
      this.Parameter1 = "DefaultParameter1 ABC";
    }
    if (string.IsNullOrWhiteSpace(this.Parameter2))
    {
      errors.Add(new ValidationResult("   Parameter2.  " +
        "   DefaultParameter2 ABC"));
      this.Parameter2 = "DefaultParameter2 ABC";
    }
    return errors;
}

Tambahkan metode untuk memanggil pemeriksaan konfigurasi yang akan dipanggil dari file Startup.cs kelas Startup :

private void ValidateAppSettings(AppSettings appSettings)
{
  var resultsValidation = new List<ValidationResult>();
  var context = new ValidationContext(appSettings);
  if (!Validator.TryValidateObject(appSettings, context, resultsValidation, true))
    {
      resultsValidation.ForEach(
        error => Console.WriteLine($" : {error.ErrorMessage}"));
      }
    }

Mari tambahkan panggilan ke metode validasi konfigurasi di ConfigureServices (IServiceCollection services). Jika tidak ada file appsettings.json, Anda perlu menginisialisasi objek AppSettings dengan nilai default.



File Startup.cs :

var appSettings = Configuration.GetSection("AppSettings").Get<AppSettings>() ?? new AppSettings();

Memeriksa parameter. Jika nilai default digunakan, pesan yang menunjukkan parameter akan ditampilkan di konsol.

 //Validate            
this.ValidateAppSettings(appSettings);            
appSettings.ClientConfigBuild();

Mari kita ubah pemeriksaan konfigurasi di onChange ()

private void onChange()
{                        
  var newAppSettings = Configuration.GetSection("AppSettings").Get<AppSettings>() ?? new AppSettings();
  //Validate            
  this.ValidateAppSettings(newAppSettings);            
  newAppSettings.ClientConfigBuild();
  var serviceAppSettings = Services.BuildServiceProvider().GetService<SingletonAppSettings>();
  serviceAppSettings.appSettings = newAppSettings;
  Console.WriteLine($"AppSettings has been changed! {DateTime.Now}");
}

Jika Anda menghapus kunci Parameter1 dari file appsettings.json , maka setelah menyimpan file, pesan tentang tidak adanya parameter akan muncul di jendela aplikasi konsol:

Hasil

Mengubah jalur untuk lokasi konfigurasi di folder config adalah solusi yang baik. memungkinkan Anda untuk tidak mencampur semua file dalam satu heap. Folder config hanya ditentukan untuk menyimpan file konfigurasi. Menyederhanakan tugas penerapan dan konfigurasi aplikasi untuk administrator melalui validasi konfigurasi. Jika Anda menambahkan output dari kesalahan konfigurasi ke log, maka administrator, jika parameter yang salah ditentukan, akan menerima informasi yang akurat tentang masalah tersebut, dan bukan karena programmer baru-baru ini mulai menulis pengecualian apa pun: "Ada yang salah . "



Tidak ada opsi ideal untuk bekerja dengan konfigurasi, semuanya tergantung pada tugas yang ada, setiap opsi memiliki pro dan kontra.



Semua template konfigurasi tersedia di sini .



Literatur:

1. Benar ASP.NET Core
2. METANIT - Konfigurasi. Dasar-dasar Konfigurasi
3. Pola Desain Singleton C # .net core
4. Memuat ulang konfigurasi di inti .NET
5. Memuat ulang Opsi yang diketik dengan kuat pada perubahan file di ASP.NET Core RC2
6. Konfigurasi Aplikasi Inti ASP.NET melalui IOptions
7. METANIT - Meneruskan konfigurasi melalui IOptions
8. Konfigurasi Aplikasi Inti ASP.NET melalui IOptions
9. METANIT - Model Self-Validation