Konfigurasi di ASP.NET Core

Oleh Rick Anderson dan Kirk Larkin

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:

• Pengaturan file, seperti appsettings.json
• Variabel lingkungan
• Azure Key Vault
• Azure App Configuration
• Argumen baris perintah
• Penyedia kustom, diinstal 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.

Untuk Blazor panduan konfigurasi, yang menambahkan atau menggantikan panduan dalam simpul ini, lihat konfigurasi ASP.NET CoreBlazor.

Konfigurasi Aplikasi dan Host

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

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

Sumber konfigurasi aplikasi default

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

var builder = WebApplication.CreateBuilder(args);

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

1. Argumen baris perintah menggunakan Penyedia konfigurasi baris perintah.
2. Variabel lingkungan yang tidak berawalan menggunakan Penyedia konfigurasi variabel lingkungan yang tidak berawalan.
3. Rahasia pengguna saat aplikasi berjalan di lingkungan Development.
4. appsettings.{Environment}.jsonmenggunakan penyedia konfigurasi JSON. Misalnya, appsettings.Production.json dan appsettings.Development.json.
5. appsettings.json menggunakan penyedia konfigurasi JSON.
6. Cadangan ke konfigurasi host dijelaskan di bagian berikutnya.

Sumber konfigurasi host default

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

1. Argumen baris perintah menggunakan Penyedia konfigurasi baris Perintah
2. Variabel lingkungan yang diawali DOTNET_ menggunakan Penyedia konfigurasi variabel lingkungan.
3. Variabel lingkungan yang diawali ASPNETCORE_ menggunakan Penyedia konfigurasi variabel lingkungan.

Untuk Host Generik .NET dan Host Web, sumber konfigurasi host default dari prioritas tertinggi hingga terendah adalah:

1. Variabel lingkungan yang diawali ASPNETCORE_ menggunakan Penyedia konfigurasi variabel lingkungan.
2. Argumen baris perintah menggunakan Penyedia konfigurasi baris Perintah
3. Variabel lingkungan yang diawali DOTNET_ menggunakan Penyedia konfigurasi variabel lingkungan.

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

Variabel host

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

• Nama aplikasi
• Nama lingkungan, misalnya Development, Production, dan 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 dalam panggilan balik IHostBuilder.ConfigureAppConfiguration.

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 pengaturan host lainnya yang tidak ada dalam daftar sebelumnya, URLS dibaca kemudian dari konfigurasi aplikasi. Konfigurasi host adalah cadangan untuk konfigurasi aplikasi, sehingga konfigurasi host dapat digunakan untuk mengatur URLS, tetapi akan diambil alih 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 menggunakan variabel lingkungan atau baris perintah

Bagian selanjutnya dalam artikel ini mengacu pada konfigurasi aplikasi.

Penyedia konfigurasi aplikasi

Kode berikut menampilkan penyedia konfigurasi yang diaktifkan sesuai urutan penambahannya:

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 sumber konfigurasi default dari prioritas yang tertinggi hingga terendah sebelumnya menunjukkan penyedia dalam urutan yang berlawanan saat ditambahkan ke aplikasi yang dihasilkan templat. Misalnya, penyedia konfigurasi JSON ditambahkan sebelum penyedia konfigurasi Baris perintah.

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

Untuk informasi selengkapnya tentang CreateBuilder, lihat Pengaturan penyusun default.

appsettings.json

Pertimbangkan file appsettings.json berikut:

{
  "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:

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

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

• Saat pengembangan, konfigurasi appsettings.Development.json menimpa nilai yang ditemukan di appsettings.json.
• Saat produksi, konfigurasi appsettings.Production.json 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, file appsettings.json dan appsettings.{Environment}.json diaktifkan dengan reloadOnChange: true. Perubahan yang dilakukan pada appsettings.json file dan appsettings.{Environment}.json setelah aplikasi dimulai dibaca oleh penyedia konfigurasi JSON.

Komentar di appsettings.json

Komentar di appsettings.json dan appsettings.{Environment}.json file didukung menggunakan komentar gaya JavaScript atau C#.

Mengikat data konfigurasi hierarkis menggunakan pola opsi

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

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

Buat kelas PositionOptions berikut:

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 nonabstrak dengan konstruktor tanpa parameter publik.
• Semua properti baca-tulis publik dari jenis ini 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 kelas PositionOptions ke bagian Position.
• Menampilkan data konfigurasi Position.

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 file konfigurasi JSON setelah aplikasi dimulai dibaca.

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

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 file konfigurasi JSON setelah aplikasi dimulai dibaca.

Pendekatan alternatif saat menggunakan pola opsi adalah untuk 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 file konfigurasi JSON setelah aplikasi dimulai tidak dibaca. Untuk membaca perubahan setelah aplikasi dimulai, gunakan IOptionsSnapshot.

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

Lihat Penyedia konfigurasi JSON dalam dokumen ini untuk informasi tentang menambahkan file konfigurasi JSON tambahan.

Menggabungkan kumpulan layanan

Pertimbangkan hal berikut yang mendaftarkan layanan dan mengonfigurasikan 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;
        }

        public static IServiceCollection AddMyDependencyGroup(
             this IServiceCollection services)
        {
            services.AddScoped<IMyDependency, MyDependency>();
            services.AddScoped<IMyDependency2, MyDependency2>();

            return services;
        }
    }
}

Layanan yang tersisa akan didaftarkan di kelas yang sama. 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 metode ekstensi services.Add{GROUP_NAME} menambahkan dan berpotensi mengonfigurasikan layanan. Misalnya, AddControllersWithViews menambahkan pengontrol MVC pada layanan dengan tampilan yang diperlukan, dan AddRazorPages menambahkan Razor Pages yang diperlukan pada layanan.

Keamanan dan rahasia 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.
• Aplikasi produksi harus menggunakan alur autentikasi paling aman yang tersedia. Untuk informasi selengkapnya, lihat Mengamankan alur autentikasi.

Secara default, sumber konfigurasi rahasia pengguna didaftarkan setelah sumber konfigurasi JSON. 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
• Brankas penyimpanan rahasia aplikasi 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 file JSON 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 berawalan

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

• Daftar sumber konfigurasi default prioritas tertinggi hingga terendah termasuk variabel lingkungan yang tidak berawalan, serta diawali ASPNETCORE_ dan DOTNETCORE_.
• Variabel lingkunganDOTNET_ yang digunakan di luar Microsoft.Extensions.Hosting.

Menggunakan konfigurasi default, EnvironmentVariablesConfigurationProvider memuat konfigurasi dari pasangan kunci-nilai 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 hierarkis variabel lingkungan di semua platform. Misalnya, pemisah : tidak didukung oleh Bash. Garis bawah ganda, __, adalah:

• Didukung oleh semua platform.
• Secara otomatis digantikan oleh titik dua, :.

berikut memberi perintah:

• Mengatur kunci dan nilai lingkungan contoh sebelumnya pada Windows.
• Menguji 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, pengaturan setx tetap ada. /M mengatur variabel di lingkungan sistem. Jika switch /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 hidupkan 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 Penyedia konfigurasi JSON.
• Variabel lingkungan yang diatur dengan awalan MyCustomPrefix_ mengambil alih penyedia konfigurasi default. Ini termasuk variabel lingkungan tanpa awalan.

Awalan dihapus 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_. Awalan DOTNET_ 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 Pengaturan > Konfigurasi. Pengaturan aplikasi Azure App Service:

• Dienkripsi di dan ditransmisikan rest melalui saluran terenkripsi.
• Diekspos sebagai variabel lingkungan.

Untuk informasi lebih lanjut, lihat Aplikasi Azure: Menimpa konfigurasi aplikasi menggunakan Portal Azure.

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

Penamaan variabel lingkungan

Nama variabel lingkungan mencerminkan struktur file appsettings.json. 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 appsettings.json berikut 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 diatur di lingkungan sistem. Misalnya, templat web ASP.NET Core menghasilkan file launchSettings.json yang mengatur konfigurasi titik akhir ke:

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

Mengonfigurasikan applicationUrl mengatur variabel lingkungan ASPNETCORE_URLS dan mengambil alih nilai yang diatur di lingkungan.

Keluar variabel lingkungan di Linux

Di Linux, nilai variabel lingkungan URL harus dikeluarkan agar systemd dapat mengurainya. Gunakan alat linux systemd-escape 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 mendebug 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 mengikuti sumber konfigurasi berikut:

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

Secara default, nilai konfigurasi yang diatur pada baris perintah mengambil alih nilai konfigurasi yang diatur 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 / jika nilai setelah 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.

Pemetaan switch

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

Saat kamus pemetaan switch digunakan, kamus diperiksa untuk mencari 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 switch diperlukan untuk setiap kunci baris perintah yang diawali dengan tanda hubung tunggal (-).

Aturan kunci kamus pemetaan switch:

• Switch harus dimulai dengan - atau --.
• Kamus pemetaan switch tidak boleh berisi kunci duplikat.

Untuk menggunakan kamus pemetaan switch, 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 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 switch, panggilan ke CreateDefaultBuilder tidak boleh meneruskan argumen. Panggilan AddCommandLine metode CreateDefaultBuilder tidak menyertakan switch yang dipetakan, dan tidak ada cara untuk meneruskan kamus pemetaan switch ke CreateDefaultBuilder. Solusinya bukan untuk meneruskan argumen ke CreateDefaultBuilder, tetapi untuk memungkinkan metode AddCommandLine dari ConfigurationBuilder memproses argumen dan kamus pemetaan switch.

Mengatur argumen lingkungan dan baris perintah dengan Visual Studio

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

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

Data konfigurasi hierarkis

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

Unduhan sampel berisi file appsettings.json berikut:

{
  "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 terbaik untuk membaca data konfigurasi hierarkis adalah dengan menggunakan pola opsi. Untuk informasi selengkapnya, lihat Mengikat data konfigurasi hierarkis dalam dokumen ini.

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

Kunci dan nilai konfigurasi

Peringatan

Artikel ini memperlihatkan penggunaan string koneksi. Dengan database lokal, pengguna tidak perlu diautentikasi, tetapi dalam produksi, string koneksi terkadang menyertakan kata sandi untuk mengautentikasi. Kredensial kata sandi pemilik sumber daya (ROPC) adalah risiko keamanan yang harus dihindari dalam database produksi. Aplikasi produksi harus menggunakan alur autentikasi paling aman yang tersedia. Untuk informasi selengkapnya tentang autentikasi untuk aplikasi yang disebarkan untuk menguji atau lingkungan produksi, lihat Mengamankan alur autentikasi.

Kunci konfigurasi:

• Tidak sensitif pada 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 menggunakan -- sebagai pemisah. Penyedia konfigurasi Azure Key Vault mengganti -- dengan : secara otomatis 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 diikat 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 dengan urutan sesuai penyedia konfigurasi mereka yang disebutkan dengan jelas. Pesan penyedia konfigurasi dengan kode agar sesuai dengan prioritas untuk sumber konfigurasi mendasar yang diperlukan aplikasi.

Urutan umum penyedia konfigurasi adalah:

1. appsettings.json
2. appsettings.{Environment}.json
3. Rahasia pengguna
4. Variabel lingkungan menggunakan Penyedia konfigurasi Variabel Lingkungan.
5. Argumen baris perintah menggunakan Penyedia konfigurasi baris perintah.

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

Urutan penyedia sebelumnya digunakan dalam konfigurasi default.

Awalan string koneksi

Peringatan

Artikel ini memperlihatkan penggunaan string koneksi. Dengan database lokal, pengguna tidak perlu diautentikasi, tetapi dalam produksi, string koneksi terkadang menyertakan kata sandi untuk mengautentikasi. Kredensial kata sandi pemilik sumber daya (ROPC) adalah risiko keamanan yang harus dihindari dalam database produksi. Aplikasi produksi harus menggunakan alur autentikasi paling aman yang tersedia. Untuk informasi selengkapnya tentang autentikasi untuk aplikasi yang disebarkan untuk menguji atau lingkungan produksi, lihat Mengamankan alur autentikasi.

API Konfigurasi memiliki aturan pemrosesan khusus untuk empat variabel lingkungan string koneksi. String koneksi ini terlibat dalam mengonfigurasikan 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 untuk CUSTOMCONNSTR_, yang tidak memiliki penyedia).

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
• Penyedia konfigurasi JSON
• Penyedia konfigurasi XML

Penyedia konfigurasi INI

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

Kode berikut menambahkan beberapa penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"MyIniConfig.{builder.Environment.EnvironmentName}.ini",
                optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

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

• Penyedia konfigurasi variabel lingkungan
• Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file MyIniConfig.ini berikut:

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}");
    }
}

Penyedia konfigurasi JSON

Memuat JsonConfigurationProvider konfigurasi dari pasangan kunci-nilai file JSON.

Kelebihan beban dapat menentukan:

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

Pertimbangkan gambar berikut:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("MyConfig.json",
        optional: true,
        reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

Kode sebelumnya:

• Mengonfigurasi penyedia konfigurasi JSON 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 file MyConfig.json. Pengaturan dalam file MyConfig.json mengambil alih pengaturan di penyedia konfigurasi default, termasuk Penyedia konfigurasi variabel lingkungan dan Penyedia konfigurasi baris perintah.

Anda biasanya tidak ingin file JSON kustom mengesampingkan nilai yang ditetapkan di penyedia konfigurasi variabel Lingkungan dan penyedia konfigurasi baris perintah.

Penyedia konfigurasi XML

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

Kode berikut menambahkan beberapa penyedia konfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
    .AddXmlFile($"MyXMLFile.{builder.Environment.EnvironmentName}.xml",
                optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

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

• Penyedia konfigurasi variabel lingkungan
• Penyedia konfigurasi baris perintah.

Unduhan sampel berisi file MyXMLFile.xml berikut:

<?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 atribut name 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 metode ekstensi AddKeyPerFile pada instans ConfigurationBuilder. directoryPath ke file harus merupakan jalur absolut.

Izin kelebihan beban menentukan:

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

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

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.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

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}");
    }
}

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

Lihat Mengikat array untuk contoh lain menggunakan MemoryConfigurationProvider.

Konfigurasi titik akhir Kestrel

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

• UseUrls
• --urls pada baris perintah
• Variabel lingkungan ASPNETCORE_URLS

Pertimbangkan file appsettings.json berikut 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"

Kestrel mengikat ke titik akhir yang dikonfigurasikan secara spesifik untuk Kestrel dalam file appsettings.json (https://localhost:9999) dan bukan https://localhost:7777.

Pertimbangkan titik akhir spesifik Kestrel yang dikonfigurasikan sebagai variabel lingkungan:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Dalam variabel lingkungan sebelumnya, Https adalah nama titik akhir spesifik Kestrel. File appsettings.json sebelumnya juga menentukan titik akhir spesifik 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 titik akhir Https.

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 default 99 digunakan.

GetSection, GetChildren, dan Exists

Untuk contoh berikut, pertimbangkan file MySubsection.json berikut:

{
  "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.Configuration
    .AddJsonFile("MySubsection.json",
                 optional: true,
                 reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection mengembalikan subbagian konfigurasi dengan kunci subbagian 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, IConfigurationSection kosong akan dikembalikan.

Saat GetSection mengembalikan bagian yang cocok, Value tidak diisi. 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);
    }
}

Kode sebelumnya memanggil ConfigurationExtensions.Exists untuk memverifikasi bahwa 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.Configuration
    .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 keluaran 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 sesuai dengan "4": "value40", 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 sebagai berikut:

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

Tentukan entitas EFConfigurationValue 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 EFConfigurationContext untuk menyimpan dan mengakses nilai yang dikonfigurasikan.

EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Buat 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 terhadap 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;
    }
}

Metode ekstensi AddEFConfiguration 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 EFConfigurationProvider kustom 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 diinjeksi ke layanan menggunakan Injeksi Dependensi (DI) dengan menyelesaikan layanan IConfiguration:

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 Page:

@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 di tampilan MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Konfigurasi akses di Program.cs

Kode berikut mengakses konfigurasi di file Program.cs.

var builder = WebApplication.CreateBuilder(args);

var key1 = builder.Configuration.GetValue<string>("KeyOne");

var app = builder.Build();

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

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

app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);

app.Run();

Dalam appsettings.json untuk contoh sebelumnya:

{
  ...
  "KeyOne": "Key One Value",
  "KeyTwo": 1999,
  "KeyThree": true
}

Mengonfigurasikan opsi dengan delegasi

Opsi yang dikonfigurasikan dalam delegasi mengambil alih nilai yang diatur di penyedia konfigurasi.

Dalam kode berikut, layanan IConfigureOptions<TOptions> ditambahkan ke kontainer layanan. Ini menggunakan delegasi untuk mengonfigurasikan 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 diambil alih oleh delegasi yang dikonfigurasikan.

Konfigurasi host versus aplikasi

Sebelum aplikasi dikonfigurasikan dan dimulai, host dikonfigurasikan dan diluncurkan. Host bertanggung jawab atas startup aplikasi dan manajemen seumur hidup. Aplikasi dan host dikonfigurasikan 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 yang diawali DOTNET_ (misalnya, DOTNET_ENVIRONMENT) menggunakan Penyedia konfigurasi Variabel Lingkungan. Awalan (DOTNET_) dihapus saat pasangan kunci-nilai konfigurasi dibaca.
  • Argumen baris perintah menggunakan Penyedia konfigurasi baris perintah.
• Konfigurasi default Web Host dibuat (ConfigureWebHostDefaults):
  • Kestrel digunakan sebagai server web dan dikonfigurasikan menggunakan penyedia konfigurasi aplikasi.
  • Tambahkan Middleware Pemfilteran Host.
  • Tambahkan Middleware Header yang Diteruskan jika variabel lingkungan ASPNETCORE_FORWARDEDHEADERS_ENABLED diatur ke true.
  • Mengaktifkan integrasi IIS.

Konfigurasi lainnya

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

• launch.json/launchSettings.json adalah file konfigurasi alat untuk lingkungan Pengembangan, dijelaskan:
  • Di Menggunakan beberapa lingkungan di ASP.NET Core.
  • Di seluruh kumpulan dokumentasi tempat file digunakan untuk mengonfigurasikan 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 diatur di lingkungan sistem.

Untuk informasi selengkapnya tentang memigrasikan konfigurasi aplikasi dari versi ASP.NET sebelumnya, lihat Memperbarui 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 Startup aplikasi. Untuk informasi selengkapnya, lihat Menggunakan rakitan startup hosting di ASP.NET Core.

Generator sumber pengikatan konfigurasi

Generator sumber pengikatan konfigurasi menyediakan konfigurasi AOT dan trim-friendly. Untuk informasi selengkapnya, lihat Generator sumber pengikatan konfigurasi.

Sumber Daya Tambahan:

• Kode sumber konfigurasi
• Kode sumber WebApplicationBuilder
• Melihat atau mengunduh kode sampel (cara mengunduh)
• Pola opsi ASP.NET Core
• Konfigurasi ASP.NET Core Blazor