Konfigurasi di ASP.NET Core

Artikel
07/22/2022
92 menit untuk membaca

Konfigurasi aplikasi di ASP.NET Core dilakukan menggunakan satu atau beberapa penyedia konfigurasi. Penyedia konfigurasi membaca data konfigurasi dari pasangan kunci-nilai menggunakan berbagai sumber konfigurasi:

File pengaturan, seperti appsettings.json
Variabel lingkungan
Azure Key Vault
Azure App Configuration
Argumen baris perintah
Penyedia kustom, terinstal atau dibuat
File direktori
Objek .NET dalam memori

Artikel ini menyediakan informasi tentang konfigurasi di ASP.NET Core. Untuk informasi tentang menggunakan konfigurasi di aplikasi konsol, lihat Konfigurasi .NET.

Konfigurasi Aplikasi dan Host

ASP.NET Aplikasi core mengonfigurasi dan meluncurkan host. Host bertanggung jawab atas startup aplikasi dan manajemen seumur hidup. Templat ASP.NET Core membuat yang WebApplicationBuilder berisi host. Meskipun beberapa konfigurasi dapat dilakukan di host dan penyedia konfigurasi aplikasi, umumnya, hanya konfigurasi yang diperlukan untuk host yang harus dilakukan dalam konfigurasi host.

Konfigurasi aplikasi adalah prioritas tertinggi dan dirinci di bagian berikutnya. Konfigurasi host mengikuti konfigurasi aplikasi, dan dijelaskan dalam artikel ini.

Sumber konfigurasi aplikasi default

ASP.NET Core web yang dibuat dengan dotnet baru atau Visual Studio menghasilkan kode berikut:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder menginisialisasi instans WebApplicationBuilder baru kelas dengan default yang telah dikonfigurasi sebelumnya. Inisialisasi WebApplicationBuilder (builder) menyediakan konfigurasi default untuk aplikasi dalam urutan berikut, dari prioritas tertinggi hingga terendah:

Argumen baris perintah menggunakan penyedia konfigurasi Baris perintah.
Variabel lingkungan yang tidak diawali menggunakan penyedia konfigurasi Variabel lingkungan yang tidak diawali.
Rahasia pengguna saat aplikasi berjalan di Development lingkungan.
appsettings.{Environment}.jsonJSmenggunakan penyedia konfigurasi ON. Misalnya, appsettings.Production.json dan appsettings.Development.json.
appsettings.json menggunakan JSpenyedia konfigurasi ON.
Fallback ke konfigurasi host yang dijelaskan di bagian berikutnya.

Sumber konfigurasi host default

Daftar berikut berisi sumber konfigurasi host default dari prioritas tertinggi hingga terendah:

ASPNETCORE_-variabel lingkungan awalan menggunakan penyedia konfigurasi variabel Lingkungan.
Argumen baris perintah menggunakan penyedia konfigurasi Baris perintah
DOTNET_-variabel lingkungan awalan menggunakan penyedia konfigurasi variabel Lingkungan.

Ketika nilai konfigurasi diatur dalam konfigurasi host dan aplikasi, konfigurasi aplikasi digunakan.

Lihat Penjelasan dalam komentar GitHub ini untuk penjelasan tentang mengapa dalam konfigurasi host, ASPNETCORE_ variabel lingkungan awalan memiliki prioritas yang lebih tinggi daripada argumen baris perintah.

Variabel host

Variabel berikut dikunci di awal saat menginisialisasi penyusun host dan tidak dapat dipengaruhi oleh konfigurasi aplikasi:

Nama aplikasi
Nama lingkungan, misalnya Development, , Productiondan Staging
Akar konten
Akar web
Apakah akan memindai rakitan startup hosting dan rakitan mana yang akan dipindai.
Variabel yang dibaca oleh aplikasi dan kode pustaka dari HostBuilderContext.Configuration di IHostBuilder.ConfigureAppConfiguration callbacks.

Setiap pengaturan host lainnya dibaca dari konfigurasi aplikasi alih-alih konfigurasi host.

URLS adalah salah satu dari banyak pengaturan host umum yang bukan pengaturan bootstrap. Seperti setiap pengaturan host lain yang tidak ada dalam daftar sebelumnya, URLS dibaca nanti dari konfigurasi aplikasi. Konfigurasi host adalah fallback untuk konfigurasi aplikasi, sehingga konfigurasi host dapat digunakan untuk mengatur URLS, tetapi akan ditimpa oleh sumber konfigurasi apa pun dalam konfigurasi aplikasi seperti appsettings.json.

Untuk informasi selengkapnya, lihat Mengubah akar konten, nama aplikasi, dan lingkungan dan Mengubah akar konten, nama aplikasi, dan lingkungan menurut variabel lingkungan atau baris perintah

Bagian yang tersisa dalam artikel ini mengacu pada konfigurasi aplikasi.

Penyedia konfigurasi aplikasi

Kode berikut menampilkan penyedia konfigurasi yang diaktifkan dalam urutan ditambahkan:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

Daftar sebelumnya dari sumber konfigurasi default prioritas tertinggi hingga terendah menunjukkan penyedia dalam urutan yang berlawanan mereka ditambahkan ke aplikasi yang dihasilkan templat. Misalnya, JSpenyedia konfigurasi ON ditambahkan sebelum penyedia konfigurasi Baris perintah.

Penyedia konfigurasi yang ditambahkan nanti memiliki prioritas yang lebih tinggi dan mengambil alih pengaturan kunci sebelumnya. Misalnya, jika MyKey diatur di lingkungan appsettings.json dan , nilai lingkungan digunakan. Dengan menggunakan penyedia konfigurasi default, penyedia konfigurasi Baris perintah mengambil alih semua penyedia lain.

Untuk informasi selengkapnya tentang CreateBuilder, lihat Pengaturan penyusun default.

`appsettings.json`

Pertimbangkan file berikut appsettings.json :

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JsonConfigurationProvider Default memuat konfigurasi dalam urutan berikut:

appsettings.json
appsettings.{Environment}.json : Misalnya, appsettings.Production.json file dan appsettings.Development.json . Versi lingkungan file dimuat berdasarkan IHostingEnvironment.EnvironmentName. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

appsettings.{Environment}.json nilai mengambil alih kunci di appsettings.json. Misalnya, secara default:

Dalam pengembangan, appsettings.Development.json konfigurasi menimpa nilai yang ditemukan di appsettings.json.
Dalam produksi, appsettings.Production.json konfigurasi menimpa nilai yang ditemukan di appsettings.json. Misalnya, saat menyebarkan aplikasi ke Azure.

Jika nilai konfigurasi harus dijamin, lihat GetValue. Contoh sebelumnya hanya membaca string dan tidak mendukung nilai default.

Menggunakan konfigurasi default , appsettings.json file dan appsettings.{Environment}.json diaktifkan dengan reloadOnChange: true. Perubahan yang dilakukan pada appsettings.json file dan appsettings.{Environment}.jsonsetelah aplikasi dimulai dibaca oleh JSpenyedia konfigurasi ON.

Mengikat data konfigurasi hierarkis menggunakan pola opsi

Cara yang disukai untuk membaca nilai konfigurasi terkait adalah menggunakan pola opsi. Misalnya, untuk membaca nilai konfigurasi berikut:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Buat kelas berikut PositionOptions :

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; } = String.Empty;
    public string Name { get; set; } = String.Empty;
}

Kelas opsi:

Harus non-abstrak dengan konstruktor tanpa parameter publik.
Semua properti baca-tulis publik dari jenis terikat.
Bidang tidak terikat. Dalam kode sebelumnya, Position tidak terikat. Bidang Position digunakan sehingga string "Position" tidak perlu dikodekan secara permanen di aplikasi saat mengikat kelas ke penyedia konfigurasi.

Kode berikut:

Memanggil ConfigurationBinder.Bind untuk mengikat PositionOptions kelas ke bagian Position .
Position Menampilkan data konfigurasi.

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Dalam kode sebelumnya, secara default, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai dibaca.

ConfigurationBinder.Get<T> mengikat dan mengembalikan jenis yang ditentukan. ConfigurationBinder.Get<T> mungkin lebih nyaman daripada menggunakan ConfigurationBinder.Bind. Kode berikut menunjukkan cara menggunakan ConfigurationBinder.Get<T> dengan PositionOptions kelas :

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions? positionOptions { get; private set; }

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

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Dalam kode sebelumnya, secara default, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai dibaca.

Pendekatan alternatif saat menggunakan pola opsi adalah mengikat bagian Position dan menambahkannya ke kontainer layanan injeksi dependensi. Dalam kode berikut, PositionOptions ditambahkan ke kontainer layanan dengan Configure dan terikat ke konfigurasi:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));

var app = builder.Build();

Dengan menggunakan kode sebelumnya, kode berikut membaca opsi posisi:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Dalam kode sebelumnya, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai tidak dibaca. Untuk membaca perubahan setelah aplikasi dimulai, gunakan IOptionsSnapshot.

Lihat JSpenyedia konfigurasi ON dalam dokumen ini untuk informasi tentang menambahkan file konfigurasi ON tambahan JS.

Menggabungkan kumpulan layanan

Pertimbangkan hal berikut yang mendaftarkan layanan dan mengonfigurasi opsi:

using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
    builder.Configuration.GetSection(ColorOptions.Color));

builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();

var app = builder.Build();

Grup pendaftaran terkait dapat dipindahkan ke metode ekstensi untuk mendaftarkan layanan. Misalnya, layanan konfigurasi ditambahkan ke kelas berikut:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }
    }
}

Layanan yang tersisa terdaftar di kelas serupa. Kode berikut menggunakan metode ekstensi baru untuk mendaftarkan layanan:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddConfig(builder.Configuration)
    .AddMyDependencyGroup();

builder.Services.AddRazorPages();

var app = builder.Build();

Catatan: Setiap services.Add{GROUP_NAME} metode ekstensi menambahkan dan berpotensi mengonfigurasi layanan. Misalnya, AddControllersWithViews menambahkan pengontrol MVC layanan dengan tampilan memerlukan, dan AddRazorPages menambahkan layanan yang Razor diperlukan Pages. Sebaiknya aplikasi mengikuti konvensi penamaan pembuatan metode ekstensi di Microsoft.Extensions.DependencyInjection namespace layanan. Membuat metode ekstensi di Microsoft.Extensions.DependencyInjection namespace:

Merangkum grup pendaftaran layanan.
Menyediakan akses IntelliSense yang nyaman ke layanan.

Rahasia keamanan dan pengguna

Panduan data konfigurasi:

Jangan pernah menyimpan kata sandi atau data sensitif lainnya dalam kode penyedia konfigurasi atau dalam file konfigurasi teks biasa. Alat Secret Manager dapat digunakan untuk menyimpan rahasia dalam pengembangan.
Jangan gunakan rahasia produksi di lingkungan pengembangan atau pengujian.
Tentukan rahasia di luar proyek sehingga tidak dapat diterapkan secara tidak sengaja ke repositori kode sumber.

Secara default, sumber konfigurasi rahasia pengguna didaftarkan setelah JSsumber konfigurasi ON. Oleh karena itu, kunci rahasia pengguna lebih diutamakan daripada kunci di appsettings.json dan appsettings.{Environment}.json.

Untuk informasi selengkapnya tentang menyimpan kata sandi atau data sensitif lainnya:

Gunakan beberapa lingkungan di ASP.NET Core
Penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core: Mencakup saran tentang menggunakan variabel lingkungan untuk menyimpan data sensitif. Alat Secret Manager menggunakan penyedia konfigurasi File untuk menyimpan rahasia pengguna dalam JSfile ON pada sistem lokal.

Azure Key Vault menyimpan rahasia aplikasi dengan aman untuk aplikasi ASP.NET Core. Untuk informasi selengkapnya, lihat Penyedia konfigurasi Azure Key Vault di ASP.NET Core.

Variabel lingkungan yang tidak diawali

Variabel lingkungan yang tidak diawali adalah variabel lingkungan selain yang diawali oleh ASPNETCORE_ atau DOTNET_. Misalnya, templat aplikasi web ASP.NET Core diatur "ASPNETCORE_ENVIRONMENT": "Development" di launchSettings.json. Untuk informasi selengkapnya tentang ASPNETCORE_ variabel lingkungan dan DOTNET_ , lihat:

Daftar sumber konfigurasi default prioritas tertinggi hingga terendah termasuk variabel lingkungan non-prefiks, -prefiks, ASPNETCORE_dan DOTNETCORE_-prefiks.
DOTNET_ variabel lingkungan yang digunakan di luar Microsoft.Extensions.Hosting.

Menggunakan konfigurasi default, EnvironmentVariablesConfigurationProvider memuat konfigurasi dari pasangan kunci-nilai variabel lingkungan setelah membaca appsettings.jsonrahasia pengguna , appsettings.{Environment}.json, dan . Oleh karena itu, nilai kunci yang dibaca dari lingkungan mengambil alih nilai yang dibaca dari appsettings.jsonrahasia pengguna , appsettings.{Environment}.json, dan .

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. __, garis bawah ganda, adalah:

Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __ adalah.
Diganti secara otomatis oleh :

Perintah berikut set :

Atur kunci lingkungan dan nilai contoh sebelumnya di Windows.
Uji pengaturan saat menggunakan unduhan sampel. Perintah dotnet run harus dijalankan di direktori proyek.

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Pengaturan lingkungan sebelumnya:

Hanya diatur dalam proses yang diluncurkan dari jendela perintah tempat mereka diatur.
Tidak akan dibaca oleh browser yang diluncurkan dengan Visual Studio.

Perintah setx berikut dapat digunakan untuk mengatur kunci dan nilai lingkungan di Windows. Tidak seperti set, setx pengaturan tetap ada. /M mengatur variabel di lingkungan sistem. Jika sakelar /M tidak digunakan, variabel lingkungan pengguna diatur.

setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Untuk menguji bahwa perintah sebelumnya mengambil alih appsettings.json dan appsettings.{Environment}.json:

Dengan Visual Studio: Keluar dan mulai ulang Visual Studio.
Dengan CLI: Mulai jendela perintah baru dan masukkan dotnet run.

Panggil AddEnvironmentVariables dengan string untuk menentukan awalan untuk variabel lingkungan:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");

var app = builder.Build();

Dalam kode sebelumnya:

builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_") ditambahkan setelah penyedia konfigurasi default. Untuk contoh pemesanan penyedia konfigurasi, lihat JSPenyedia konfigurasi ON.
Variabel lingkungan yang diatur dengan awalan MyCustomPrefix_ mengambil alih penyedia konfigurasi default. Ini termasuk variabel lingkungan tanpa awalan.

Awalan dilucuti saat pasangan kunci-nilai konfigurasi dibaca.

Perintah berikut menguji awalan kustom:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Konfigurasi default memuat variabel lingkungan dan argumen baris perintah yang diawali dengan DOTNET_ dan ASPNETCORE_. DOTNET_ Awalan dan ASPNETCORE_ digunakan oleh ASP.NET Core untuk konfigurasi host dan aplikasi, tetapi tidak untuk konfigurasi pengguna. Untuk informasi selengkapnya tentang konfigurasi host dan aplikasi, lihat Host Generik .NET.

Pada Azure App Service, pilih Pengaturan aplikasi baru di halaman Konfigurasi Pengaturan>. Azure App Service pengaturan aplikasi adalah:

Dienkripsi saat tidak aktif dan ditransmisikan melalui saluran terenkripsi.
Diekspos sebagai variabel lingkungan.

Untuk informasi selengkapnya, lihat Aplikasi Azure: Mengambil alih konfigurasi aplikasi menggunakan Portal Microsoft Azure.

Lihat Awalan string koneksi untuk informasi tentang string koneksi database Azure.

Penamaan variabel lingkungan

Nama variabel lingkungan mencerminkan struktur appsettings.json file. Setiap elemen dalam hierarki dipisahkan oleh garis bawah ganda (lebih disukai) atau titik dua. Ketika struktur elemen menyertakan array, indeks array harus diperlakukan sebagai nama elemen tambahan di jalur ini. Pertimbangkan file berikut appsettings.json dan nilai yang setara yang direpresentasikan sebagai variabel lingkungan.

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

variabel lingkungan

setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information

Variabel lingkungan diatur dalam launchSettings.json yang dihasilkan

Variabel lingkungan yang diatur dalam launchSettings.json mengambil alih yang ditetapkan di lingkungan sistem. Misalnya, templat web ASP.NET Core menghasilkan launchSettings.json file yang mengatur konfigurasi titik akhir ke:

"applicationUrl": "https://localhost:5001;http://localhost:5000"

Mengonfigurasi applicationUrl set ASPNETCORE_URLS variabel lingkungan dan mengambil alih nilai yang ditetapkan di lingkungan.

Variabel lingkungan escape di Linux

Di Linux, nilai variabel lingkungan URL harus diloloskan sehingga systemd dapat mengurainya. Gunakan alat systemd-escape linux yang menghasilkan http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Menampilkan variabel lingkungan

Kode berikut menampilkan variabel lingkungan dan nilai pada startup aplikasi, yang dapat membantu saat men-debug pengaturan lingkungan:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

foreach (var c in builder.Configuration.AsEnumerable())
{
    Console.WriteLine(c.Key + " = " + c.Value);
}

Baris perintah

Menggunakan konfigurasi default , CommandLineConfigurationProvider memuat konfigurasi dari pasangan kunci-nilai argumen baris perintah setelah sumber konfigurasi berikut:

appsettings.json dan appsettings.{Environment}.json file.
Rahasia aplikasi di lingkungan Pengembangan.
Variabel lingkungan.

Secara default, nilai konfigurasi yang diatur pada baris perintah mengambil alih nilai konfigurasi yang ditetapkan dengan semua penyedia konfigurasi lainnya.

Argumen baris perintah

Perintah berikut mengatur kunci dan nilai menggunakan =:

dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick

Perintah berikut mengatur kunci dan nilai menggunakan /:

dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick

Perintah berikut mengatur kunci dan nilai menggunakan --:

dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick

Nilai kunci:

Harus mengikuti =, atau kunci harus memiliki awalan -- atau / ketika nilai mengikuti spasi.
Tidak diperlukan jika = digunakan. Contohnya:MySetting=

Dalam perintah yang sama, jangan mencampur pasangan kunci-nilai argumen baris perintah yang digunakan = dengan pasangan kunci-nilai yang menggunakan spasi.

Beralih pemetaan

Pemetaan sakelar memungkinkan logika penggantian nama kunci . Berikan kamus penggantian sakelar ke AddCommandLine metode .

Saat kamus pemetaan sakelar digunakan, kamus diperiksa untuk kunci yang cocok dengan kunci yang disediakan oleh argumen baris perintah. Jika kunci baris perintah ditemukan di kamus, nilai kamus diteruskan kembali untuk mengatur pasangan kunci-nilai ke dalam konfigurasi aplikasi. Pemetaan sakelar diperlukan untuk setiap kunci baris perintah yang diawali dengan tanda hubung tunggal (-).

Beralih aturan kunci kamus pemetaan:

Sakelar harus dimulai dengan - atau --.
Kamus pemetaan sakelar tidak boleh berisi kunci duplikat.

Untuk menggunakan kamus pemetaan sakelar, teruskan ke dalam panggilan ke AddCommandLine:


var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

builder.Configuration.AddCommandLine(args, switchMappings);

var app = builder.Build();

Jalankan perintah berikut berfungsi untuk menguji penggantian kunci:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Kode berikut menunjukkan nilai kunci untuk kunci yang diganti:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

Untuk aplikasi yang menggunakan pemetaan sakelar, panggilan ke CreateDefaultBuilder tidak boleh meneruskan argumen. Panggilan CreateDefaultBuilder metode AddCommandLine tidak menyertakan sakelar yang dipetakan, dan tidak ada cara untuk meneruskan kamus pemetaan sakelar ke CreateDefaultBuilder. Solusinya bukan untuk meneruskan argumen CreateDefaultBuilder tetapi sebagai gantinya untuk memungkinkan ConfigurationBuilder metode metode AddCommandLine memproses argumen dan kamus pemetaan sakelar.

Mengatur argumen lingkungan dan baris perintah dengan Visual Studio

Argumen lingkungan dan baris perintah dapat diatur di Visual Studio dari dialog profil peluncuran:

Di Penjelajah Solusi, klik kanan proyek dan pilih Properti.
Pilih tab Umum Debug > dan pilih Buka antarmuka pengguna profil peluncuran debug.

Data konfigurasi hierarkis

API Konfigurasi membaca data konfigurasi hierarkis dengan meratakan data hierarkis dengan penggunaan pemisah di kunci konfigurasi.

Unduhan sampel berisi file berikutappsettings.json:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Cara yang disukai untuk membaca data konfigurasi hierarkis adalah menggunakan pola opsi. Untuk informasi selengkapnya, lihat Mengikat data konfigurasi hierarkis dalam dokumen ini.

GetSection dan GetChildren metode tersedia untuk mengisolasi bagian dan turunan dari bagian dalam data konfigurasi. Metode ini dijelaskan nanti di GetSection, GetChildren, dan Exists.

Kunci dan nilai konfigurasi

Kunci konfigurasi:

Tidak peka huruf besar/kecil. Misalnya, ConnectionString dan connectionstring dianggap sebagai kunci yang setara.
Jika kunci dan nilai diatur di lebih dari satu penyedia konfigurasi, nilai dari penyedia terakhir yang ditambahkan akan digunakan. Untuk informasi selengkapnya, lihat Konfigurasi default.
Kunci hierarkis
- Dalam API Konfigurasi, pemisah titik dua (:) berfungsi di semua platform.
- Dalam variabel lingkungan, pemisah titik dua mungkin tidak berfungsi pada semua platform. Garis bawah ganda, __, didukung oleh semua platform dan secara otomatis dikonversi menjadi titik dua :.
- Di Azure Key Vault, kunci hierarkis digunakan -- sebagai pemisah. Penyedia konfigurasi Azure Key Vault secara otomatis mengganti -- dengan : saat rahasia dimuat ke dalam konfigurasi aplikasi.
ConfigurationBinder mendukung pengikatan array ke objek menggunakan indeks array dalam kunci konfigurasi. Pengikatan array dijelaskan di bagian Ikat array ke kelas .

Nilai konfigurasi:

Adalah string.
Nilai null tidak dapat disimpan dalam konfigurasi atau terikat ke objek.

Penyedia konfigurasi

Tabel berikut menunjukkan penyedia konfigurasi yang tersedia untuk aplikasi ASP.NET Core.

Penyedia	Menyediakan konfigurasi dari
Penyedia konfigurasi Azure Key Vault	Azure Key Vault
Penyedia konfigurasi Azure App	Azure App Configuration
Penyedia konfigurasi baris perintah	Parameter baris perintah
Penyedia konfigurasi kustom	Sumber kustom
Penyedia konfigurasi Variabel Lingkungan	Variabel lingkungan
Penyedia konfigurasi file	File INI, JSON, dan XML
Penyedia konfigurasi kunci per file	File direktori
Penyedia konfigurasi memori	Koleksi dalam memori
Rahasia pengguna	File di direktori profil pengguna

Sumber konfigurasi dibaca dalam urutan penyedia konfigurasi mereka ditentukan. Pesan penyedia konfigurasi dalam kode agar sesuai dengan prioritas untuk sumber konfigurasi mendasar yang diperlukan aplikasi.

Urutan umum penyedia konfigurasi adalah:

appsettings.json
appsettings.{Environment}.json
Rahasia pengguna
Variabel lingkungan menggunakan penyedia konfigurasi Variabel Lingkungan.
Argumen baris perintah menggunakan penyedia konfigurasi baris Perintah.

Praktik umumnya adalah menambahkan penyedia konfigurasi Baris perintah terakhir dalam serangkaian penyedia untuk memungkinkan argumen baris perintah mengambil alih konfigurasi yang ditetapkan oleh penyedia lain.

Urutan penyedia sebelumnya digunakan dalam konfigurasi default.

Awalan string koneksi

API Konfigurasi memiliki aturan pemrosesan khusus untuk empat variabel lingkungan string koneksi. String koneksi ini terlibat dalam mengonfigurasi string koneksi Azure untuk lingkungan aplikasi. Variabel lingkungan dengan awalan yang ditampilkan dalam tabel dimuat ke dalam aplikasi dengan konfigurasi default atau ketika tidak ada awalan yang disediakan ke AddEnvironmentVariables.

Awalan string koneksi	Penyedia
`CUSTOMCONNSTR_`	Penyedia kustom
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Azure SQL Database
`SQLCONNSTR_`	SQL Server

Saat variabel lingkungan ditemukan dan dimuat ke dalam konfigurasi dengan salah satu dari empat awalan yang ditunjukkan dalam tabel:

Kunci konfigurasi dibuat dengan menghapus awalan variabel lingkungan dan menambahkan bagian kunci konfigurasi (ConnectionStrings).
Pasangan kunci-nilai konfigurasi baru dibuat yang mewakili penyedia koneksi database (kecuali CUSTOMCONNSTR_, yang tidak memiliki penyedia yang dinyatakan).

Kunci variabel lingkungan	Kunci konfigurasi yang dikonversi	Entri konfigurasi penyedia
`CUSTOMCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Entri konfigurasi tidak dibuat.
`MYSQLCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `MySql.Data.MySqlClient`
`SQLAZURECONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `System.Data.SqlClient`
`SQLCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `System.Data.SqlClient`

Penyedia konfigurasi file

FileConfigurationProvider adalah kelas dasar untuk memuat konfigurasi dari sistem file. Penyedia konfigurasi berikut berasal dari FileConfigurationProvider:

Penyedia konfigurasi INI
JSPenyedia konfigurasi ON
Penyedia konfigurasi XML

Penyedia konfigurasi INI

Memuat IniConfigurationProvider konfigurasi dari pasangan kunci-nilai file INI saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
          .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Dalam kode sebelumnya, pengaturan dalam MyIniConfig.ini file dan MyIniConfig.{Environment}.ini ditimpa oleh pengaturan di:

Penyedia konfigurasi variabel lingkungan
Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file berikutMyIniConfig.ini:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JSPenyedia konfigurasi ON

Memuat JsonConfigurationProvider konfigurasi dari JSpasangan kunci-nilai file ON.

Kelebihan beban dapat menentukan:

Apakah file bersifat opsional.
Apakah konfigurasi dimuat ulang jika file berubah.

Pertimbangkan kode berikut:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyConfig.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Kode sebelumnya:

JSMengonfigurasi penyedia konfigurasi ON untuk memuat MyConfig.json file dengan opsi berikut:
- optional: true: File bersifat opsional.
- reloadOnChange: true : File dimuat ulang saat perubahan disimpan.
Membaca penyedia konfigurasi default sebelum MyConfig.json file. Pengaturan dalam MyConfig.json pengaturan penimpaan file di penyedia konfigurasi default, termasuk penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi baris Perintah.

Anda biasanya tidak ingin nilai penimpaan file ON kustom JSdiatur dalam penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi Baris perintah.

Penyedia konfigurasi XML

Memuat XmlConfigurationProvider konfigurasi dari pasangan kunci-nilai file XML saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
          .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Dalam kode sebelumnya, pengaturan dalam MyXMLFile.xml file dan MyXMLFile.{Environment}.xml ditimpa oleh pengaturan di:

Penyedia konfigurasi variabel lingkungan
Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file berikutMyXMLFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Elemen berulang yang menggunakan nama elemen yang sama berfungsi jika name atribut digunakan untuk membedakan elemen:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Kode berikut membaca file konfigurasi sebelumnya dan menampilkan kunci dan nilai:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

Atribut dapat digunakan untuk menyediakan nilai:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

File konfigurasi sebelumnya memuat kunci berikut dengan value:

key:attribute
section:key:attribute

Penyedia konfigurasi kunci per file

KeyPerFileConfigurationProvider menggunakan file direktori sebagai pasangan kunci-nilai konfigurasi. Kuncinya adalah nama file. Nilai berisi konten file. Penyedia konfigurasi Kunci per file digunakan dalam skenario hosting Docker.

Untuk mengaktifkan konfigurasi kunci per file, panggil AddKeyPerFile metode ekstensi pada instans ConfigurationBuilder. ke directoryPath file harus merupakan jalur absolut.

Izin kelebihan beban yang menentukan:

Delegasi Action<KeyPerFileConfigurationSource> yang mengonfigurasi sumber.
Apakah direktori bersifat opsional dan jalur ke direktori.

Garis bawah ganda (__) digunakan sebagai pemisah kunci konfigurasi dalam nama file. Misalnya, nama Logging__LogLevel__System file menghasilkan kunci Logging:LogLevel:Systemkonfigurasi .

Panggil ConfigureAppConfiguration saat membangun host untuk menentukan konfigurasi aplikasi:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Penyedia konfigurasi memori

MemoryConfigurationProvider menggunakan koleksi dalam memori sebagai pasangan kunci-nilai konfigurasi.

Kode berikut menambahkan koleksi memori ke sistem konfigurasi:

var builder = WebApplication.CreateBuilder(args);

var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Kode berikut dari unduhan sampel menampilkan pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Dalam kode sebelumnya, config.AddInMemoryCollection(Dict) ditambahkan setelah penyedia konfigurasi default. Untuk contoh pemesanan penyedia konfigurasi, lihat JSPenyedia konfigurasi ON.

Lihat Mengikat array untuk contoh lain menggunakan MemoryConfigurationProvider.

Kestrel konfigurasi titik akhir

Kestrel konfigurasi titik akhir tertentu mengambil alih semua konfigurasi titik akhir lintas server . Konfigurasi titik akhir lintas server meliputi:

UseUrls
--urls pada baris perintah
Variabel lingkunganASPNETCORE_URLS

Pertimbangkan file berikut appsettings.json yang digunakan dalam aplikasi web ASP.NET Core:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Saat markup yang disorot sebelumnya digunakan dalam aplikasi web ASP.NET Core dan aplikasi diluncurkan pada baris perintah dengan konfigurasi titik akhir lintas server berikut:

dotnet run --urls="https://localhost:7777"

Kestrelmengikat ke titik akhir yang dikonfigurasi khusus untuk Kestrel dalam file (https://localhost:9999) dan bukan https://localhost:7777appsettings.json .

Pertimbangkan titik akhir tertentu yang dikonfigurasi Kestrel sebagai variabel lingkungan:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dalam variabel lingkungan sebelumnya, Https adalah nama Kestrel titik akhir tertentu. File sebelumnya appsettings.json juga menentukan titik akhir tertentu Kestrel bernama Https. Secara default, variabel lingkungan yang menggunakan penyedia konfigurasi Variabel Lingkungan dibaca setelah appsettings.{Environment}.json, oleh karena itu, variabel lingkungan sebelumnya digunakan untuk Https titik akhir.

GetValue

ConfigurationBinder.GetValue mengekstrak satu nilai dari konfigurasi dengan kunci tertentu dan mengonversinya ke jenis yang ditentukan:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Dalam kode sebelumnya, jika NumberKey tidak ditemukan dalam konfigurasi, nilai 99 default digunakan.

GetSection, GetChildren, dan Exists

Untuk contoh berikut, pertimbangkan file berikut MySubsection.json :

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

Kode berikut menambahkan MySubsection.json ke penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MySubsection.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection mengembalikan sub bagian konfigurasi dengan kunci sub-bagian yang ditentukan.

Kode berikut mengembalikan nilai untuk section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Kode berikut mengembalikan nilai untuk section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

GetSection tidak pernah mengembalikan null. Jika bagian yang cocok tidak ditemukan, kosong IConfigurationSection akan dikembalikan.

Saat GetSection mengembalikan bagian yang cocok, Value tidak diisi. A Key dan Path dikembalikan ketika bagian ada.

GetChildren dan Exists

Kode berikut memanggil IConfiguration.GetChildren dan mengembalikan nilai untuk section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = "";
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Panggilan ConfigurationExtensions.Exists kode sebelumnya untuk memverifikasi bagian tersebut ada:

Mengikat array

ConfigurationBinder.Bind mendukung pengikatan array ke objek menggunakan indeks array dalam kunci konfigurasi. Format array apa pun yang mengekspos segmen kunci numerik mampu mengikat array ke array kelas POCO .

Pertimbangkan MyArray.json dari unduhan sampel:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

Kode berikut menambahkan MyArray.json ke penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyArray.json",
                        optional: true,
                        reloadOnChange: true); ;
});

builder.Services.AddRazorPages();

var app = builder.Build();

Kode berikut membaca konfigurasi dan menampilkan nilai:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample? _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
       _array = Config.GetSection("array").Get<ArrayExample>();
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }
        string s = String.Empty;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

Kode sebelumnya mengembalikan output berikut:

Index: 0  Value: value00
Index: 1  Value: value10
Index: 2  Value: value20
Index: 3  Value: value40
Index: 4  Value: value50

Dalam output sebelumnya, Indeks 3 memiliki nilai value40, yang "4": "value40", sesuai dengan di MyArray.json. Indeks array terikat berkelanjutan dan tidak terikat ke indeks kunci konfigurasi. Pengikat konfigurasi tidak mampu mengikat nilai null atau membuat entri null dalam objek terikat.

Penyedia konfigurasi kustom

Aplikasi sampel menunjukkan cara membuat penyedia konfigurasi dasar yang membaca pasangan kunci-nilai konfigurasi dari database menggunakan Kerangka Kerja Entitas (EF).

Penyedia memiliki karakteristik berikut:

Database dalam memori EF digunakan untuk tujuan demonstrasi. Untuk menggunakan database yang memerlukan string koneksi, terapkan sekunder ConfigurationBuilder untuk menyediakan string koneksi dari penyedia konfigurasi lain.
Penyedia membaca tabel database ke dalam konfigurasi saat startup. Penyedia tidak mengkueri database berdasarkan per kunci.
Muat ulang saat perubahan tidak diimplementasikan, jadi memperbarui database setelah aplikasi dimulai tidak berpengaruh pada konfigurasi aplikasi.

EFConfigurationValue Tentukan entitas untuk menyimpan nilai konfigurasi dalam database.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; } = String.Empty;
    public string Value { get; set; } = String.Empty;
}

Tambahkan untuk menyimpan dan mengakses nilai yang EFConfigurationContext dikonfigurasi.

EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions<EFConfigurationContext> options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

Membuat kelas yang mengimplementasikan IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => _optionsAction = optionsAction;

    public IConfigurationProvider Build(IConfigurationBuilder builder) => new EFConfigurationProvider(_optionsAction);
}

Buat penyedia konfigurasi kustom dengan mewarisi dari ConfigurationProvider. Penyedia konfigurasi menginisialisasi database saat kosong. Karena kunci konfigurasi tidak peka huruf besar/kecil, kamus yang digunakan untuk menginisialisasi database dibuat dengan pembanding yang tidak peka huruf besar/kecil (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            if (dbContext == null || dbContext.Values == null)
            {
                throw new Exception("Null DB context");
            }
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues =
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                    { "quote1", "I aim to misbehave." },
                    { "quote2", "I swallowed a bug." },
                    { "quote3", "You can't stop the signal, Mal." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue
            {
                Id = kvp.Key,
                Value = kvp.Value
            })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

AddEFConfiguration Metode ekstensi memungkinkan penambahan sumber konfigurasi ke ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
               this IConfigurationBuilder builder,
               Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Kode berikut menunjukkan cara menggunakan kustom EFConfigurationProvider dalam Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

var app = builder.Build();

app.Run();

Konfigurasi akses dengan Injeksi Dependensi (DI)

Konfigurasi dapat disuntikkan ke layanan menggunakan Dependency Injection (DI) dengan menyelesaikan IConfiguration layanan:

public class Service
{
    private readonly IConfiguration _config;

    public Service(IConfiguration config) =>
        _config = config;

    public void DoSomething()
    {
        var configSettingValue = _config["ConfigSetting"];

        // ...
    }
}

Untuk informasi tentang cara mengakses nilai menggunakan IConfiguration, lihat GetValue dan GetSection, GetChildren, dan Exists di artikel ini.

Mengakses konfigurasi di Razor Pages

Kode berikut menampilkan data konfigurasi di Razor Halaman:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Dalam kode berikut, MyOptions ditambahkan ke kontainer layanan dengan Configure dan terikat ke konfigurasi:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

var app = builder.Build();

Markup berikut menggunakan direktif @injectRazor untuk mengatasi dan menampilkan nilai opsi:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Konfigurasi akses dalam file tampilan MVC

Kode berikut menampilkan data konfigurasi dalam tampilan MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Konfigurasi akses di `Program.cs`

Kode berikut mengakses konfigurasi dalam Program.cs file.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

var key1 = app.Configuration.GetValue<int>("KeyOne");
var key2 = app.Configuration.GetValue<bool>("KeyTwo");

app.Logger.LogInformation($"KeyOne = {key1}");
app.Logger.LogInformation($"KeyTwo = {key2}");

app.Run();

Mengonfigurasi opsi dengan delegasi

Opsi yang dikonfigurasi dalam delegasi mengambil alih nilai yang ditetapkan di penyedia konfigurasi.

Dalam kode berikut, IConfigureOptions<TOptions> layanan ditambahkan ke kontainer layanan. Ini menggunakan delegasi untuk mengonfigurasi nilai untuk MyOptions:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "Value configured in delegate";
    myOptions.Option2 = 500;
});

var app = builder.Build();

Kode berikut menampilkan nilai opsi:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Dalam contoh sebelumnya, nilai Option1 dan Option2 ditentukan di appsettings.json lalu ditimpa oleh delegasi yang dikonfigurasi.

Host versus konfigurasi aplikasi

Sebelum aplikasi dikonfigurasi dan dimulai, host dikonfigurasi dan diluncurkan. Host bertanggung jawab atas startup aplikasi dan manajemen seumur hidup. Aplikasi dan host dikonfigurasi menggunakan penyedia konfigurasi yang dijelaskan dalam topik ini. Pasangan kunci-nilai konfigurasi host juga disertakan dalam konfigurasi aplikasi. Untuk informasi selengkapnya tentang bagaimana penyedia konfigurasi digunakan saat host dibuat dan bagaimana sumber konfigurasi memengaruhi konfigurasi host, lihat gambaran umum dasar-dasar ASP.NET Core.

Konfigurasi host default

Untuk detail tentang konfigurasi default saat menggunakan Web Host, lihat versi ASP.NET Core 2.2 dari topik ini.

Konfigurasi host disediakan dari:
- Variabel lingkungan diawali dengan DOTNET_ (misalnya, DOTNET_ENVIRONMENT) menggunakan penyedia konfigurasi Variabel Lingkungan. Awalan (DOTNET_) dilucuti saat pasangan kunci-nilai konfigurasi dimuat.
- Argumen baris perintah menggunakan penyedia konfigurasi Baris perintah.
Konfigurasi default Web Host dibuat (ConfigureWebHostDefaults):
- Kestrel digunakan sebagai server web dan dikonfigurasi menggunakan penyedia konfigurasi aplikasi.
- Tambahkan Middleware Pemfilteran Host.
- Tambahkan Middleware Header yang Diteruskan jika ASPNETCORE_FORWARDEDHEADERS_ENABLED variabel lingkungan diatur ke true.
- Aktifkan integrasi IIS.

Konfigurasi lainnya

Topik ini hanya berkaitan dengan konfigurasi aplikasi. Aspek lain dari menjalankan dan menghosting aplikasi ASP.NET Core dikonfigurasi menggunakan file konfigurasi yang tidak tercakup dalam topik ini:

launch.json/launchSettings.json adalah file konfigurasi alat untuk lingkungan Pengembangan, dijelaskan:
- Di Gunakan beberapa lingkungan di ASP.NET Core.
- Di seluruh kumpulan dokumentasi tempat file digunakan untuk mengonfigurasi aplikasi ASP.NET Core untuk skenario Pengembangan.
web.config adalah file konfigurasi server, yang dijelaskan dalam topik berikut:
- Host ASP.NET Core di Windows dengan IIS
- ASP.NET Core Module (ANCM) untuk IIS

Variabel lingkungan yang diatur dalam launchSettings.json mengambil alih yang ditetapkan di lingkungan sistem.

Untuk informasi selengkapnya tentang migrasi konfigurasi aplikasi dari versi ASP.NET yang lebih lama, lihat Migrasi dari ASP.NET ke ASP.NET Core.

Menambahkan konfigurasi dari rakitan eksternal

Implementasi IHostingStartup memungkinkan penambahan penyempurnaan ke aplikasi saat startup dari rakitan eksternal di luar kelas aplikasi Startup . Untuk informasi selengkapnya, lihat Menggunakan rakitan startup hosting di ASP.NET Core.

Sumber Daya Tambahan:

File pengaturan, seperti appsettings.json
Variabel lingkungan
Azure Key Vault
Azure App Configuration
Argumen baris perintah
Penyedia kustom, terinstal atau dibuat
File direktori
Objek .NET dalam memori

Artikel ini menyediakan informasi tentang konfigurasi di ASP.NET Core. Untuk informasi tentang menggunakan konfigurasi di aplikasi konsol, lihat Konfigurasi .NET.

Konfigurasi Aplikasi dan Host

Konfigurasi aplikasi adalah prioritas tertinggi dan dirinci di bagian berikutnya. Konfigurasi host mengikuti konfigurasi aplikasi, dan dijelaskan dalam artikel ini.

Sumber konfigurasi aplikasi default

ASP.NET Core web yang dibuat dengan dotnet baru atau Visual Studio menghasilkan kode berikut:

var builder = WebApplication.CreateBuilder(args);

Argumen baris perintah menggunakan penyedia konfigurasi Baris perintah.
Variabel lingkungan yang tidak diawali menggunakan penyedia konfigurasi Variabel lingkungan yang tidak diawali.
Rahasia pengguna saat aplikasi berjalan di Development lingkungan.
appsettings.{Environment}.jsonJSmenggunakan penyedia konfigurasi ON. Misalnya, appsettings.Production.json dan appsettings.Development.json.
appsettings.json menggunakan JSpenyedia konfigurasi ON.
Fallback ke konfigurasi host yang dijelaskan di bagian berikutnya.

Sumber konfigurasi host default

Daftar berikut berisi sumber konfigurasi host default dari prioritas tertinggi hingga terendah:

Argumen baris perintah menggunakan penyedia konfigurasi Baris perintah
ASPNETCORE_-variabel lingkungan awalan menggunakan penyedia konfigurasi variabel Lingkungan.
DOTNET_-variabel lingkungan awalan menggunakan penyedia konfigurasi variabel Lingkungan.

Ketika nilai konfigurasi diatur dalam konfigurasi host dan aplikasi, konfigurasi aplikasi digunakan.

Variabel host

Variabel berikut dikunci di awal saat menginisialisasi penyusun host dan tidak dapat dipengaruhi oleh konfigurasi aplikasi:

Nama aplikasi
Nama lingkungan, misalnya Development, , Productiondan Staging
Akar konten
Akar web
Apakah akan memindai rakitan startup hosting dan rakitan mana yang akan dipindai.
Variabel yang dibaca oleh aplikasi dan kode pustaka dari HostBuilderContext.Configuration di IHostBuilder.ConfigureAppConfiguration callbacks.

Setiap pengaturan host lainnya dibaca dari konfigurasi aplikasi alih-alih konfigurasi host.

Untuk informasi selengkapnya, lihat Mengubah akar konten, nama aplikasi, dan lingkungan dan Mengubah akar konten, nama aplikasi, dan lingkungan menurut variabel lingkungan atau baris perintah

Bagian yang tersisa dalam artikel ini mengacu pada konfigurasi aplikasi.

Penyedia konfigurasi aplikasi

Kode berikut menampilkan penyedia konfigurasi yang diaktifkan dalam urutan ditambahkan:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

Untuk informasi selengkapnya tentang CreateBuilder, lihat Pengaturan penyusun default.

`appsettings.json`

Pertimbangkan file berikut appsettings.json :

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JsonConfigurationProvider Default memuat konfigurasi dalam urutan berikut:

appsettings.json
appsettings.{Environment}.json : Misalnya, appsettings.Production.json file dan appsettings.Development.json . Versi lingkungan file dimuat berdasarkan IHostingEnvironment.EnvironmentName. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

appsettings.{Environment}.json nilai mengambil alih kunci di appsettings.json. Misalnya, secara default:

Dalam pengembangan, appsettings.Development.json konfigurasi menimpa nilai yang ditemukan di appsettings.json.
Dalam produksi, appsettings.Production.json konfigurasi menimpa nilai yang ditemukan di appsettings.json. Misalnya, saat menyebarkan aplikasi ke Azure.

Jika nilai konfigurasi harus dijamin, lihat GetValue. Contoh sebelumnya hanya membaca string dan tidak mendukung nilai default.

Mengikat data konfigurasi hierarkis menggunakan pola opsi

Cara yang disukai untuk membaca nilai konfigurasi terkait adalah menggunakan pola opsi. Misalnya, untuk membaca nilai konfigurasi berikut:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Buat kelas berikut PositionOptions :

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; } = String.Empty;
    public string Name { get; set; } = String.Empty;
}

Kelas opsi:

Harus non-abstrak dengan konstruktor tanpa parameter publik.
Semua properti baca-tulis publik dari jenis terikat.
Bidang tidak terikat. Dalam kode sebelumnya, Position tidak terikat. Bidang Position digunakan sehingga string "Position" tidak perlu dikodekan secara permanen di aplikasi saat mengikat kelas ke penyedia konfigurasi.

Kode berikut:

Memanggil ConfigurationBinder.Bind untuk mengikat PositionOptions kelas ke bagian Position .
Position Menampilkan data konfigurasi.

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Dalam kode sebelumnya, secara default, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai dibaca.

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions? positionOptions { get; private set; }

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

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Dalam kode sebelumnya, secara default, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai dibaca.

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));

var app = builder.Build();

Dengan menggunakan kode sebelumnya, kode berikut membaca opsi posisi:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Dalam kode sebelumnya, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai tidak dibaca. Untuk membaca perubahan setelah aplikasi dimulai, gunakan IOptionsSnapshot.

Lihat JSPenyedia konfigurasi ON dalam dokumen ini untuk informasi tentang menambahkan file konfigurasi ON tambahan JS.

Menggabungkan kumpulan layanan

Pertimbangkan hal berikut yang mendaftarkan layanan dan mengonfigurasi opsi:

using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
    builder.Configuration.GetSection(ColorOptions.Color));

builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();

var app = builder.Build();

Grup pendaftaran terkait dapat dipindahkan ke metode ekstensi untuk mendaftarkan layanan. Misalnya, layanan konfigurasi ditambahkan ke kelas berikut:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }
    }
}

Layanan yang tersisa terdaftar di kelas serupa. Kode berikut menggunakan metode ekstensi baru untuk mendaftarkan layanan:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddConfig(builder.Configuration)
    .AddMyDependencyGroup();

builder.Services.AddRazorPages();

var app = builder.Build();

Catatan: Setiap services.Add{GROUP_NAME} metode ekstensi menambahkan dan berpotensi mengonfigurasi layanan. Misalnya, AddControllersWithViews menambahkan pengontrol MVC layanan dengan tampilan yang diperlukan, dan AddRazorPages menambahkan layanan yang Razor diperlukan Halaman. Kami menyarankan agar aplikasi mengikuti konvensi penamaan pembuatan metode ekstensi di Microsoft.Extensions.DependencyInjection namespace layanan. Membuat metode ekstensi di Microsoft.Extensions.DependencyInjection namespace:

Merangkum grup pendaftaran layanan.
Menyediakan akses IntelliSense yang nyaman ke layanan.

Rahasia keamanan dan pengguna

Panduan data konfigurasi:

Jangan pernah menyimpan kata sandi atau data sensitif lainnya dalam kode penyedia konfigurasi atau dalam file konfigurasi teks biasa. Alat Secret Manager dapat digunakan untuk menyimpan rahasia dalam pengembangan.
Jangan gunakan rahasia produksi di lingkungan pengembangan atau pengujian.
Tentukan rahasia di luar proyek sehingga tidak dapat diterapkan secara tidak sengaja ke repositori kode sumber.

Untuk informasi selengkapnya tentang menyimpan kata sandi atau data sensitif lainnya:

Gunakan beberapa lingkungan di ASP.NET Core
Penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core: Mencakup saran tentang menggunakan variabel lingkungan untuk menyimpan data sensitif. Alat Secret Manager menggunakan penyedia konfigurasi File untuk menyimpan rahasia pengguna dalam JSfile ON pada sistem lokal.

Azure Key Vault menyimpan rahasia aplikasi dengan aman untuk aplikasi ASP.NET Core. Untuk informasi selengkapnya, lihat Penyedia konfigurasi Azure Key Vault di ASP.NET Core.

Variabel lingkungan yang tidak diawali

Daftar sumber konfigurasi default prioritas tertinggi hingga terendah termasuk variabel lingkungan non-prefiks, -prefiks, ASPNETCORE_dan DOTNETCORE_-prefiks.
DOTNET_ variabel lingkungan yang digunakan di luar Microsoft.Extensions.Hosting.

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. __, garis bawah ganda, adalah:

Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __ adalah.
Diganti secara otomatis oleh :

Perintah berikut set :

Atur kunci lingkungan dan nilai contoh sebelumnya di Windows.
Uji pengaturan saat menggunakan unduhan sampel. Perintah dotnet run harus dijalankan di direktori proyek.

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Pengaturan lingkungan sebelumnya:

Hanya diatur dalam proses yang diluncurkan dari jendela perintah tempat mereka diatur.
Tidak akan dibaca oleh browser yang diluncurkan dengan Visual Studio.

setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Untuk menguji bahwa perintah sebelumnya mengambil alih appsettings.json dan appsettings.{Environment}.json:

Dengan Visual Studio: Keluar dan mulai ulang Visual Studio.
Dengan CLI: Mulai jendela perintah baru dan masukkan dotnet run.

Panggil AddEnvironmentVariables dengan string untuk menentukan awalan untuk variabel lingkungan:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");

var app = builder.Build();

Dalam kode sebelumnya:

builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_") ditambahkan setelah penyedia konfigurasi default. Untuk contoh pemesanan penyedia konfigurasi, lihat JSPenyedia konfigurasi ON.
Variabel lingkungan yang diatur dengan awalan MyCustomPrefix_ mengambil alih penyedia konfigurasi default. Ini termasuk variabel lingkungan tanpa awalan.

Awalan dilucuti saat pasangan kunci-nilai konfigurasi dibaca.

Perintah berikut menguji awalan kustom:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Pada Azure App Service, pilih Pengaturan aplikasi baru di halaman Konfigurasi Pengaturan>. Azure App Service pengaturan aplikasi adalah:

Dienkripsi saat tidak aktif dan ditransmisikan melalui saluran terenkripsi.
Diekspos sebagai variabel lingkungan.

Untuk informasi selengkapnya, lihat Aplikasi Azure: Mengambil alih konfigurasi aplikasi menggunakan Portal Microsoft Azure.

Lihat Awalan string koneksi untuk informasi tentang string koneksi database Azure.

Penamaan variabel lingkungan

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

variabel lingkungan

setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information

Variabel lingkungan diatur dalam launchSettings.json yang dihasilkan

"applicationUrl": "https://localhost:5001;http://localhost:5000"

Mengonfigurasi applicationUrl set ASPNETCORE_URLS variabel lingkungan dan mengambil alih nilai yang ditetapkan di lingkungan.

Variabel lingkungan escape di Linux

Di Linux, nilai variabel lingkungan URL harus diloloskan sehingga systemd dapat mengurainya. Gunakan alat systemd-escape linux yang menghasilkan http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Menampilkan variabel lingkungan

Kode berikut menampilkan variabel lingkungan dan nilai pada startup aplikasi, yang dapat membantu saat men-debug pengaturan lingkungan:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

foreach (var c in builder.Configuration.AsEnumerable())
{
    Console.WriteLine(c.Key + " = " + c.Value);
}

Baris perintah

Menggunakan konfigurasi default , CommandLineConfigurationProvider memuat konfigurasi dari pasangan kunci-nilai argumen baris perintah setelah sumber konfigurasi berikut:

appsettings.json dan appsettings.{Environment}.json file.
Rahasia aplikasi di lingkungan Pengembangan.
Variabel lingkungan.

Secara default, nilai konfigurasi yang diatur pada baris perintah mengambil alih nilai konfigurasi yang ditetapkan dengan semua penyedia konfigurasi lainnya.

Argumen baris perintah

Perintah berikut mengatur kunci dan nilai menggunakan =:

dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick

Perintah berikut mengatur kunci dan nilai menggunakan /:

dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick

Perintah berikut mengatur kunci dan nilai menggunakan --:

dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick

Nilai kunci:

Harus mengikuti =, atau kunci harus memiliki awalan -- atau / ketika nilai mengikuti spasi.
Tidak diperlukan jika = digunakan. Contohnya:MySetting=

Dalam perintah yang sama, jangan mencampur pasangan kunci-nilai argumen baris perintah yang digunakan = dengan pasangan kunci-nilai yang menggunakan spasi.

Beralih pemetaan

Pemetaan sakelar memungkinkan logika penggantian nama kunci . Berikan kamus penggantian sakelar ke AddCommandLine metode .

Beralih aturan kunci kamus pemetaan:

Sakelar harus dimulai dengan - atau --.
Kamus pemetaan sakelar tidak boleh berisi kunci duplikat.

Untuk menggunakan kamus pemetaan sakelar, teruskan ke dalam panggilan ke AddCommandLine:


var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

builder.Configuration.AddCommandLine(args, switchMappings);

var app = builder.Build();

Jalankan perintah berikut berfungsi untuk menguji penggantian kunci:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Kode berikut menunjukkan nilai kunci untuk kunci yang diganti:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

Mengatur argumen lingkungan dan baris perintah dengan Visual Studio

Argumen lingkungan dan baris perintah dapat diatur di Visual Studio dari dialog profil peluncuran:

Di Penjelajah Solusi, klik kanan proyek dan pilih Properti.
Pilih tab Umum Debug > dan pilih Buka antarmuka pengguna profil peluncuran debug.

Data konfigurasi hierarkis

API Konfigurasi membaca data konfigurasi hierarkis dengan meratakan data hierarkis dengan penggunaan pemisah di kunci konfigurasi.

Unduhan sampel berisi file berikutappsettings.json:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Cara yang disukai untuk membaca data konfigurasi hierarkis adalah menggunakan pola opsi. Untuk informasi selengkapnya, lihat Mengikat data konfigurasi hierarkis dalam dokumen ini.

GetSection dan GetChildren metode tersedia untuk mengisolasi bagian dan turunan dari bagian dalam data konfigurasi. Metode ini dijelaskan nanti di GetSection, GetChildren, dan Exists.

Kunci dan nilai konfigurasi

Kunci konfigurasi:

Tidak peka huruf besar/kecil. Misalnya, ConnectionString dan connectionstring dianggap sebagai kunci yang setara.
Jika kunci dan nilai diatur di lebih dari satu penyedia konfigurasi, nilai dari penyedia terakhir yang ditambahkan akan digunakan. Untuk informasi selengkapnya, lihat Konfigurasi default.
Kunci hierarkis
- Dalam API Konfigurasi, pemisah titik dua (:) berfungsi di semua platform.
- Dalam variabel lingkungan, pemisah titik dua mungkin tidak berfungsi pada semua platform. Garis bawah ganda, __, didukung oleh semua platform dan secara otomatis dikonversi menjadi titik dua :.
- Di Azure Key Vault, kunci hierarkis digunakan -- sebagai pemisah. Penyedia konfigurasi Azure Key Vault secara otomatis mengganti -- dengan : saat rahasia dimuat ke dalam konfigurasi aplikasi.
ConfigurationBinder mendukung pengikatan array ke objek menggunakan indeks array dalam kunci konfigurasi. Pengikatan array dijelaskan di bagian Ikat array ke kelas .

Nilai konfigurasi:

Adalah string.
Nilai null tidak dapat disimpan dalam konfigurasi atau terikat ke objek.

Penyedia konfigurasi

Tabel berikut menunjukkan penyedia konfigurasi yang tersedia untuk aplikasi ASP.NET Core.

Penyedia	Menyediakan konfigurasi dari
Penyedia konfigurasi Azure Key Vault	Azure Key Vault
Penyedia konfigurasi Azure App	Azure App Configuration
Penyedia konfigurasi baris perintah	Parameter baris perintah
Penyedia konfigurasi kustom	Sumber kustom
Penyedia konfigurasi Variabel Lingkungan	Variabel lingkungan
Penyedia konfigurasi file	File INI, JSON, dan XML
Penyedia konfigurasi kunci per file	File direktori
Penyedia konfigurasi memori	Koleksi dalam memori
Rahasia pengguna	File di direktori profil pengguna

Urutan umum penyedia konfigurasi adalah:

appsettings.json
appsettings.{Environment}.json
Rahasia pengguna
Variabel lingkungan menggunakan penyedia konfigurasi Variabel Lingkungan.
Argumen baris perintah menggunakan penyedia konfigurasi baris Perintah.

Urutan penyedia sebelumnya digunakan dalam konfigurasi default.

Awalan string koneksi

Awalan string koneksi	Penyedia
`CUSTOMCONNSTR_`	Penyedia kustom
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Azure SQL Database
`SQLCONNSTR_`	SQL Server

Saat variabel lingkungan ditemukan dan dimuat ke dalam konfigurasi dengan salah satu dari empat awalan yang ditunjukkan dalam tabel:

Kunci konfigurasi dibuat dengan menghapus awalan variabel lingkungan dan menambahkan bagian kunci konfigurasi (ConnectionStrings).
Pasangan kunci-nilai konfigurasi baru dibuat yang mewakili penyedia koneksi database (kecuali CUSTOMCONNSTR_, yang tidak memiliki penyedia yang dinyatakan).

Kunci variabel lingkungan	Kunci konfigurasi yang dikonversi	Entri konfigurasi penyedia
`CUSTOMCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Entri konfigurasi tidak dibuat.
`MYSQLCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `MySql.Data.MySqlClient`
`SQLAZURECONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `System.Data.SqlClient`
`SQLCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `System.Data.SqlClient`

Penyedia konfigurasi file

FileConfigurationProvider adalah kelas dasar untuk memuat konfigurasi dari sistem file. Penyedia konfigurasi berikut berasal dari FileConfigurationProvider:

Penyedia konfigurasi INI
JSPenyedia konfigurasi ON
Penyedia konfigurasi XML

Penyedia konfigurasi INI

Memuat IniConfigurationProvider konfigurasi dari pasangan kunci-nilai file INI saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
          .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Dalam kode sebelumnya, pengaturan dalam MyIniConfig.ini file dan MyIniConfig.{Environment}.ini ditimpa oleh pengaturan di:

Penyedia konfigurasi variabel lingkungan
Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file berikutMyIniConfig.ini:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JSPenyedia konfigurasi ON

Memuat JsonConfigurationProvider konfigurasi dari JSpasangan kunci-nilai file ON.

Kelebihan beban dapat menentukan:

Apakah file bersifat opsional.
Apakah konfigurasi dimuat ulang jika file berubah.

Pertimbangkan kode berikut:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyConfig.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Kode sebelumnya:

JSMengonfigurasi penyedia konfigurasi ON untuk memuat MyConfig.json file dengan opsi berikut:
- optional: true: File bersifat opsional.
- reloadOnChange: true : File dimuat ulang saat perubahan disimpan.
Membaca penyedia konfigurasi default sebelum MyConfig.json file. Pengaturan dalam MyConfig.json pengaturan penimpaan file di penyedia konfigurasi default, termasuk penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi baris Perintah.

Anda biasanya tidak ingin nilai penimpaan file ON kustom JSdiatur dalam penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi Baris perintah.

Penyedia konfigurasi XML

Memuat XmlConfigurationProvider konfigurasi dari pasangan kunci-nilai file XML saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
          .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Dalam kode sebelumnya, pengaturan dalam MyXMLFile.xml file dan MyXMLFile.{Environment}.xml ditimpa oleh pengaturan di:

Penyedia konfigurasi variabel lingkungan
Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file berikutMyXMLFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Elemen berulang yang menggunakan nama elemen yang sama berfungsi jika name atribut digunakan untuk membedakan elemen:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Kode berikut membaca file konfigurasi sebelumnya dan menampilkan kunci dan nilai:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

Atribut dapat digunakan untuk menyediakan nilai:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

File konfigurasi sebelumnya memuat kunci berikut dengan value:

key:attribute
section:key:attribute

Penyedia konfigurasi kunci per file

Untuk mengaktifkan konfigurasi kunci per file, panggil AddKeyPerFile metode ekstensi pada instans ConfigurationBuilder. ke directoryPath file harus merupakan jalur absolut.

Izin kelebihan beban yang menentukan:

Delegasi Action<KeyPerFileConfigurationSource> yang mengonfigurasi sumber.
Apakah direktori bersifat opsional dan jalur ke direktori.

Garis bawah ganda (__) digunakan sebagai pemisah kunci konfigurasi dalam nama file. Misalnya, nama Logging__LogLevel__System file menghasilkan kunci Logging:LogLevel:Systemkonfigurasi .

Panggil ConfigureAppConfiguration saat membangun host untuk menentukan konfigurasi aplikasi:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Penyedia konfigurasi memori

MemoryConfigurationProvider menggunakan koleksi dalam memori sebagai pasangan kunci-nilai konfigurasi.

Kode berikut menambahkan koleksi memori ke sistem konfigurasi:

var builder = WebApplication.CreateBuilder(args);

var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Kode berikut dari unduhan sampel menampilkan pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Dalam kode sebelumnya, config.AddInMemoryCollection(Dict) ditambahkan setelah penyedia konfigurasi default. Untuk contoh pemesanan penyedia konfigurasi, lihat JSPenyedia konfigurasi ON.

Lihat Mengikat array untuk contoh lain menggunakan MemoryConfigurationProvider.

Kestrel konfigurasi titik akhir

Kestrel konfigurasi titik akhir tertentu mengambil alih semua konfigurasi titik akhir lintas server . Konfigurasi titik akhir lintas server meliputi:

UseUrls
--urls pada baris perintah
Variabel lingkunganASPNETCORE_URLS

Pertimbangkan file berikut appsettings.json yang digunakan dalam aplikasi web ASP.NET Core:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Saat markup yang disorot sebelumnya digunakan dalam aplikasi web ASP.NET Core dan aplikasi diluncurkan pada baris perintah dengan konfigurasi titik akhir lintas server berikut:

dotnet run --urls="https://localhost:7777"

Kestrelmengikat ke titik akhir yang dikonfigurasi khusus untuk Kestrel dalam file (https://localhost:9999) dan bukan https://localhost:7777appsettings.json .

Pertimbangkan titik akhir tertentu yang dikonfigurasi Kestrel sebagai variabel lingkungan:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

GetValue

ConfigurationBinder.GetValue mengekstrak satu nilai dari konfigurasi dengan kunci tertentu dan mengonversinya ke jenis yang ditentukan:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Dalam kode sebelumnya, jika NumberKey tidak ditemukan dalam konfigurasi, nilai 99 default digunakan.

GetSection, GetChildren, dan Exists

Untuk contoh berikut, pertimbangkan file berikut MySubsection.json :

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

Kode berikut menambahkan MySubsection.json ke penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MySubsection.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection mengembalikan sub bagian konfigurasi dengan kunci sub-bagian yang ditentukan.

Kode berikut mengembalikan nilai untuk section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Kode berikut mengembalikan nilai untuk section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

GetSection tidak pernah mengembalikan null. Jika bagian yang cocok tidak ditemukan, kosong IConfigurationSection akan dikembalikan.

Saat GetSection mengembalikan bagian yang cocok, Value tidak diisi. A Key dan Path dikembalikan ketika bagian ada.

GetChildren dan Exists

Kode berikut memanggil IConfiguration.GetChildren dan mengembalikan nilai untuk section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = "";
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Panggilan ConfigurationExtensions.Exists kode sebelumnya untuk memverifikasi bagian tersebut ada:

Mengikat array

Pertimbangkan MyArray.json dari unduhan sampel:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

Kode berikut menambahkan MyArray.json ke penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyArray.json",
                        optional: true,
                        reloadOnChange: true); ;
});

builder.Services.AddRazorPages();

var app = builder.Build();

Kode berikut membaca konfigurasi dan menampilkan nilai:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample? _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
       _array = Config.GetSection("array").Get<ArrayExample>();
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }
        string s = String.Empty;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

Kode sebelumnya mengembalikan output berikut:

Index: 0  Value: value00
Index: 1  Value: value10
Index: 2  Value: value20
Index: 3  Value: value40
Index: 4  Value: value50

Dalam output sebelumnya, Indeks 3 memiliki nilai value40, yang "4": "value40", sesuai dengan di MyArray.json. Indeks array terikat bersifat berkelanjutan dan tidak terikat ke indeks kunci konfigurasi. Pengikat konfigurasi tidak mampu mengikat nilai null atau membuat entri null dalam objek terikat.

Penyedia konfigurasi kustom

Aplikasi sampel menunjukkan cara membuat penyedia konfigurasi dasar yang membaca pasangan kunci-nilai konfigurasi dari database menggunakan Kerangka Kerja Entitas (EF).

Penyedia memiliki karakteristik berikut:

Database dalam memori EF digunakan untuk tujuan demonstrasi. Untuk menggunakan database yang memerlukan string koneksi, terapkan sekunder ConfigurationBuilder untuk menyediakan string koneksi dari penyedia konfigurasi lain.
Penyedia membaca tabel database ke dalam konfigurasi saat startup. Penyedia tidak mengkueri database berdasarkan per kunci.
Muat ulang saat perubahan tidak diimplementasikan, jadi memperbarui database setelah aplikasi dimulai tidak berpengaruh pada konfigurasi aplikasi.

EFConfigurationValue Tentukan entitas untuk menyimpan nilai konfigurasi dalam database.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; } = String.Empty;
    public string Value { get; set; } = String.Empty;
}

Tambahkan untuk menyimpan dan mengakses nilai yang EFConfigurationContext dikonfigurasi.

EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions<EFConfigurationContext> options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

Membuat kelas yang mengimplementasikan IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => _optionsAction = optionsAction;

    public IConfigurationProvider Build(IConfigurationBuilder builder) => new EFConfigurationProvider(_optionsAction);
}

EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            if (dbContext == null || dbContext.Values == null)
            {
                throw new Exception("Null DB context");
            }
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues =
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                    { "quote1", "I aim to misbehave." },
                    { "quote2", "I swallowed a bug." },
                    { "quote3", "You can't stop the signal, Mal." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue
            {
                Id = kvp.Key,
                Value = kvp.Value
            })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Metode AddEFConfiguration ekstensi memungkinkan penambahan sumber konfigurasi ke ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
               this IConfigurationBuilder builder,
               Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Kode berikut menunjukkan cara menggunakan kustom EFConfigurationProvider di Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

var app = builder.Build();

app.Run();

Konfigurasi akses dengan Injeksi Dependensi (DI)

Konfigurasi dapat disuntikkan ke layanan menggunakan Dependency Injection (DI) dengan menyelesaikan IConfiguration layanan:

public class Service
{
    private readonly IConfiguration _config;

    public Service(IConfiguration config) =>
        _config = config;

    public void DoSomething()
    {
        var configSettingValue = _config["ConfigSetting"];

        // ...
    }
}

Untuk informasi tentang cara mengakses nilai menggunakan IConfiguration, lihat GetValue dan GetSection, GetChildren, dan Exists di artikel ini.

Mengakses konfigurasi di Razor Pages

Kode berikut menampilkan data konfigurasi di Razor Halaman:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Dalam kode berikut, MyOptions ditambahkan ke kontainer layanan dengan Configure dan terikat ke konfigurasi:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

var app = builder.Build();

Markup berikut menggunakan direktif @injectRazor untuk mengatasi dan menampilkan nilai opsi:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Mengakses konfigurasi dalam file tampilan MVC

Kode berikut menampilkan data konfigurasi dalam tampilan MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Konfigurasi akses di `Program.cs`

Kode berikut mengakses konfigurasi dalam Program.cs file.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

var key1 = app.Configuration.GetValue<int>("KeyOne");
var key2 = app.Configuration.GetValue<bool>("KeyTwo");

app.Logger.LogInformation($"KeyOne = {key1}");
app.Logger.LogInformation($"KeyTwo = {key2}");

app.Run();

Mengonfigurasi opsi dengan delegasi

Opsi yang dikonfigurasi dalam delegasi mengambil alih nilai yang ditetapkan di penyedia konfigurasi.

Dalam kode berikut, IConfigureOptions<TOptions> layanan ditambahkan ke kontainer layanan. Ini menggunakan delegasi untuk mengonfigurasi nilai untuk MyOptions:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "Value configured in delegate";
    myOptions.Option2 = 500;
});

var app = builder.Build();

Kode berikut menampilkan nilai opsi:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Dalam contoh sebelumnya, nilai Option1 dan Option2 ditentukan di lalu ditimpa oleh delegasi yang dikonfigurasi appsettings.json .

Konfigurasi host versus aplikasi

Konfigurasi host default

Untuk detail tentang konfigurasi default saat menggunakan Web Host, lihat versi ASP.NET Core 2.2 dari topik ini.

Konfigurasi host disediakan dari:
- Variabel lingkungan diawali dengan DOTNET_ (misalnya, DOTNET_ENVIRONMENT) menggunakan penyedia konfigurasi Variabel Lingkungan. Awalan (DOTNET_) dilucuti saat pasangan kunci-nilai konfigurasi dimuat.
- Argumen baris perintah menggunakan penyedia konfigurasi baris Perintah.
Konfigurasi default Web Host dibuat (ConfigureWebHostDefaults):
- Kestrel digunakan sebagai server web dan dikonfigurasi menggunakan penyedia konfigurasi aplikasi.
- Tambahkan Middleware Pemfilteran Host.
- Tambahkan Middleware Header yang Diteruskan jika ASPNETCORE_FORWARDEDHEADERS_ENABLED variabel lingkungan diatur ke true.
- Mengaktifkan integrasi IIS.

Konfigurasi lainnya

launch.json/launchSettings.json adalah file konfigurasi alat untuk lingkungan Pengembangan, dijelaskan:
- Di Gunakan beberapa lingkungan di ASP.NET Core.
- Di seluruh kumpulan dokumentasi tempat file digunakan untuk mengonfigurasi aplikasi ASP.NET Core untuk skenario Pengembangan.
web.config adalah file konfigurasi server, yang dijelaskan dalam topik berikut:
- Host ASP.NET Core di Windows dengan IIS
- ASP.NET Core Module (ANCM) untuk IIS

Variabel lingkungan yang diatur dalam launchSettings.json mengambil alih yang ditetapkan di lingkungan sistem.

Untuk informasi selengkapnya tentang memigrasikan konfigurasi aplikasi dari versi ASP.NET yang lebih lama, lihat Migrasi dari ASP.NET ke ASP.NET Core.

Menambahkan konfigurasi dari rakitan eksternal

Sumber Daya Tambahan:

Konfigurasi di ASP.NET Core dilakukan menggunakan satu atau beberapa penyedia konfigurasi. Penyedia konfigurasi membaca data konfigurasi dari pasangan kunci-nilai menggunakan berbagai sumber konfigurasi:

File pengaturan, seperti appsettings.json
Variabel lingkungan
Azure Key Vault
Azure App Configuration
Argumen baris perintah
Penyedia kustom, terinstal atau dibuat
File direktori
Objek .NET dalam memori

Topik ini menyediakan informasi tentang konfigurasi di ASP.NET Core. Untuk informasi tentang menggunakan konfigurasi di aplikasi konsol, lihat Konfigurasi .NET.

Menampilkan atau mengunduh kode sampel (cara mengunduh)

Konfigurasi default

ASP.NET Aplikasi web Core yang dibuat dengan dotnet baru atau Visual Studio menghasilkan kode berikut:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder menyediakan konfigurasi default untuk aplikasi dalam urutan berikut:

ChainedConfigurationProvider : Menambahkan yang sudah ada IConfiguration sebagai sumber. Dalam kasus konfigurasi default, menambahkan konfigurasi host dan mengaturnya sebagai sumber pertama untuk konfigurasi aplikasi .
appsettings.json menggunakan JSpenyedia konfigurasi ON.
appsettings.{Environment}.jsonJSmenggunakan penyedia konfigurasi ON. Misalnya, appsettings.Production.json dan appsettings.Development.json.
Rahasia aplikasi saat aplikasi berjalan di Development lingkungan.
Variabel lingkungan menggunakan penyedia konfigurasi Variabel Lingkungan.
Argumen baris perintah menggunakan penyedia konfigurasi baris Perintah.

Penyedia konfigurasi yang ditambahkan kemudian mengambil alih pengaturan kunci sebelumnya. Misalnya, jika MyKey diatur di lingkungan appsettings.json dan , nilai lingkungan digunakan. Dengan menggunakan penyedia konfigurasi default, penyedia konfigurasi Baris perintah mengambil alih semua penyedia lain.

Untuk informasi selengkapnya tentang CreateDefaultBuilder, lihat Pengaturan penyusun default.

Kode berikut menampilkan penyedia konfigurasi yang diaktifkan dalam urutan ditambahkan:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

`appsettings.json`

Pertimbangkan file berikut appsettings.json :

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey":  "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JsonConfigurationProvider Default memuat konfigurasi dalam urutan berikut:

appsettings.json
appsettings.{Environment}.json : Misalnya, appsettings.Production.json file dan appsettings.Development.json . Versi lingkungan file dimuat berdasarkan IHostingEnvironment.EnvironmentName. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

appsettings.{Environment}.json nilai mengambil alih kunci di appsettings.json. Misalnya, secara default:

Dalam pengembangan, appsettings.Development.json konfigurasi menimpa nilai yang ditemukan di appsettings.json.
Dalam produksi, appsettings.Production.json konfigurasi menimpa nilai yang ditemukan di appsettings.json. Misalnya, saat menyebarkan aplikasi ke Azure.

Jika nilai konfigurasi harus dijamin, lihat GetValue. Contoh sebelumnya hanya membaca string dan tidak mendukung nilai default.

Mengikat data konfigurasi hierarkis menggunakan pola opsi

Cara yang disukai untuk membaca nilai konfigurasi terkait adalah menggunakan pola opsi. Misalnya, untuk membaca nilai konfigurasi berikut:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Buat kelas berikut PositionOptions :

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; }
    public string Name { get; set; }
}

Kelas opsi:

Harus non-abstrak dengan konstruktor tanpa parameter publik.
Semua properti baca-tulis publik jenis terikat.
Bidang tidak terikat. Dalam kode sebelumnya, Position tidak terikat. Properti Position digunakan sehingga string "Position" tidak perlu dikodekan secara permanen di aplikasi saat mengikat kelas ke penyedia konfigurasi.

Kode berikut:

Memanggil ConfigurationBinder.Bind untuk mengikat PositionOptions kelas ke bagian Position .
Position Menampilkan data konfigurasi.

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Dalam kode sebelumnya, secara default, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai dibaca.

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions positionOptions { get; private set; }

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

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Dalam kode sebelumnya, secara default, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai dibaca.

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

Dengan menggunakan kode sebelumnya, kode berikut membaca opsi posisi:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Dalam kode sebelumnya, perubahan pada JSfile konfigurasi ON setelah aplikasi dimulai tidak dibaca. Untuk membaca perubahan setelah aplikasi dimulai, gunakan IOptionsSnapshot.

Lihat JSPenyedia konfigurasi ON dalam dokumen ini untuk informasi tentang menambahkan file konfigurasi ON tambahan JS.

Menggabungkan kumpulan layanan

Pertimbangkan metode berikut ConfigureServices , yang mendaftarkan layanan dan mengonfigurasi opsi:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

    services.AddScoped<IMyDependency, MyDependency>();
    services.AddScoped<IMyDependency2, MyDependency2>();

    services.AddRazorPages();
}

Grup pendaftaran terkait dapat dipindahkan ke metode ekstensi untuk mendaftarkan layanan. Misalnya, layanan konfigurasi ditambahkan ke kelas berikut:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }
    }
}

Layanan yang tersisa terdaftar di kelas serupa. Metode berikut ConfigureServices menggunakan metode ekstensi baru untuk mendaftarkan layanan:

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

Catatan: Setiap services.Add{GROUP_NAME} metode ekstensi menambahkan dan berpotensi mengonfigurasi layanan. Misalnya, AddControllersWithViews menambahkan pengontrol MVC layanan dengan tampilan yang diperlukan, dan AddRazorPages menambahkan layanan yang Razor diperlukan Halaman. Kami menyarankan agar aplikasi mengikuti konvensi penamaan pembuatan metode ekstensi di Microsoft.Extensions.DependencyInjection namespace layanan. Membuat metode ekstensi di Microsoft.Extensions.DependencyInjection namespace:

Merangkum grup pendaftaran layanan.
Menyediakan akses IntelliSense yang nyaman ke layanan.

Rahasia keamanan dan pengguna

Panduan data konfigurasi:

Jangan pernah menyimpan kata sandi atau data sensitif lainnya dalam kode penyedia konfigurasi atau dalam file konfigurasi teks biasa. Alat Secret Manager dapat digunakan untuk menyimpan rahasia dalam pengembangan.
Jangan gunakan rahasia produksi di lingkungan pengembangan atau pengujian.
Tentukan rahasia di luar proyek sehingga tidak dapat diterapkan secara tidak sengaja ke repositori kode sumber.

Untuk informasi selengkapnya tentang menyimpan kata sandi atau data sensitif lainnya:

Gunakan beberapa lingkungan di ASP.NET Core
Penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core: Mencakup saran tentang menggunakan variabel lingkungan untuk menyimpan data sensitif. Alat Secret Manager menggunakan penyedia konfigurasi File untuk menyimpan rahasia pengguna dalam JSfile ON pada sistem lokal.

Azure Key Vault menyimpan rahasia aplikasi dengan aman untuk aplikasi ASP.NET Core. Untuk informasi selengkapnya, lihat Penyedia konfigurasi Azure Key Vault di ASP.NET Core.

Variabel lingkungan

Menggunakan konfigurasi default , EnvironmentVariablesConfigurationProvider memuat konfigurasi dari pasangan nilai kunci variabel lingkungan setelah membaca appsettings.json, appsettings.{Environment}.json, dan rahasia pengguna. Oleh karena itu, nilai kunci yang dibaca dari lingkungan mengambil alih nilai yang dibaca dari appsettings.json, appsettings.{Environment}.json, dan rahasia pengguna.

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. __, garis bawah ganda, adalah:

Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __ adalah.
Digantikan secara otomatis oleh :

Perintah berikut set :

Atur kunci lingkungan dan nilai contoh sebelumnya di Windows.
Uji pengaturan saat menggunakan unduhan sampel. Perintah dotnet run harus dijalankan di direktori proyek.

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Pengaturan lingkungan sebelumnya:

Hanya diatur dalam proses yang diluncurkan dari jendela perintah tempat mereka diatur.
Tidak akan dibaca oleh browser yang diluncurkan dengan Visual Studio.

Perintah setx berikut dapat digunakan untuk mengatur kunci dan nilai lingkungan pada Windows. Tidak seperti set, setx pengaturan tetap ada. /M mengatur variabel di lingkungan sistem. Jika sakelar /M tidak digunakan, variabel lingkungan pengguna diatur.

setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Untuk menguji bahwa perintah sebelumnya mengambil appsettings.json alih dan appsettings.{Environment}.json:

Dengan Visual Studio: Keluar dan mulai ulang Visual Studio.
Dengan CLI: Mulai jendela perintah baru dan masukkan dotnet run.

Panggil AddEnvironmentVariables dengan string untuk menentukan awalan untuk variabel lingkungan:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Dalam kode sebelumnya:

config.AddEnvironmentVariables(prefix: "MyCustomPrefix_") ditambahkan setelah penyedia konfigurasi default. Untuk contoh pemesanan penyedia konfigurasi, lihat JSPenyedia konfigurasi ON.
Variabel lingkungan diatur dengan awalan MyCustomPrefix_ mengambil alih penyedia konfigurasi default. Ini termasuk variabel lingkungan tanpa awalan.

Awalan dilucuti saat pasangan kunci-nilai konfigurasi dibaca.

Perintah berikut menguji awalan kustom:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Pada Azure App Service, pilih Pengaturan aplikasi baru di halaman Konfigurasi Pengaturan>. Azure App Service pengaturan aplikasi adalah:

Dienkripsi saat tidak aktif dan ditransmisikan melalui saluran terenkripsi.
Diekspos sebagai variabel lingkungan.

Untuk informasi selengkapnya, lihat Aplikasi Azure: Mengambil alih konfigurasi aplikasi menggunakan Portal Microsoft Azure.

Lihat Awalan string koneksi untuk informasi tentang string koneksi database Azure.

Penamaan variabel lingkungan

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

variabel lingkungan

setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information

Variabel lingkungan diatur dalam launchSettings.json yang dihasilkan

"applicationUrl": "https://localhost:5001;http://localhost:5000"

Mengonfigurasi applicationUrl set ASPNETCORE_URLS variabel lingkungan dan mengambil alih nilai yang ditetapkan di lingkungan.

Variabel lingkungan escape di Linux

Di Linux, nilai variabel lingkungan URL harus diloloskan sehingga systemd dapat mengurainya. Gunakan alat systemd-escape linux yang menghasilkan http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Menampilkan variabel lingkungan

Kode berikut menampilkan variabel lingkungan dan nilai pada startup aplikasi, yang dapat membantu saat men-debug pengaturan lingkungan:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var config = host.Services.GetRequiredService<IConfiguration>();

    foreach (var c in config.AsEnumerable())
    {
        Console.WriteLine(c.Key + " = " + c.Value);
    }
    host.Run();
}

Baris perintah

Menggunakan konfigurasi default , CommandLineConfigurationProvider memuat konfigurasi dari pasangan kunci-nilai argumen baris perintah setelah sumber konfigurasi berikut:

appsettings.json dan appsettings.{Environment}.json file.
Rahasia aplikasi di lingkungan Pengembangan.
Variabel lingkungan.

Secara default, nilai konfigurasi yang diatur pada baris perintah mengambil alih nilai konfigurasi yang ditetapkan dengan semua penyedia konfigurasi lainnya.

Argumen baris perintah

Perintah berikut mengatur kunci dan nilai menggunakan =:

dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick

Perintah berikut mengatur kunci dan nilai menggunakan /:

dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick

Perintah berikut mengatur kunci dan nilai menggunakan --:

dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick

Nilai kunci:

Harus mengikuti =, atau kunci harus memiliki awalan -- atau / ketika nilai mengikuti spasi.
Tidak diperlukan jika = digunakan. Contohnya:MySetting=

Dalam perintah yang sama, jangan mencampur pasangan kunci-nilai argumen baris perintah yang menggunakan = dengan pasangan kunci-nilai yang menggunakan spasi.

Beralih pemetaan

Pemetaan pengalihan memungkinkan logika penggantian nama kunci . Berikan kamus penggantian sakelar ke AddCommandLine metode .

Saat kamus pemetaan sakelar digunakan, kamus diperiksa untuk kunci yang cocok dengan kunci yang disediakan oleh argumen baris perintah. Jika kunci baris perintah ditemukan dalam kamus, nilai kamus diteruskan kembali untuk mengatur pasangan kunci-nilai ke dalam konfigurasi aplikasi. Pemetaan sakelar diperlukan untuk setiap kunci baris perintah yang diawali dengan tanda hubung tunggal (-).

Beralih aturan kunci kamus pemetaan:

Sakelar harus dimulai dengan - atau --.
Kamus pemetaan sakelar tidak boleh berisi kunci duplikat.

Untuk menggunakan kamus pemetaan sakelar, teruskan ke panggilan ke AddCommandLine:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Kode berikut menunjukkan nilai kunci untuk kunci yang diganti:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

Perintah berikut berfungsi untuk menguji penggantian kunci:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Untuk aplikasi yang menggunakan pemetaan pengalihan, panggilan ke CreateDefaultBuilder tidak boleh meneruskan argumen. Panggilan CreateDefaultBuilder metode AddCommandLine tidak menyertakan sakelar yang dipetakan, dan tidak ada cara untuk meneruskan kamus pemetaan sakelar ke CreateDefaultBuilder. Solusinya bukan untuk meneruskan argumen ke CreateDefaultBuilder tetapi sebaliknya untuk memungkinkan ConfigurationBuilder metode metode AddCommandLine memproses argumen dan kamus pemetaan sakelar.

Mengatur argumen lingkungan dan baris perintah dengan Visual Studio

Gambar berikut menunjukkan pengaturan lingkungan dan argumen baris perintah dengan Visual Studio:

Debug tab of VS

Di Visual Studio 2019 versi 16.10 pratinjau 4 dan yang lebih baru, mengatur argumen lingkungan dan baris perintah dilakukan dari antarmuka pengguna profil peluncuran:

luncurkan antarmuka pengguna profil

Data konfigurasi hierarkis

API Konfigurasi membaca data konfigurasi hierarkis dengan meratakan data hierarkis dengan penggunaan pemisah di kunci konfigurasi.

Unduhan sampel berisi file berikutappsettings.json:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey":  "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Cara yang disukai untuk membaca data konfigurasi hierarkis adalah menggunakan pola opsi. Untuk informasi selengkapnya, lihat Mengikat data konfigurasi hierarkis dalam dokumen ini.

GetSection metode dan GetChildren tersedia untuk mengisolasi bagian dan turunan dari bagian dalam data konfigurasi. Metode ini dijelaskan nanti di GetSection, GetChildren, dan Exists.

Kunci dan nilai konfigurasi

Kunci konfigurasi:

Tidak peka huruf besar/kecil. Misalnya, ConnectionString dan connectionstring dianggap sebagai kunci yang setara.
Jika kunci dan nilai diatur di lebih dari satu penyedia konfigurasi, nilai dari penyedia terakhir yang ditambahkan akan digunakan. Untuk informasi selengkapnya, lihat Konfigurasi default.
Kunci hierarkis
- Dalam API Konfigurasi, pemisah titik dua (:) berfungsi di semua platform.
- Dalam variabel lingkungan, pemisah titik dua mungkin tidak berfungsi di semua platform. Garis bawah ganda, __, didukung oleh semua platform dan secara otomatis dikonversi menjadi titik dua :.
- Di Azure Key Vault, kunci hierarkis digunakan -- sebagai pemisah. Penyedia konfigurasi Azure Key Vault secara otomatis mengganti -- dengan : saat rahasia dimuat ke dalam konfigurasi aplikasi.
ConfigurationBinder mendukung pengikatan array ke objek menggunakan indeks array dalam kunci konfigurasi. Pengikatan array dijelaskan di bagian Ikat array ke kelas .

Nilai konfigurasi:

Adalah string.
Nilai null tidak dapat disimpan dalam konfigurasi atau terikat ke objek.

Penyedia konfigurasi

Tabel berikut menunjukkan penyedia konfigurasi yang tersedia untuk ASP.NET aplikasi Core.

Penyedia	Menyediakan konfigurasi dari
Penyedia konfigurasi Azure Key Vault	Azure Key Vault
Penyedia konfigurasi Aplikasi Azure	Azure App Configuration
Penyedia konfigurasi baris perintah	Parameter baris perintah
Penyedia konfigurasi kustom	Sumber kustom
Penyedia konfigurasi Variabel Lingkungan	Variabel lingkungan
Penyedia konfigurasi file	File INI, JSON, dan XML
Penyedia konfigurasi kunci per file	File direktori
Penyedia konfigurasi memori	Koleksi dalam memori
Rahasia pengguna	File di direktori profil pengguna

Urutan umum penyedia konfigurasi adalah:

appsettings.json
appsettings.{Environment}.json
Rahasia pengguna
Variabel lingkungan menggunakan penyedia konfigurasi Variabel Lingkungan.
Argumen baris perintah menggunakan penyedia konfigurasi Baris perintah.

Urutan penyedia sebelumnya digunakan dalam konfigurasi default.

Awalan string koneksi

Awalan string koneksi	Penyedia
`CUSTOMCONNSTR_`	Penyedia kustom
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Azure SQL Database
`SQLCONNSTR_`	SQL Server

Saat variabel lingkungan ditemukan dan dimuat ke dalam konfigurasi dengan salah satu dari empat awalan yang ditunjukkan dalam tabel:

Kunci konfigurasi dibuat dengan menghapus awalan variabel lingkungan dan menambahkan bagian kunci konfigurasi (ConnectionStrings).
Pasangan kunci-nilai konfigurasi baru dibuat yang mewakili penyedia koneksi database (kecuali CUSTOMCONNSTR_, yang tidak memiliki penyedia yang dinyatakan).

Kunci variabel lingkungan	Kunci konfigurasi yang dikonversi	Entri konfigurasi penyedia
`CUSTOMCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Entri konfigurasi tidak dibuat.
`MYSQLCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `MySql.Data.MySqlClient`
`SQLAZURECONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `System.Data.SqlClient`
`SQLCONNSTR_{KEY}`	`ConnectionStrings:{KEY}`	Kunci: `ConnectionStrings:{KEY}_ProviderName`: Nilai: `System.Data.SqlClient`

Penyedia konfigurasi file

FileConfigurationProvider adalah kelas dasar untuk memuat konfigurasi dari sistem file. Penyedia konfigurasi berikut berasal dari FileConfigurationProvider:

Penyedia konfigurasi INI
JSPenyedia konfigurasi ON
Penyedia konfigurasi XML

Penyedia konfigurasi INI

Memuat IniConfigurationProvider konfigurasi dari pasangan kunci-nilai file INI saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Dalam kode sebelumnya, pengaturan dalam MyIniConfig.ini file dan MyIniConfig.{Environment}.ini ditimpa oleh pengaturan di:

Penyedia konfigurasi variabel lingkungan
Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file berikutMyIniConfig.ini:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JSPenyedia konfigurasi ON

Memuat JsonConfigurationProvider konfigurasi dari JSpasangan kunci-nilai file ON.

Kelebihan beban dapat menentukan:

Apakah file bersifat opsional.
Apakah konfigurasi dimuat ulang jika file berubah.

Pertimbangkan kode berikut:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Kode sebelumnya:

JSMengonfigurasi penyedia konfigurasi ON untuk memuat MyConfig.json file dengan opsi berikut:
- optional: true: File bersifat opsional.
- reloadOnChange: true : File dimuat ulang saat perubahan disimpan.
Membaca penyedia konfigurasi default sebelum MyConfig.json file. Pengaturan dalam MyConfig.json pengaturan penimpaan file di penyedia konfigurasi default, termasuk penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi baris Perintah.

Anda biasanya tidak ingin nilai penimpaan file ON kustom JSdiatur dalam penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi Baris perintah.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                                     optional: true, reloadOnChange: true);

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Dalam kode sebelumnya, pengaturan di MyConfig.json dan MyConfig.Environment. file json :

Mengesampingkan appsettings.json pengaturan dalam file dan appsettings.{Environment}.json .
Ditimpa oleh pengaturan di penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi baris Perintah.

Unduhan sampel berisi file berikutMyConfig.json:

{
  "Position": {
    "Title": "My Config title",
    "Name": "My Config Smith"
  },
  "MyKey":  "MyConfig.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Penyedia konfigurasi XML

Memuat XmlConfigurationProvider konfigurasi dari pasangan kunci-nilai file XML saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan beberapa penyedia konfigurasi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Dalam kode sebelumnya, pengaturan dalam MyXMLFile.xml file dan MyXMLFile.{Environment}.xml ditimpa oleh pengaturan di:

Penyedia konfigurasi variabel lingkungan
Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file berikutMyXMLFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Kode berikut dari unduhan sampel menampilkan beberapa pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Elemen berulang yang menggunakan nama elemen yang sama berfungsi jika name atribut digunakan untuk membedakan elemen:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Kode berikut membaca file konfigurasi sebelumnya dan menampilkan kunci dan nilai:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

Atribut dapat digunakan untuk menyediakan nilai:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

File konfigurasi sebelumnya memuat kunci berikut dengan value:

key:attribute
section:key:attribute

Penyedia konfigurasi kunci per file

Untuk mengaktifkan konfigurasi kunci per file, panggil AddKeyPerFile metode ekstensi pada instans ConfigurationBuilder. ke directoryPath file harus merupakan jalur absolut.

Izin kelebihan beban yang menentukan:

Delegasi Action<KeyPerFileConfigurationSource> yang mengonfigurasi sumber.
Apakah direktori bersifat opsional dan jalur ke direktori.

Garis bawah ganda (__) digunakan sebagai pemisah kunci konfigurasi dalam nama file. Misalnya, nama Logging__LogLevel__System file menghasilkan kunci Logging:LogLevel:Systemkonfigurasi .

Panggil ConfigureAppConfiguration saat membangun host untuk menentukan konfigurasi aplikasi:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Penyedia konfigurasi memori

MemoryConfigurationProvider menggunakan koleksi dalam memori sebagai pasangan kunci-nilai konfigurasi.

Kode berikut menambahkan koleksi memori ke sistem konfigurasi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Kode berikut dari unduhan sampel menampilkan pengaturan konfigurasi sebelumnya:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Dalam kode sebelumnya, config.AddInMemoryCollection(Dict) ditambahkan setelah penyedia konfigurasi default. Untuk contoh pemesanan penyedia konfigurasi, lihat JSPenyedia konfigurasi ON.

Lihat Mengikat array untuk contoh lain menggunakan MemoryConfigurationProvider.

Kestrel konfigurasi titik akhir

Kestrel konfigurasi titik akhir tertentu mengambil alih semua konfigurasi titik akhir lintas server . Konfigurasi titik akhir lintas server meliputi:

UseUrls
--urls pada baris perintah
Variabel lingkunganASPNETCORE_URLS

Pertimbangkan file berikut appsettings.json yang digunakan dalam aplikasi web ASP.NET Core:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Saat markup yang disorot sebelumnya digunakan dalam aplikasi web ASP.NET Core dan aplikasi diluncurkan pada baris perintah dengan konfigurasi titik akhir lintas server berikut:

dotnet run --urls="https://localhost:7777"

Kestrelmengikat ke titik akhir yang dikonfigurasi khusus untuk Kestrel dalam file (https://localhost:9999) dan bukan https://localhost:7777appsettings.json .

Pertimbangkan titik akhir tertentu yang dikonfigurasi Kestrel sebagai variabel lingkungan:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

GetValue

ConfigurationBinder.GetValue mengekstrak satu nilai dari konfigurasi dengan kunci tertentu dan mengonversinya ke jenis yang ditentukan. Metode ini adalah metode ekstensi untuk IConfiguration:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Dalam kode sebelumnya, jika NumberKey tidak ditemukan dalam konfigurasi, nilai 99 default digunakan.

GetSection, GetChildren, dan Exists

Untuk contoh berikut, pertimbangkan file berikut MySubsection.json :

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

Kode berikut menambahkan MySubsection.json ke penyedia konfigurasi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MySubsection.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

GetSection

IConfiguration.GetSection mengembalikan sub bagian konfigurasi dengan kunci sub-bagian yang ditentukan.

Kode berikut mengembalikan nilai untuk section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Kode berikut mengembalikan nilai untuk section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

GetSection tidak pernah mengembalikan null. Jika bagian yang cocok tidak ditemukan, kosong IConfigurationSection akan dikembalikan.

Saat GetSection mengembalikan bagian yang cocok, Value tidak diisi. A Key dan Path dikembalikan ketika bagian ada.

GetChildren dan Exists

Kode berikut memanggil IConfiguration.GetChildren dan mengembalikan nilai untuk section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = null;
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new System.Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Panggilan ConfigurationExtensions.Exists kode sebelumnya untuk memverifikasi bagian tersebut ada:

Mengikat array

Pertimbangkan MyArray.json dari unduhan sampel:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

Kode berikut menambahkan MyArray.json ke penyedia konfigurasi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyArray.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Kode berikut membaca konfigurasi dan menampilkan nilai:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Kode sebelumnya mengembalikan output berikut:

Index: 0  Value: value00
Index: 1  Value: value10
Index: 2  Value: value20
Index: 3  Value: value40
Index: 4  Value: value50

Kode berikut memuat array:entries konfigurasi dengan AddInMemoryCollection metode ekstensi:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Kode berikut membaca konfigurasi di arrayDictDictionary dan menampilkan nilai:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Kode sebelumnya mengembalikan output berikut:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value4
Index: 4  Value: value5

Indeks #3 dalam objek terikat menyimpan data konfigurasi untuk array:4 kunci konfigurasi dan nilainya .value4 Saat data konfigurasi yang berisi array terikat, indeks array dalam kunci konfigurasi digunakan untuk melakukan iterasi data konfigurasi saat membuat objek. Nilai null tidak dapat dipertahankan dalam data konfigurasi, dan entri bernilai null tidak dibuat dalam objek terikat saat array dalam kunci konfigurasi melewati satu atau beberapa indeks.

Item konfigurasi yang hilang untuk indeks #3 dapat disediakan sebelum mengikat ke ArrayExample instans oleh penyedia konfigurasi apa pun yang membaca indeks #3 pasangan kunci/nilai. Pertimbangkan file berikut Value3.json dari unduhan sampel:

{
  "array:entries:3": "value3"
}

Kode berikut mencakup konfigurasi untuk Value3.json dan arrayDictDictionary:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile("Value3.json",
                                    optional: false, reloadOnChange: false);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Kode berikut membaca konfigurasi sebelumnya dan menampilkan nilai:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

Kode sebelumnya mengembalikan output berikut:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value3
Index: 4  Value: value4
Index: 5  Value: value5

Penyedia konfigurasi kustom tidak diperlukan untuk menerapkan pengikatan array.

Penyedia konfigurasi kustom

Aplikasi sampel menunjukkan cara membuat penyedia konfigurasi dasar yang membaca pasangan kunci-nilai konfigurasi dari database menggunakan Kerangka Kerja Entitas (EF).

Penyedia memiliki karakteristik berikut:

Database dalam memori EF digunakan untuk tujuan demonstrasi. Untuk menggunakan database yang memerlukan string koneksi, terapkan sekunder ConfigurationBuilder untuk menyediakan string koneksi dari penyedia konfigurasi lain.
Penyedia membaca tabel database ke dalam konfigurasi saat startup. Penyedia tidak mengkueri database berdasarkan per kunci.
Muat ulang saat perubahan tidak diimplementasikan, jadi memperbarui database setelah aplikasi dimulai tidak berpengaruh pada konfigurasi aplikasi.

EFConfigurationValue Tentukan entitas untuk menyimpan nilai konfigurasi dalam database.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Tambahkan untuk menyimpan dan mengakses nilai yang EFConfigurationContext dikonfigurasi.

EFConfigurationProvider/EFConfigurationContext.cs:

// using Microsoft.EntityFrameworkCore;

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Membuat kelas yang mengimplementasikan IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
    {
        _optionsAction = optionsAction;
    }

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

EFConfigurationProvider/EFConfigurationProvider.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues = 
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue 
                {
                    Id = kvp.Key,
                    Value = kvp.Value
                })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Metode AddEFConfiguration ekstensi memungkinkan penambahan sumber konfigurasi ke ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Kode berikut menunjukkan cara menggunakan kustom EFConfigurationProvider di Program.cs:

// using Microsoft.EntityFrameworkCore;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddEFConfiguration(
                options => options.UseInMemoryDatabase("InMemoryDb"));
        })

Konfigurasi akses di Startup

Kode berikut menampilkan data konfigurasi dalam Startup metode:

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

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Untuk contoh mengakses konfigurasi menggunakan metode kenyamanan startup, lihat Startup aplikasi: Metode kenyamanan.

Mengakses konfigurasi di Razor Pages

Kode berikut menampilkan data konfigurasi di Razor Halaman:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Dalam kode berikut, MyOptions ditambahkan ke kontainer layanan dengan Configure dan terikat ke konfigurasi:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));

    services.AddRazorPages();
}

Markup berikut menggunakan direktif @injectRazor untuk mengatasi dan menampilkan nilai opsi:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Mengakses konfigurasi dalam file tampilan MVC

Kode berikut menampilkan data konfigurasi dalam tampilan MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Mengonfigurasi opsi dengan delegasi

Opsi yang dikonfigurasi dalam delegasi mengambil alih nilai yang ditetapkan di penyedia konfigurasi.

Mengonfigurasi opsi dengan delegasi ditunjukkan sebagai Contoh 2 di aplikasi sampel.

Dalam kode berikut, IConfigureOptions<TOptions> layanan ditambahkan ke kontainer layanan. Ini menggunakan delegasi untuk mengonfigurasi nilai untuk MyOptions:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "Value configured in delegate";
        myOptions.Option2 = 500;
    });

    services.AddRazorPages();
}

Kode berikut menampilkan nilai opsi:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Dalam contoh sebelumnya, nilai Option1 dan Option2 ditentukan di lalu ditimpa oleh delegasi yang dikonfigurasi appsettings.json .

Konfigurasi host versus aplikasi

Konfigurasi host default

Untuk detail tentang konfigurasi default saat menggunakan Web Host, lihat versi ASP.NET Core 2.2 dari topik ini.

Konfigurasi host disediakan dari:
- Variabel lingkungan diawali dengan DOTNET_ (misalnya, DOTNET_ENVIRONMENT) menggunakan penyedia konfigurasi Variabel Lingkungan. Awalan (DOTNET_) dilucuti saat pasangan kunci-nilai konfigurasi dimuat.
- Argumen baris perintah menggunakan penyedia konfigurasi baris Perintah.
Konfigurasi default Web Host dibuat (ConfigureWebHostDefaults):
- Kestrel digunakan sebagai server web dan dikonfigurasi menggunakan penyedia konfigurasi aplikasi.
- Tambahkan Middleware Pemfilteran Host.
- Tambahkan Middleware Header yang Diteruskan jika ASPNETCORE_FORWARDEDHEADERS_ENABLED variabel lingkungan diatur ke true.
- Mengaktifkan integrasi IIS.

Konfigurasi lainnya

launch.json/launchSettings.json adalah file konfigurasi alat untuk lingkungan Pengembangan, dijelaskan:
- Di Gunakan beberapa lingkungan di ASP.NET Core.
- Di seluruh kumpulan dokumentasi tempat file digunakan untuk mengonfigurasi aplikasi ASP.NET Core untuk skenario Pengembangan.
web.config adalah file konfigurasi server, yang dijelaskan dalam topik berikut:
- Host ASP.NET Core di Windows dengan IIS
- ASP.NET Core Module (ANCM) untuk IIS

Variabel lingkungan yang diatur dalam launchSettings.json mengambil alih yang ditetapkan di lingkungan sistem.

Untuk informasi selengkapnya tentang memigrasikan konfigurasi aplikasi dari versi ASP.NET yang lebih lama, lihat Migrasi dari ASP.NET ke ASP.NET Core.

Konfigurasi di ASP.NET Core

Konfigurasi Aplikasi dan Host

Sumber konfigurasi aplikasi default

Sumber konfigurasi host default

Variabel host

Penyedia konfigurasi aplikasi

appsettings.json

Mengikat data konfigurasi hierarkis menggunakan pola opsi

Menggabungkan kumpulan layanan

Rahasia keamanan dan pengguna

Variabel lingkungan yang tidak diawali

Penamaan variabel lingkungan

Variabel lingkungan diatur dalam launchSettings.json yang dihasilkan

Variabel lingkungan escape di Linux

Menampilkan variabel lingkungan

Baris perintah

Argumen baris perintah

Beralih pemetaan

Mengatur argumen lingkungan dan baris perintah dengan Visual Studio

Data konfigurasi hierarkis

Kunci dan nilai konfigurasi

Penyedia konfigurasi

Awalan string koneksi

Penyedia konfigurasi file

Penyedia konfigurasi INI

JSPenyedia konfigurasi ON

Penyedia konfigurasi XML

Penyedia konfigurasi kunci per file

Penyedia konfigurasi memori

Kestrel konfigurasi titik akhir

GetValue

GetSection, GetChildren, dan Exists

GetSection

GetChildren dan Exists

Mengikat array

Penyedia konfigurasi kustom

Konfigurasi akses dengan Injeksi Dependensi (DI)

Mengakses konfigurasi di Razor Pages

Konfigurasi akses dalam file tampilan MVC

Konfigurasi akses di Program.cs

Mengonfigurasi opsi dengan delegasi

Host versus konfigurasi aplikasi

Konfigurasi host default

Konfigurasi lainnya

Menambahkan konfigurasi dari rakitan eksternal

Sumber Daya Tambahan:

Konfigurasi Aplikasi dan Host

Sumber konfigurasi aplikasi default

Sumber konfigurasi host default

Variabel host

Penyedia konfigurasi aplikasi

appsettings.json

Mengikat data konfigurasi hierarkis menggunakan pola opsi

Menggabungkan kumpulan layanan

Rahasia keamanan dan pengguna

Variabel lingkungan yang tidak diawali

Penamaan variabel lingkungan

Variabel lingkungan diatur dalam launchSettings.json yang dihasilkan

Variabel lingkungan escape di Linux

Menampilkan variabel lingkungan

Baris perintah

Argumen baris perintah

Beralih pemetaan

Mengatur argumen lingkungan dan baris perintah dengan Visual Studio

Data konfigurasi hierarkis

Kunci dan nilai konfigurasi

Penyedia konfigurasi

Awalan string koneksi

Penyedia konfigurasi file

Penyedia konfigurasi INI

JSPenyedia konfigurasi ON

Penyedia konfigurasi XML

Penyedia konfigurasi kunci per file

Penyedia konfigurasi memori

Kestrel konfigurasi titik akhir

GetValue

GetSection, GetChildren, dan Exists

GetSection

GetChildren dan Exists

Mengikat array

`appsettings.json`

Konfigurasi akses di `Program.cs`

`appsettings.json`

Konfigurasi akses di `Program.cs`

`appsettings.json`