Penyedia konfigurasi pada .NET

Konfigurasi di .NET dimungkinkan dengan penyedia konfigurasi. Beberapa jenis penyedia mengandalkan berbagai sumber konfigurasi. Artikel ini merinci semua penyedia konfigurasi yang berbeda dan sumber yang sesuai.

• Penyedia layanan konfigurasi berkas
• Penyedia konfigurasi variabel lingkungan
• Penyedia Konfigurasi baris perintah
• Penyedia konfigurasi berdasarkan kunci per berkas
• Penyedia konfigurasi memori

Penyedia konfigurasi file

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

• Penyedia konfigurasi JSON
• Penyedia konfigurasi XML
• Penyedia konfigurasi INI

Kunci tidak peka huruf besar/kecil. Semua penyedia konfigurasi file melemparkan FormatException ketika kunci duplikat ditemukan dalam satu penyedia.

Penyedia konfigurasi JSON

Kelas JsonConfigurationProvider memuat konfigurasi dari file JSON. Microsoft.Extensions.Configuration.Json Instal paket NuGet.

Kelebihan beban dapat menentukan:

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

Pertimbangkan kode berikut:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

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

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Kode sebelumnya:

• Menghapus semua penyedia konfigurasi yang ada yang ditambahkan secara default dalam CreateApplicationBuilder(String[]) metode .
• Mengonfigurasi penyedia konfigurasi JSON untuk memuat appsettings.json dan appsettings.Environment.file json dengan opsi berikut:
  • optional: true: File bersifat opsional.
  • reloadOnChange: true: File dimuat ulang saat perubahan disimpan.

Penting

Saat menambahkan penyedia konfigurasi dengan IConfigurationBuilder.Add, penyedia konfigurasi tambahan ditambahkan ke akhir IConfigurationSource daftar. Ketika kunci ditemukan oleh beberapa penyedia, penyedia terakhir yang membaca kunci menggantikan penyedia sebelumnya.

Contoh file appsettings.json dengan berbagai pengaturan konfigurasi berikut:

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

Pada IConfigurationBuilder instans, setelah penyedia konfigurasi ditambahkan, Anda dapat memanggil IConfigurationBuilder.Build() untuk mendapatkan objek IConfigurationRoot. Akar konfigurasi mewakili akar hierarki konfigurasi. Bagian dari konfigurasi dapat terikat ke instans objek .NET dan kemudian disediakan sebagai IOptions<TOptions> melalui injeksi dependensi.

Catatan

Properti Tindakan Build dan Salin ke Direktori Output untuk file JSON perlu diatur menjadi Konten dan Salin jika lebih baru (atau Salin selalu).

Pertimbangkan kelas yang TransientFaultHandlingOptions didefinisikan sebagai berikut:

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Kode berikut membangun akar konfigurasi, mengikat bagian ke TransientFaultHandlingOptions jenis kelas, dan mencetak nilai terikat ke jendela konsol:

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

Aplikasi menulis contoh output berikut:

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

Penyedia konfigurasi XML

Kelas XmlConfigurationProvider memuat konfigurasi dari file XML saat runtime. Microsoft.Extensions.Configuration.Xml Instal paket NuGet.

Kode berikut menunjukkan konfigurasi file XML menggunakan penyedia konfigurasi XML.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Kode sebelumnya:

• Menghapus semua penyedia konfigurasi yang ada yang ditambahkan secara default dalam CreateApplicationBuilder(String[]) metode .
• Mengonfigurasi penyedia konfigurasi XML untuk memuat file appsettings.xml dan repeating-example.xml dengan opsi berikut:
  • optional: true: File bersifat opsional.
  • reloadOnChange: true: File dimuat ulang saat perubahan disimpan.
• Mengonfigurasi penyedia konfigurasi variabel lingkungan.
• Mengonfigurasi penyedia konfigurasi baris perintah jika args yang diberikan berisi argumen.

Pengaturan XML digantikan oleh pengaturan di penyedia konfigurasi variabel lingkungan dan penyedia konfigurasi baris perintah.

Contoh file appsettings.xml dengan berbagai pengaturan konfigurasi berikut:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Petunjuk / Saran

Untuk menggunakan tipe IConfiguration dalam aplikasi WinForms, tambahkan "referensi ke" paket NuGet "Microsoft.Extensions.Configuration.Xml". Instansiasi ConfigurationBuilder dan memanggil secara berantai ke AddXmlFile dan Build(). Untuk informasi selengkapnya, lihat Masalah Dokumen .NET #29679.

Di .NET 5 dan versi yang lebih lama, tambahkan name atribut untuk membedakan elemen berulang yang menggunakan nama elemen yang sama. Di .NET 6 dan versi yang lebih baru, penyedia konfigurasi XML secara otomatis mengindeks elemen berulang. Itu berarti Anda tidak perlu menentukan name atribut, kecuali jika Anda menginginkan indeks "0" di kunci dan hanya ada satu elemen. (Jika Anda memutakhirkan ke .NET 6 atau yang lebih baru, Anda mungkin mengalami jeda yang dihasilkan dari perubahan perilaku ini. Untuk informasi selengkapnya, lihat Elemen XML berulang menyertakan indeks.)

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

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

Aplikasi akan menulis output sampel berikut:

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

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 INI

Kelas IniConfigurationProvider memuat konfigurasi dari file INI saat runtime.

Kode berikut menghapus semua penyedia konfigurasi dan menambahkan IniConfigurationProvider dengan dua file INI sebagai sumbernya:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Catatan

Anda harus menginstal paket Microsoft.Extensions.Configuration.Ini NuGet untuk memiliki akses ke AddIniFile method.

Contoh file appsettings.ini dengan berbagai pengaturan konfigurasi berikut:

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Kode berikut menampilkan pengaturan konfigurasi sebelumnya dengan menulisnya ke jendela konsol:

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

Aplikasi akan menulis output sampel berikut:

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

Penyedia konfigurasi variabel lingkungan

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

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. Misalnya, pemisah : tidak didukung oleh Bash. Garis bawah ganda (__), yang didukung di semua platform, secara otomatis menggantikan pemisah apa pun : dalam variabel lingkungan.

Pertimbangkan kelas TransientFaultHandlingOptions

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Perintah berikut set mengatur kunci dan nilai lingkungan dari SecretKey dan TransientFaultHandlingOptions.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

Pengaturan lingkungan ini hanya diatur dalam proses yang diluncurkan dari jendela perintah tempat pengaturannya ditetapkan. Mereka tidak dibaca oleh aplikasi web yang diluncurkan dengan Visual Studio.

Dengan Visual Studio 2019 dan yang lebih baru, Anda dapat menentukan variabel lingkungan menggunakan dialog Luncurkan Profil .

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 SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Untuk menguji bahwa perintah sebelumnya menggantikan pengaturan apapun dalam 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.

Awalan

Untuk menentukan awalan untuk variabel lingkungan, panggil AddEnvironmentVariables dengan string:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Dalam kode sebelumnya:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") ditambahkan setelah penyedia konfigurasi default. Untuk contoh urutan penyedia konfigurasi, lihat penyedia konfigurasi XML.
• Variabel lingkungan yang ditetapkan dengan prefix CustomPrefix_ menggantikan penyedia konfigurasi default. Ini termasuk variabel lingkungan tanpa awalan.

Awalan dihapus saat pasangan kunci-nilai konfigurasi dibaca.

Konfigurasi default memuat variabel lingkungan dan argumen baris perintah yang diawali dengan DOTNET_. DOTNET_ Prefiks digunakan oleh .NET untuk host dan konfigurasi aplikasi, tetapi tidak untuk pengaturan pengguna.

Untuk informasi selengkapnya tentang konfigurasi host dan aplikasi, lihat Host Generik .NET.

Awalan string koneksi

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

Penting

Microsoft menyarankan agar Anda menggunakan alur autentikasi paling aman yang tersedia. Jika Anda menyambungkan ke Azure SQL, Identitas Terkelola untuk sumber daya Azure adalah metode autentikasi yang direkomendasikan.

Variabel lingkungan diatur dalam launchSettings.json

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

Pengaturan App Service Azure

Pada Azure App Service, pilih Tambahkan di halaman Pengaturan variabel lingkungan >. Pengaturan aplikasi Azure App Service:

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

Penyedia Konfigurasi baris perintah

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

• appsettings.json dan appsettings.Environment.file json.
• Rahasia aplikasi (Secret Manager) di Development lingkungan.
• Variabel lingkungan.

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

Dengan Visual Studio 2019 dan yang lebih baru, Anda dapat menentukan argumen baris perintah menggunakan dialog Luncurkan Profil .

Argumen baris perintah

Perintah berikut mengatur kunci dan nilai menggunakan =:

dotnet run SecretKey="Secret key from command line"

Perintah berikut mengatur kunci dan nilai menggunakan /:

dotnet run /SecretKey "Secret key set from forward slash"

Perintah berikut mengatur kunci dan nilai menggunakan --:

dotnet run --SecretKey "Secret key set from double hyphen"

Nilai kunci:

• Harus mengikuti =, atau kunci harus memiliki awalan -- atau / jika nilai setelah spasi.
• Tidak diperlukan jika = digunakan. Contohnya,SomeKey=.

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

Penyedia konfigurasi kunci per file

KeyPerFileConfigurationProvider menggunakan file direktori sebagai pasangan kunci-nilai konfigurasi. Kuncinya adalah nama file. Nilainya adalah 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((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    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:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Dalam kode sebelumnya, MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) menambahkan penyedia memori setelah penyedia konfigurasi default. Untuk contoh urutan penyedia konfigurasi, lihat penyedia konfigurasi XML.

Lihat juga

• Konfigurasi di .NET
• Host Umum .NET
• Menerapkan penyedia konfigurasi kustom