Konfigurasi di ASP.NET Core

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, termasuk konfigurasi Aplikasi Azure
• Azure Key Vault
• Argumen baris perintah
• Penyedia kustom, diinstal atau dibuat
• Objek .NET dalam memori

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

Untuk panduan konfigurasi tambahanBlazor, yang menambahkan atau menggantikan panduan di sini, lihat konfigurasi ASP.NET CoreBlazor.

Artikel ini terutama berkaitan dengan konfigurasi aplikasi. Jenis konfigurasi lainnya, seperti file pengaturan peluncuran dan web.config file, disebutkan di sini, tetapi dokumentasi utamanya ada di tempat lain:

• Luncurkan file pengaturan (launch.json/launchSettings.json), yang merupakan file konfigurasi alat untuk Development lingkungan. Untuk informasi selengkapnya, lihat lingkungan runtime ASP.NET Core. Beberapa detail tentang pengaturan peluncuran dibahas dalam artikel ini di bagian Pengaturan peluncuran menggantikan pengaturan variabel lingkungan.
• web.config, yang merupakan file konfigurasi server untuk Layanan Informasi Internet (IIS). Untuk informasi selengkapnya, lihat Host ASP.NET Core di Windows dengan IIS dan ASP.NET Core Module (ANCM) untuk IIS.

Untuk informasi selengkapnya tentang memigrasikan konfigurasi aplikasi dari versi ASP.NET sebelumnya, lihat Memigrasikan konfigurasi ke ASP.NET Core.

Warning

Artikel ini memperlihatkan penggunaan string koneksi. Saat menggunakan database lokal untuk pengembangan dan pengujian, autentikasi pengguna database melalui string koneksi tidak diperlukan. Di lingkungan produksi, string koneksi terkadang menyertakan kata sandi untuk mengautentikasi akses database atau operasi database. Kredensial kata sandi pemilik sumber daya (ROPC) dalam string koneksi adalah risiko keamanan yang harus dihindari di aplikasi produksi. Aplikasi produksi harus menggunakan alur autentikasi paling aman yang tersedia. Untuk informasi selengkapnya tentang autentikasi untuk aplikasi yang disebarkan untuk lingkungan pengujian atau produksi, lihat topik keamanan ASP.NET Core.

Contoh dalam artikel ini menggunakan konstruktor utama, tersedia di C# 12 (.NET 8) atau yang lebih baru. Untuk informasi selengkapnya, lihat Mendeklarasikan konstruktor utama untuk kelas dan struktur (tutorial dokumentasi C#) dan Konstruktor utama (Panduan C#).

Membaca nilai konfigurasi

Konfigurasi biasanya dibaca dengan mengakses layanan IConfiguration (Microsoft.Extensions.Configuration namespace) dan menggunakan kunci dari pasangan kunci-nilai konfigurasi untuk mendapatkan nilai konfigurasi.

Kode komponen berikut Razor menunjukkan bagaimana nilai konfigurasi, alamat email kontak teknis, diperoleh dari konfigurasi dengan kunci TechnicalContactEmail.

@inject IConfiguration Config

Technical Contact: @Config["TechnicalContactEmail"]

Konfigurasi aplikasi dan host

Aplikasi ASP.NET Core mengonfigurasi dan meluncurkan host. Host bertanggung jawab atas startup aplikasi dan pengelolaan masa hidup aplikasi. Pasangan kunci-nilai konfigurasi host disertakan dalam konfigurasi aplikasi. Meskipun Anda dapat melakukan beberapa konfigurasi aplikasi dengan penyedia konfigurasi host, kami hanya menyarankan melakukan konfigurasi yang diperlukan untuk host dengan menggunakan konfigurasi host.

Konfigurasi aplikasi adalah prioritas tertinggi. 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.

Sumber konfigurasi aplikasi default

ASP.NET aplikasi web Core memanggil WebApplication.CreateBuilder untuk menginisialisasi instans baru dari kelas WebApplicationBuilder dengan konfigurasi default yang telah diatur sebelumnya.

var builder = WebApplication.CreateBuilder(args);

Untuk informasi selengkapnya, lihat Host Generik .NET di ASP.NET Core.

Konfigurasi aplikasi default dimuat dalam urutan berikut, dari prioritas tertinggi hingga terendah:

1. Argumen baris perintah menggunakan Penyedia Konfigurasi Baris Perintah.
2. Variabel lingkungan tidak diawali dengan ASPNETCORE_ atau DOTNET_ menggunakan Penyedia Konfigurasi Variabel Lingkungan.
3. Rahasia pengguna saat aplikasi berjalan di Development lingkungan menggunakan Penyedia Konfigurasi File.
4. Konfigurasi file pengaturan lingkungan aplikasi melalui , di mana placeholder appsettings.{ENVIRONMENT}.json adalah {ENVIRONMENT} aplikasi, menggunakan Penyedia Konfigurasi JSON. Misalnya, appsettings.Production.json digunakan dalam produksi, dan appsettings.Development.json digunakan selama pengembangan.
5. Konfigurasi file pengaturan aplikasi umum melalui appsettings.json menggunakan Penyedia Konfigurasi JSON.
6. Fallback konfigurasi host.

Note

Kami tidak menyarankan untuk memanggil CreateBuilder lebih dari sekali hanya untuk tujuan mendapatkan nilai konfigurasi pada runtime. Sebaiknya gunakan ConfigurationManager (misalnya: builder.Configuration, WebApplicationBuilder.Configuration) atau menggunakan ConfigurationBuilder dari sumber konfigurasi yang sesuai.

Untuk mengizinkan argumen baris perintah untuk mengontrol pengaturan seperti nama lingkungan, yang penting untuk menentukan file pengaturan aplikasi berbasis lingkungan mana yang akan dimuat, Penyedia Konfigurasi Baris Perintah digunakan dua kali sebagai sumber konfigurasi, di awal dan akhir konfigurasi. Karena penyedia digunakan di akhir, maka memiliki prioritas tertinggi.

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

Sumber konfigurasi host default

Sumber konfigurasi host default dari prioritas tertinggi hingga terendah saat diterapkan ke konfigurasi aplikasi web (WebApplicationBuilder):

1. Argumen baris perintah menggunakan Penyedia Konfigurasi Baris Perintah.
2. Variabel lingkungan yang diawali dengan tanda DOTNET_ menggunakan Penyedia Konfigurasi Variabel Lingkungan.
3. Variabel lingkungan yang diawali dengan tanda ASPNETCORE_ menggunakan Penyedia Konfigurasi Variabel Lingkungan.

Sumber konfigurasi host default dari prioritas tertinggi hingga terendah yang diterapkan ke Host Generik atau Host Web:

1. Variabel lingkungan yang diawali dengan tanda ASPNETCORE_ menggunakan Penyedia Konfigurasi Variabel Lingkungan.
2. Argumen baris perintah menggunakan Penyedia Konfigurasi Baris Perintah.
3. Variabel lingkungan yang diawali dengan tanda DOTNET_ menggunakan Penyedia Konfigurasi Variabel Lingkungan.

Untuk informasi selengkapnya tentang konfigurasi host, lihat sumber daya berikut:

• Host Generik: Direkomendasikan untuk aplikasi ASP.NET Core yang menargetkan .NET 6 atau yang lebih baru yang mengadopsi model hosting minimal.
• Web Host: Diperlukan untuk aplikasi ASP.NET Core yang menargetkan rilis sebelum .NET 6 dan hanya dikelola oleh kerangka kerja untuk kompatibilitas mundur di .NET 6 atau yang lebih baru.

Variabel host

Variabel berikut diatur lebih awal dalam inisialisasi pembangun host dan tidak dapat dipengaruhi oleh konfigurasi aplikasi:

• Nama aplikasi.
• Nama lingkungan.
• Akar konten.
• Direktori root web.
• Apakah akan melakukan pemindaian untuk rakitan awal hosting dan rakitan mana yang harus dipindai.
• Variabel-variabel yang dibaca oleh kode aplikasi dan pustaka dari HostBuilderContext.Configuration dalam IHostBuilder.ConfigureAppConfiguration panggilan balik.

Pengaturan host lainnya dibaca dari konfigurasi aplikasi alih-alih konfigurasi host.

URLS adalah salah satu dari banyak pengaturan host umum yang tidak diinisialisasi oleh konfigurasi host. URLS akan dibaca nanti dari konfigurasi aplikasi. Konfigurasi host berfungsi sebagai fallback untuk konfigurasi aplikasi, sehingga dapat digunakan untuk mengatur URLS, tetapi nilainya akan ditimpa oleh sumber konfigurasi mana pun yang menetapkan URLS dalam konfigurasi aplikasi, seperti file pengaturan aplikasi (appsettings.{ENVIRONMENT}.json, di mana {ENVIRONMENT} adalah tempat penampung untuk nama lingkungan, atau 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.

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.

Sumber konfigurasi file Rahasia Pengguna dari sumber konfigurasi default didaftarkan setelah sumber konfigurasi JSON untuk file pengaturan aplikasi. 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:

• lingkungan runtime ASP.NET Core
• Penyimpanan aman 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.

Konfigurasi akses dengan Injeksi Dependensi (DI)

Konfigurasi dapat disuntikkan ke layanan menggunakan Injeksi Dependensi (DI) dengan menyelesaikan IConfiguration layanan. Dalam contoh berikut, nilai konfigurasi yang disimpan untuk kunci konfigurasi yang diwakili oleh placeholder {KEY} dialokasikan ke value. Jika kunci tidak ditemukan, null ditetapkan ke value:

public class CustomService(IConfiguration config)
{
    public void CustomMethod()
    {
        var value = config["{KEY}"];
    }
}

Mengakses konfigurasi dalam Program file

Kode berikut mengakses konfigurasi dalam Program file menggunakan WebApplicationBuilder.Configuration (builder.Configuration):

var defaultConnectionString = 
   builder.Configuration.GetValue<string>("ConnectionStrings:DefaultConnection");

Setelah aplikasi dibangun (setelah baris var app = builder.Build();), gunakan WebApplication.Configuration (app.Configuration):

var defaultLogLevel = app.Configuration.GetValue<string>("Logging:LogLevel:Default");

Konfigurasi akses di kelas Startup

Bagian ini umumnya berlaku untuk aplikasi ASP.NET Core sebelum rilis .NET 6.

Kode berikut menampilkan data konfigurasi di metode Startup:

public class Startup
{
    public Startup(IConfiguration config)
    {
        Config = config;
    }

    public IConfiguration Config { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = Config["ConnectionStrings.DefaultConnection"];

        ...
    }

    public void Configure(...)
    {
        var defaultLogLevel = Config["Logging:LogLevel:Default"];

        ...
    }
}

Tampilkan pengaturan konfigurasi saat startup untuk debugging

Kode berikut menampilkan pasangan kunci-nilai konfigurasi aplikasi saat pengaktifan aplikasi.

Setelah aplikasi dibangun dalam Program file (setelah baris var app = builder.Build();), tempatkan kode berikut, yang mencakup direktif kompilator untuk konfigurasi DEBUG:

#if DEBUG
foreach (var c in app.Configuration.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

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 oleh 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 tidak berfungsi di semua platform. Garis bawah ganda (__) didukung oleh semua platform dan secara otomatis dikonversi menjadi titik dua (:) saat konfigurasi dibaca oleh aplikasi.
  • Di Azure Key Vault, kunci hierarkis menggunakan tanda hubung ganda (--) sebagai pemisah. Penyedia Konfigurasi Azure Key Vault secara otomatis mengganti tanda hubung ganda (--) dengan titik dua (:) saat rahasia dimuat ke dalam konfigurasi aplikasi.
• ConfigurationBinder mendukung pengikatan array ke objek menggunakan indeks array dalam kunci konfigurasi. Pengikatan array dijelaskan di bagian Pengikatan array.

Nilai konfigurasi adalah string. Nilai null tidak dapat disimpan dalam konfigurasi atau diikat ke objek.

Bagaimana data konfigurasi hierarkis terorganisir

API Konfigurasi membaca data konfigurasi hierarkis dengan meratakan data hierarkis dengan penggunaan pemisah dalam kunci konfigurasi, yang biasanya merupakan titik dua (:). Garis bawah ganda (__) biasanya digunakan dengan konfigurasi variabel lingkungan untuk dukungan lintas platform.

Note

Dalam skenario konfigurasi aplikasi yang kompleks, yang terbaik adalah mengelompokkan dan membaca data konfigurasi hierarkis terkait menggunakan pola opsi.

Pertimbangkan data konfigurasi hierarkis berikut:

• ConnectionStrings
  • DefaultConnection (Value = 'Data Source=LocalSqlServer\MSSQLDev;')
• Logging
  • LogLevel
    • Default (Value = 'Information')
    • Microsoft (Value = 'Warning')
    • Microsoft.Hosting.Lifetime (Value = 'Information')
• AllowedHosts (Value = '*')

Tabel berikut menampilkan kunci yang digunakan untuk memulihkan nilai dalam data konfigurasi sebelumnya. Pemisah tidak diperlukan untuk AllowedHosts.

Kunci (pemisah titik dua)	Kunci (pembatas garis bawah ganda)
ConnectionStrings:DefaultConnection	ConnectionStrings__DefaultConnection
Logging:LogLevel:Default	Logging__LogLevel__Default
Logging:LogLevel:Microsoft	Logging__LogLevel__Microsoft
Logging:LogLevel:Microsoft.Hosting.Lifetime	Logging__LogLevel__Microsoft.Hosting.Lifetime
AllowedHosts	AllowedHosts

Note

Dalam skenario konfigurasi aplikasi yang kompleks, kami merekomendasikan pengelompokan dan membaca data konfigurasi hierarkis terkait menggunakan pola Opsi.

Metode GetSection dan GetChildren tersedia untuk mengisolasi bagian dan sub-bagian dari suatu bagian di data konfigurasi. Metode ini dijelaskan di mana GetSection, GetChildren, dan Exists tercakup.

Ketika struktur elemen menyertakan array, indeks array harus diperlakukan sebagai nama elemen tambahan di jalur. Pertimbangkan data konfigurasi hierarkis berikut sebagai array.

MainObject (larik):

• Elemen pertama dalam array
  • Object0
  • Object1
    • SubObject0
    • SubObject1
• Item kedua dalam larik
  • Object0
  • Object1
    • SubObject0
    • SubObject1

Kunci dengan pemisah titik dua:

• MainObject:0:Object0
• MainObject:0:Object1:SubObject0
• MainObject:0:Object1:SubObject1
• MainObject:1:Object0
• MainObject:1:Object1:SubObject0
• MainObject:1:Object1:SubObject1

Kunci dengan pemisah garis bawah, yang direkomendasikan untuk kompatibilitas lintas platform saat konfigurasi disediakan oleh variabel lingkungan:

• MainObject__0__Object0
• MainObject__0__Object1:SubObject0
• MainObject__0__Object1:SubObject1
• MainObject__1__Object0
• MainObject__1__Object1:SubObject0
• MainObject__1__Object1:SubObject1

Karena konfigurasi yang berasal dari array diratakan dan diberi nomor berurutan untuk setiap sumber konfigurasi yang digunakan oleh aplikasi, nilai-nilai dapat ditimpa secara tak terduga jika kita tidak berhati-hati dalam menyusun dan membaca data dari beberapa sumber. Pertimbangkan pasangan kunci-nilai konfigurasi berikut:

Modules daftar nilai (array):

• Module1
• Module2
• Module3

Array diratakan dan diindeks secara berurutan, menghasilkan pasangan konfigurasi kunci-nilai dalam tabel berikut.

Key	Nilai
Modules:0	Module1
Modules:1	Module2
Modules:2	Module3

Setelah konfigurasi sebelumnya dibuat, sumber konfigurasi lain memuat konfigurasi berikut:

Modules daftar nilai (array):

• Module4
• Module5

Array ini juga diratakan dan diindeks secara berurutan.

Key	Nilai
Modules:0	Module4
Modules:1	Module5

Mengingat bahwa sumber konfigurasi terakhir untuk kunci tertentu menetapkan nilai kunci tersebut, kumpulan akhir pasangan kunci-nilai konfigurasi ditampilkan dalam tabel berikut.

Key	Nilai
Modules:0	Module4
Modules:1	Module5
Modules:2	Module3

Ini bukan hasil yang mengejutkan mengingat cara kerangka kerja ini meratakan dan mengindeks data array dari sumber konfigurasi, tetapi penting untuk diingat agar tidak terjadi penimpaan yang tidak terduga.

Untuk menghindari penimpaan tersebut, struktur pengindeksan array agar dapat mempertemukan di berbagai sumber konfigurasi yang menyediakan data array yang sama. Atau, pendekatan solusinya adalah memisahkan nilai array dalam nilai string dari pasangan nilai kunci tunggal, misalnya menggunakan koma, titik koma, atau pipa sebagai pemisah. Tulis kode kustom untuk membagi string dan menetapkan nilai yang dibatasi ke array Anda.

Penyedia konfigurasi

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

Provider	Menyediakan konfigurasi dari...
Penyedia Konfigurasi Azure Key Vault	Azure Key Vault
Azure App Configuration Penyedia	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	Berkas direktori
Penyedia Konfigurasi Memori	Koleksi dalam memori
Rahasia pengguna	File di direktori profil pengguna

Sumber konfigurasi dibaca dalam urutan yang ditentukan oleh penyedia konfigurasi mereka. Atur penyedia konfigurasi dalam kode untuk mencocokkan dengan prioritas sumber konfigurasi mendasar yang dibutuhkan oleh aplikasi.

Urutan umum penyedia konfigurasi adalah:

1. Pengaturan aplikasi umum melalui appsettings.json.
2. Pengaturan aplikasi lingkungan melalui appsettings.{ENVIRONMENT}.json, di mana penampung {ENVIRONMENT} adalah lingkungan aplikasi (contoh: Development, Production).
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 yang terakhir dalam serangkaian penyedia untuk memungkinkan argumen baris perintah mengambil alih konfigurasi yang ditetapkan oleh penyedia lain.

Urutan penyedia sebelumnya digunakan dalam konfigurasi default.

Untuk memeriksa penyedia konfigurasi aplikasi, masukkanIConfiguration, transmisikan ke IConfigurationRoot, dan baca Providers properti .

Dalam komponen berikut ConfigurationProvidersRazor menampilkan penyedia konfigurasi yang diaktifkan dalam urutan ditambahkan ke aplikasi.

Pages/ConfigurationProviders.razor:

@page "/configuration-providers"
@inject IConfiguration Config

<h1>Configuration Providers</h1>

@if (ConfigRoot is not null)
{
    <ul>
        @foreach (var provider in ConfigRoot.Providers)
        {
            <li>@provider</li>
        }
    </ul>
}

@code {
    private IConfigurationRoot? ConfigRoot;

    protected override void OnInitialized()
    {
        ConfigRoot = (IConfigurationRoot)Config;
    }
}

Komponen Razor yang disebutkan sebelumnya menghasilkan output berikut, di mana {APP NAMESPACE} placeholder adalah namespace aplikasi.

MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'ASPNETCORE_'
MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'DOTNET_'
JsonConfigurationProvider for 'appsettings.json' (Optional)
JsonConfigurationProvider for 'appsettings.Development.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.Development.json' (Optional)
EnvironmentVariablesConfigurationProvider
Microsoft.Extensions.Configuration.ChainedConfigurationProvider

Di bagian Sumber konfigurasi aplikasi default sebelumnya dalam artikel ini, sumber konfigurasi tercantum dari prioritas tertinggi hingga terendah. Komponen sebelumnya ConfigurationProviders menampilkan sumber dalam urutan aplikasi membacanya. Misalnya, Penyedia Konfigurasi JSON untuk file pengaturan aplikasi yang bukan untuk lingkungan (appsettings.json) terletak lebih awal dalam daftar di atas karena ditambahkan sebelum penyedia untuk file pengaturan untuk lingkungan pengembangan (appsettings.Development.json). Penyedia konfigurasi dijalankan dari bagian atas daftar ke bagian bawah daftar. Untuk kunci konfigurasi yang cocok antara dua pengaturan aplikasi Penyedia Konfigurasi JSON, pengaturan terakhir lebih diutamakan, yang merupakan nilai dari appsettings.Development.json.

Konfigurasi file pengaturan aplikasi (appsettings.json, appsettings.{ENVIRONMENT}.json)

Baca konfigurasi yang dimuat dari file pengaturan aplikasi menggunakan Penyedia Konfigurasi JSON.

Pertimbangkan file appsettings.json berikut:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=LocalSqlServer\\MSSQLDev;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Masukkan instans IConfiguration untuk membaca nilai konfigurasi.

Komponen berikut AppSettingsConfigurationRazor membaca string koneksi database default dan konfigurasi tingkat pengelogan default. IConfiguration disuntikkan di bagian atas komponen dan digunakan untuk membaca nilai konfigurasi. Pemisah titik dua (:) digunakan dalam kunci konfigurasi jenis string untuk menemukan properti JSON yang sesuai. Misalnya, struktur JSON untuk objek string koneksi default (DefaultConnection) disarangkan di bawah objek string koneksi (ConnectionStrings), sehingga notasi string untuk mengakses string koneksi default menggunakan titik dua untuk memisahkan DefaultConnection dan ConnectionStrings dalam urutan objek muncul dalam file pengaturan aplikasi: ConnectionStrings:DefaultConnection.

Pages/AppSettingsConfiguration.razor:

@page "/app-settings-configuration"
@inject IConfiguration Config

<h1>App Settings Configuration</h1>

<ul>
    <li>Default Connection String: @Config["ConnectionStrings:DefaultConnection"]
    <li>Default Log Level: @Config["Logging:LogLevel:Default"]
</ul>

Pendekatan yang sama diambil dalam model halaman Page Razor.

using Microsoft.Extensions.Configuration;

...

public class AppSettingsPageModel(IConfiguration config) : PageModel
{
    public ContentResult OnGet()
    {
        var defaultConnectionString = config["ConnectionStrings:DefaultConnection"];
        var defaultLogLevel = config["Logging:LogLevel:Default"];

        return Content(
            $"Default Connection String: {defaultConnectionString}\n" +
            $"Default Log Level: {defaultLogLevel}");
    }
}

Konfigurasi pemuatan default untuk instans JsonConfigurationProvider diatur dalam urutan berikut:

1. appsettings.json
2. appsettings.{ENVIRONMENT}.json, di mana {ENVIRONMENT} placeholder adalah lingkungan aplikasi (contoh: appsettings.Production.json, appsettings.Development.json). Versi lingkungan dari berkas dimuat berdasarkan IHostingEnvironment.EnvironmentName.

Nilai appsettings.{ENVIRONMENT}.json menggantikan kunci dalam appsettings.json.

Secara default:

• Di lingkungan Pengembangan, konfigurasi appsettings.Development.json akan menimpa nilai yang ditemukan di appsettings.json.
• Lingkungan Produksi, konfigurasi appsettings.Production.json menimpa nilai yang ditemukan di appsettings.json.

Contoh sebelumnya hanya membaca string dan tidak mendukung nilai default. Jika perlu menjamin nilai konfigurasi dengan nilai bawaan, lihat bagian Ekstraksi nilai tunggal dari konfigurasi dengan konversi tipe (GetValue).

Menggunakan sumber konfigurasi aplikasi bawaan, file appsettings.json dan appsettings.{ENVIRONMENT}.json diaktifkan dengan reloadOnChange disetel ke true. Ini berarti perubahan yang dilakukan pada file appsettings.json atau appsettings.{ENVIRONMENT}.json setelah aplikasi dimulai akan langsung berlaku setelah file disimpan.

Komentar di berkas appsettings.json dan appsettings.{ENVIRONMENT}.json didukung menggunakan komentar gaya JavaScript atau C#. Beberapa lingkungan pengembangan terintegrasi (IDEs) menampilkan kesalahan saat mengedit file JSON yang berisi komentar karena spesifikasi JSON resmi (RFC 7159) tidak memberikan jatah untuk komentar dalam file JSON. Anda umumnya dapat mengabaikan kesalahan komentar dan peringatan, tetapi Anda juga biasanya dapat menonaktifkan peringatan atau kesalahan dengan pengaturan di IDE. Di Visual Studio Code, misalnya, tambahkan yang berikut ini ke settings.json file untuk menonaktifkan kesalahan:

"files.associations": {
  "appsettings*.json": "jsonc"
}

Pengaturan sebelumnya menunjukkan ke Visual Studio Code bahwa file pengaturan aplikasi, termasuk file berbasis lingkungan, dikaitkan dengan format file JSONC ("JSON dengan Komentar"), yang mendukung komentar.

Untuk IDE lain, periksa dokumentasi IDE dan saluran dukungan produk untuk menentukan cara menonaktifkan kesalahan atau peringatan tentang komentar dalam file JSON.

Penyedia Konfigurasi Variabel Lingkungan

Penyedia Konfigurasi Variabel Lingkungan default (EnvironmentVariablesConfigurationProvider) memuat konfigurasi dari variabel lingkungan yang tidak diawali dengan ASPNETCORE_ atau DOTNET_. Untuk informasi selengkapnya tentang ASPNETCORE_ variabel lingkungan dan DOTNET_ , lihat bagian Sumber konfigurasi host default dan DOTNET_ variabel lingkungan (dokumentasi.NET Core).

Menggunakan Penyedia Konfigurasi Variabel Lingkungan default, aplikasi 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 variabel lingkungan menggantikan 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, __, didukung oleh semua platform dan secara otomatis digantikan oleh titik dua, :.

Untuk panduan tentang mengatur variabel lingkungan dalam shell perintah di Windows atau di shell perintah PowerShell lintas platform, lihat sumber daya berikut:

• set (variabel lingkungan)
• setx
• about_Environment_Variables (dokumentasi PowerShell)

Awalan kustom untuk variabel lingkungan

Anda dapat menambahkan penyedia konfigurasi untuk variabel lingkungan yang diawali kustom. Dalam file Program, panggil AddEnvironmentVariables dengan string untuk menentukan prefiks setelah memanggil WebApplication.CreateBuilder. Penyedia ditambahkan setelah penyedia konfigurasi default, sehingga penyedia yang ditambahkan memiliki prioritas yang lebih tinggi, termasuk daripada variabel lingkungan dengan nama yang sama tanpa awalan.

Dalam contoh berikut, variabel lingkungan ditambahkan dengan awalan CustomPrefix_ :

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

Prefiks konfigurasi dihapus saat pasangan kunci-nilai dibaca.

Pengaturan peluncuran mengesampingkan pengaturan variabel lingkungan

Variabel lingkungan yang diatur dalam launchSettings.json menggantikan 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"

Mengonfigurasi applicationUrl menetapkan variabel lingkungan ASPNETCORE_URLS dan menggantikan nilai yang diatur di lingkungan.

Keluar variabel lingkungan di Linux

Di Linux, nilai variabel lingkungan URL harus dikeluarkan agar systemd dapat mengurainya. Dalam contoh berikut, alat systemd-escape Linux digunakan untuk menghasilkan http:--localhost:5001 dari http://localhost:5001:

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

Pengaturan aplikasi Azure App Service (variabel lingkungan)

Untuk panduan pengaturan aplikasi Azure App Service (variabel lingkungan), lihat sumber daya berikut:

• Mengonfigurasi aplikasi App Service (dokumentasi Azure)
• Awalan string koneksi database Azure

Awalan koneksi string

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

Awalan string koneksi	Provider
APIHUBCONNSTR_	Hub API Azure
CUSTOMCONNSTR_	Penyedia kustom
DOCDBCONNSTR_	Azure Cosmos DB
EVENTHUBCONNSTR_	Azure Event Hubs
MYSQLCONNSTR_	MySQL
NOTIFICATIONHUBCONNSTR_	Azure Notification Hubs
POSTGRESQLCONNSTR_	PostgreSQL
REDISCACHECONNSTR_	Azure Cache for Redis
SERVICEBUSCONNSTR_	Azure Service Bus
SQLAZURECONNSTR_	Azure SQL Database
SQLCONNSTR_	SQL Server

Ketika variabel lingkungan ditemukan dan dimuat ke dalam konfigurasi dengan salah satu awalan yang dikenali:

• Kunci konfigurasi dibuat dengan menghapus awalan variabel lingkungan dan menambahkan bagian kunci konfigurasi (ConnectionStrings).
• Pasangan kunci-nilai konfigurasi baru dibuat yang menggambarkan penyedia koneksi database ketika nama penyedia terkait dengan awalan.

Kunci variabel lingkungan	Kunci konfigurasi yang dikonversi	Entri konfigurasi penyedia
APIHUBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
DOCDBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
EVENTHUBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kunci: ConnectionStrings:{KEY}_ProviderName: Nilai: MySql.Data.MySqlClient
NOTIFICATIONHUBCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
POSTGRESQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kunci: ConnectionStrings:{KEY}_ProviderName: Nilai: Npgsql
REDISCACHECONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
SERVICEBUSCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entri konfigurasi tidak dibuat.
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Kunci: ConnectionStrings:{KEY}_ProviderName: Nilai: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kunci: ConnectionStrings:{KEY}_ProviderName: Nilai: System.Data.SqlClient

Command-line

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

• File appsettings.json dan appsettings.{ENVIRONMENT}.json.
• Rahasia aplikasi di Development lingkungan.
• Variabel lingkungan.

Secara default, nilai konfigurasi yang diatur melalui baris perintah akan menggantikan nilai konfigurasi yang diatur oleh semua penyedia konfigurasi lainnya.

Argumen baris perintah

Perintah berikut dotnet run mengatur kunci dan nilai menggunakan tanda sama dengan (=):

dotnet run ConnectionStrings:DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;" Logging:LogLevel:Default=Information

Perintah berikut menetapkan kunci dan nilai menggunakan garis miring ke depan (/):

dotnet run /ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" /Logging:LogLevel:Default Information

Perintah berikut mengatur kunci dan nilai menggunakan tanda hudah ganda (--):

dotnet run --ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" --Logging:LogLevel:Default Information

Konvensi argumen:

• Nilai kunci harus mengikuti tanda sama dengan (=), atau kunci harus memiliki awalan tanda hubung ganda (--) atau garis miring (/) saat nilai mengikuti spasi.
• Jika tidak menetapkan nilai setelah tanda sama dengan (=), maka akan menetapkan string kosong untuk pengaturan konfigurasi. Misalnya, mengatur ConnectionStrings:DefaultConnection= adalah valid dan menghasilkan penyematan string kosong ke string koneksi default.
• Dalam perintah yang sama, jangan mencampur pasangan kunci-nilai argumen yang dipisahkan oleh tanda sama dengan (=) dengan pasangan nilai kunci yang dipisahkan oleh spasi.

Beralih pemetaan

Pemetaan sakelar memungkinkan logika penggantian nama kunci dengan menggunakan kamus penggantian sakelar yang diberikan kepada 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 dari kamus dikembalikan untuk menetapkan pasangan kunci-nilai ke dalam konfigurasi aplikasi. Pemetaan sakelar diperlukan untuk setiap kunci baris perintah yang diawali dengan tanda hubung tunggal (-).

Aturan kunci kamus pemetaan switch:

• Sakelar harus dimulai dengan tanda hubung tunggal (-) atau tanda hubung ganda (--).
• Kamus pemetaan saklar tidak boleh berisi kunci duplikat.

Dalam contoh berikut, kamus pemetaan sakelar (switchMappings) diteruskan ke AddCommandLine dalam file aplikasi Program :

var switchMappings = 
    new Dictionary<string, string>(){ { "-k1", "key1" }, { "-k2", "key2" } };

builder.Configuration.AddCommandLine(args, switchMappings);

Perintah berikut dotnet run menunjukkan penggantian kunci (value1 ke dalam key1 dan value2 ke dalam key2):

• dotnet run -k1 value1 -k2 value2
• dotnet run --k1=value1 --k2=value2
• dotnet run --k1 value1 --k2 value2
• dotnet run /k1=value1 /k2=value2
• dotnet run /k1 value1 /k2 value2

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

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

Konfigurasi IniConfigurationProvider dimuat dari pasangan kunci-nilai file INI. Contoh berikut ini menunjukkan cara menggunakan penyedia. Kelebihan beban dapat menentukan apakah file bersifat opsional dan apakah konfigurasi dimuat ulang pada perubahan file.

IniConfig.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;"

[Logging:LogLevel]
Default=Debug
Microsoft=Debug

IniConfig.Production.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLProd;"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Muat konfigurasi dengan memanggil AddIniFile. Contoh berikut membuat sumber konfigurasi untuk setiap file sebelumnya. File yang tidak terkait lingkungan memuat ulang konfigurasi jika file diubah (parameter reloadOnChange, default: false). Versi lingkungan file menentukan bahwa file bersifat opsional (optional parameter, default: false). Jika Anda ingin menentukan memuat ulang file pada perubahan (reloadOnChange: true), maka Anda juga harus menentukan apakah file bersifat opsional (optional).

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

Penyedia Konfigurasi JSON

Konfigurasi JsonConfigurationProvider dimuat dari pasangan kunci-nilai dalam file JSON. Contoh berikut ini menunjukkan cara menggunakan penyedia. Kelebihan beban dapat menentukan apakah file bersifat opsional dan apakah konfigurasi dimuat ulang pada perubahan file.

Panggil AddJsonFile dengan jalur file (atau nama file jika file berada di akar aplikasi). Berikut ini membuat file opsional (optional parameter, default: false) dan menentukan bahwa konfigurasi dimuat ulang jika file diubah (reloadOnChange parameter, default: false). Jika Anda ingin menentukan memuat ulang file pada perubahan (reloadOnChange: true), maka Anda juga harus menentukan apakah file bersifat opsional (optional).

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

Penyedia Konfigurasi XML

Konfigurasi XmlConfigurationProvider dimuat dari pasangan kunci-nilai file XML. Contoh berikut ini menunjukkan cara menggunakan penyedia. Kelebihan beban dapat menentukan apakah file bersifat opsional dan apakah konfigurasi dimuat ulang pada perubahan file.

XmlFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnection>Data Source=LocalSqlServer\\MSSQLDev;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Debug</Default>
      <Microsoft>Debug</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

XmlFile.Production.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnectionString>Data Source=LocalSqlServer\\MSSQLProd;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Muat konfigurasi dengan memanggil AddXmlFile. Contoh berikut membuat sumber konfigurasi untuk setiap file sebelumnya. File yang tidak terkait lingkungan memuat ulang konfigurasi jika file diubah (parameter reloadOnChange, default: false). Versi lingkungan file menentukan bahwa file bersifat opsional (optional parameter, default: false). Jika Anda ingin menentukan memuat ulang file pada perubahan (reloadOnChange: true), maka Anda juga harus menentukan apakah file bersifat opsional (optional).

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

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>

var value_00 = Config["section:section0:key:key0"];
var value_01 = Config["section:section0:key:key1"];
var value_10 = Config["section:section1:key:key0"];
var value_11 = Config["section:section1:key:key1"];

Atribut-atribut yang menyediakan nilai tersebut didukung.

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

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-Berka 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.

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
builder.Configuration.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 configSettings = new Dictionary<string, string>
{
    { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
    { "Logging:LogLevel:Default", "Information" }
};

builder.Configuration.AddInMemoryCollection(configSettings);

Konfigurasi titik akhir Kestrel

Konfigurasi titik akhir spesifik menggantikan semua konfigurasi titik akhir lintas server. Konfigurasi titik akhir lintas server meliputi:

• UseUrls.
• --urls pada baris perintah.
• Variabel ASPNETCORE_URLSlingkungan.

Pertimbangkan bagian konfigurasi berikut Kestrel dalam appsettings.json file:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:9999"
    }
  }
},

Aplikasi ini diluncurkan pada baris perintah dengan dotnet run dan konfigurasi titik akhir lintas server berikut:

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

Kestrel mengikat ke titik akhir yang dikonfigurasi khusus untuk Kestrel dalam file appsettings.json dan bukan pada konfigurasi titik akhir lintas server yang diteruskan ke perintah https://localhost:9999dotnet run.

Namun, pertimbangkan titik akhir khusus Kestrel yang dikonfigurasi sebagai variabel lingkungan.

• Kunci: Kestrel__Endpoints__Https__Url
• Nilai: https://localhost:8888

Dalam variabel lingkungan sebelumnya, "Https" adalah nama titik akhir spesifik-Kestrel. Konfigurasi pengaturan aplikasi sebelumnya juga menentukan suatu titik akhir yang spesifik bernama Kestrel. Berdasarkan penyedia konfigurasi host default, variabel lingkungan yang dibaca oleh Penyedia Konfigurasi Variabel Lingkungan akan dibaca setelah appsettings.{ENVIRONMENT}.json. Oleh karena itu, variabel lingkungan sebelumnya (Kestrel__Endpoints__Https__Url) digunakan untuk Https titik akhir.

Ekstrak satu nilai dari konfigurasi dengan perubahan tipe (GetValue)

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

var number = Config.GetValue<int>("NumberKey", 99);

Dalam kode sebelumnya:

• Config adalah suatu injeksi IConfiguration.
• Jika NumberKey tidak ditemukan dalam konfigurasi, nilai 99 default digunakan.

Bekerja dengan segmen, mendapatkan sub-bagian dari segmen, dan memeriksa apakah segmen ada

Untuk contoh berikut, pertimbangkan file subsection.json berikut:

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

Penyedia konfigurasi ditambahkan untuk subsection.json dengan memanggil AddJsonFile.

GetSection

IConfiguration.GetSection mengembalikan subbagian konfigurasi dengan kunci subbagian yang ditentukan.

Kode berikut mengembalikan nilai untuk section1, di mana Config adalah yang disuntikkan IConfiguration:

var subsection = Config.GetSection("section1");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

Kode berikut mengembalikan nilai untuk section2:subsection0, di mana Config adalah yang disuntikkan IConfiguration:

var subsection = Config.GetSection("section2:subsection0");
var value1 = subsection["key0"];
var value2 = subsection["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 tersebut ada.

GetChildren dan Exists

Kode berikut memanggil:

• ConfigurationExtensions.Exists untuk memverifikasi bahwa section2 ada.
• IConfiguration.GetChildren dan mengembalikan nilai untuk sub bagian dari section2.

var section = Config.GetSection("section2");

if (!section.Exists())
{
    throw new Exception("section2 doesn't exist!");
}

var children = section.GetChildren();

foreach (var subSection in children)
{
    int i = 0;
    var key1 = subSection.Key + ":key" + i++.ToString();
    var key2 = subSection.Key + ":key" + i.ToString();
    Console.WriteLine($"{key1} value: {section[key1]}");
    Console.WriteLine($"{key2} value: {section[key2]}");
}

Keluaran:

subsection0:key0 value: value200
subsection0:key1 value: value201
subsection1:key0 value: value210
subsection1:key1 value: value211

Menghubungkan 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.

array.json:

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

Penyedia konfigurasi ditambahkan untuk array.json dengan memanggil AddJsonFile.

Kode berikut membaca nilai konfigurasi.

ArrayExample.cs:

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

var array = Config.GetSection("array").Get<ArrayExample>();

if (array is null)
{
    throw new ArgumentNullException(nameof(array));
}

for (int j = 0; j < array.Entries?.Length; j++)
{
    Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
}

Keluaran:

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 array.json. Indeks array terikat bersifat berkelanjutan dan tidak terikat ke indeks kunci konfigurasi. Pengikat konfigurasi tidak mampu mengikat null nilai atau membuat null entri dalam objek terikat.

Item konfigurasi yang hilang untuk Indeks 3 dapat disediakan sebelum melakukan pengikatan ke instans ArrayExample oleh penyedia konfigurasi mana pun yang membaca pasangan kunci/nilai dari Indeks 3. Dalam contoh berikut, asumsikan bahwa nilai yang disediakan oleh array.json dalam contoh sebelumnya disediakan oleh koleksi dalam memori. Contoh menunjukkan cara memuat nilai Indeks 3 dari Penyedia Konfigurasi JSON sebelum koleksi terikat.

value3.json:

{
  "array:entries:3": "value30"
}

var configSettings = new Dictionary<string, string>
{
    { "array:entries:0", "value00" },
    { "array:entries:1", "value10" },
    { "array:entries:2", "value20" },
    { "array:entries:4", "value40" },
    { "array:entries:5", "value50" }
};

builder.Configuration.AddInMemoryCollection(configSettings);
builder.Configuration.AddJsonFile("value3.json", optional: false, 
    reloadOnChange: false);

Kode sebelumnya menghasilkan array terikat berikut:

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

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 huruf besar/kecil, kamus yang digunakan untuk menginisialisasi database dibuat dengan pembanding yang tidak peka huruf besar/kecil, StringComparer.OrdinalIgnoreCase.

EFConfigurationProvider/EFConfigurationProvider.cs:

using Microsoft.EntityFrameworkCore;

public class EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction) : ConfigurationProvider
{
    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 Dictionary<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 kustom EFConfigurationProvider dalam file aplikasi Program :

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

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

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 pengikat konfigurasi sumber menyediakan konfigurasi AOT dan ramah pemangkasan. Untuk informasi selengkapnya, lihat pembuat kode sumber pengikatan konfigurasi.

Sumber daya tambahan

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