Konfigurasi di .NET

Konfigurasi di .NET 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
• Penyedia pihak ketiga

Konsep dan abstraksi

Mengingat satu atau beberapa sumber konfigurasi, jenisnya IConfiguration menyediakan tampilan terpadu dari data konfigurasi. Konfigurasi bersifat baca-saja, dan pola konfigurasi tidak dirancang agar dapat ditulis secara terprogram. Antarmuka IConfiguration adalah representasi tunggal dari semua sumber konfigurasi, seperti yang ditunjukkan dalam diagram berikut:

Mengonfigurasi aplikasi konsol

Aplikasi konsol .NET yang dibuat menggunakan templat perintah baru dotnet atau Visual Studio secara default tidak mengekspos kemampuan konfigurasi. Untuk menambahkan konfigurasi di aplikasi konsol .NET baru, tambahkan referensi paket ke Microsoft.Extensions.Configuration. Paket ini adalah fondasi untuk konfigurasi di aplikasi .NET. Ini menyediakan ConfigurationBuilder jenis dan terkait.

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

Kode sebelumnya:

• Membuat instans baru ConfigurationBuilder .
• Menambahkan koleksi dalam memori pasangan kunci-nilai ke penyusun konfigurasi.
• Memanggil metode untuk membuat IConfiguration instansBuild().
• Menulis nilai SomeKey kunci ke konsol.

Meskipun contoh ini menggunakan konfigurasi dalam memori, ada banyak penyedia konfigurasi yang tersedia, mengekspos fungsionalitas untuk berbasis file, variabel lingkungan, argumen baris perintah, dan sumber konfigurasi lainnya. Untuk informasi selengkapnya, lihat Penyedia konfigurasi di .NET.

Pendekatan hosting alternatif

Umumnya, aplikasi Anda akan melakukan lebih dari sekadar membaca konfigurasi. Mereka kemungkinan akan menggunakan injeksi dependensi, pengelogan, dan layanan lainnya. Pendekatan .NET Generic Host direkomendasikan untuk aplikasi yang menggunakan layanan ini. Sebagai gantinya, pertimbangkan untuk menambahkan referensi paket ke Microsoft.Extensions.Hosting. Ubah file Program.cs agar sesuai dengan kode berikut:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Metode ini Host.CreateApplicationBuilder(String[]) 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 menggunakan Penyedia konfigurasi Variabel Lingkungan.
3. Rahasia pengguna saat aplikasi berjalan di lingkungan Development.
4. appsettings.json menggunakan penyedia konfigurasi JSON.
5. appsettings.Environment. json menggunakan penyedia konfigurasi JSON. Misalnya, appsettings.Produksi.json dan appsettings.Pengembangan.json.
6. ChainedConfigurationProvider : Menambahkan IConfiguration yang sudah ada sebagai sumber.

Menambahkan penyedia konfigurasi akan mengambil alih nilai konfigurasi sebelumnya. Misalnya, penyedia konfigurasi Baris perintah mengambil alih semua nilai dari penyedia lain karena ditambahkan terakhir. Jika SomeKey diatur di appsettings.json dan lingkungan, nilai lingkungan digunakan karena ditambahkan setelah appsettings.json.

Pengikatan

Salah satu keuntungan utama menggunakan abstraksi konfigurasi .NET adalah kemampuan untuk mengikat nilai konfigurasi ke instans objek .NET. Misalnya, penyedia konfigurasi JSON dapat digunakan untuk memetakan file appsettings.json ke objek .NET dan digunakan dengan injeksi dependensi. Ini memungkinkan pola opsi, yang menggunakan kelas untuk menyediakan akses yang sangat diketik ke grup pengaturan terkait. Konfigurasi .NET menyediakan berbagai abstraksi. Pertimbangkan antarmuka berikut:

• IConfiguration: Mewakili sekumpulan properti konfigurasi aplikasi kunci/nilai.
• IConfigurationRoot: Mewakili akar IConfiguration hierarki.
• IConfigurationSection: Mewakili bagian dari nilai konfigurasi aplikasi.

Abstraksi ini agnostik untuk penyedia konfigurasi yang mendasar (IConfigurationProvider). Dengan kata lain, Anda dapat menggunakan IConfiguration instans untuk mengakses nilai konfigurasi apa pun dari beberapa penyedia.

Pengikat dapat menggunakan pendekatan yang berbeda untuk memproses nilai konfigurasi:

• Deserialisasi langsung (menggunakan konverter bawaan) untuk jenis primitif.
• TypeConverter untuk jenis kompleks ketika jenis memilikinya.
• Pantulan untuk jenis kompleks yang memiliki properti.

Hierarki pengikatan

Nilai konfigurasi dapat berisi data hierarkis. Objek hierarkis diwakili dengan penggunaan pemisah : dalam kunci konfigurasi. Untuk mengakses nilai konfigurasi, gunakan : karakter untuk memisahkan hierarki. Misalnya, pertimbangkan nilai konfigurasi berikut:

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

Tabel berikut ini mewakili contoh kunci dan nilai yang sesuai untuk contoh JSON sebelumnya:

Contoh dasar

Untuk mengakses nilai konfigurasi dalam bentuk dasarnya, tanpa bantuan pendekatan host generik, gunakan jenisnya ConfigurationBuilder secara langsung.

Pertimbangkan proyek C# berikut:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="8.0.2" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </ItemGroup>

</Project>

File proyek sebelumnya mereferensikan beberapa paket NuGet konfigurasi:

• Microsoft.Extensions.Configuration.Binder: Fungsionalitas untuk mengikat objek ke data di penyedia konfigurasi untuk Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.Json: Implementasi penyedia konfigurasi JSON untuk Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.EnvironmentVariables: Implementasi penyedia konfigurasi variabel lingkungan untuk Microsoft.Extensions.Configuration.

Pertimbangkan contoh file appsettings.json :

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

Sekarang, mengingat file JSON ini, berikut adalah contoh pola konsumsi menggunakan penyusun konfigurasi secara langsung:

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

Kode C# sebelumnya:

• Membuat instans ConfigurationBuilder.
• Menambahkan file yang "appsettings.json" akan dikenali oleh penyedia konfigurasi JSON.
• Menambahkan variabel lingkungan sebagaimana dikenali oleh penyedia konfigurasi Variabel Lingkungan.
• Mendapatkan bagian yang diperlukan "Settings" dan instans yang Settings sesuai dengan menggunakan config instans.

Objek Settings dibentuk sebagai berikut:

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Contoh dasar dengan hosting

Untuk mengakses IConfiguration nilai, Anda dapat mengandalkan Microsoft.Extensions.Hosting kembali paket NuGet. Buat aplikasi konsol baru, dan tempelkan konten file proyek berikut ke dalamnya:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="8.0.2" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>

</Project>

File proyek sebelumnya mendefinisikan bahwa:

• Aplikasi ini dapat dieksekusi.
• File appsettings.json akan disalin ke direktori output saat proyek dikompilasi.
• Microsoft.Extensions.Hosting Referensi paket NuGet ditambahkan.

Tambahkan file appsettings.json di akar proyek dengan konten berikut:

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Ganti konten file Program.cs dengan kode C# berikut:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

Saat Anda menjalankan aplikasi ini, Host.CreateApplicationBuilder menentukan perilaku untuk menemukan konfigurasi JSON dan mengeksposnya melalui IConfiguration instans. host Dari instans, Anda dapat meminta instans kepada IConfiguration penyedia layanan lalu meminta nilainya.

Contoh dasar dengan hosting dan menggunakan API pengindeks

Pertimbangkan konten file appsettings.json yang sama dari contoh sebelumnya:

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Ganti konten file Program.cs dengan kode C# berikut:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Nilai diakses menggunakan API pengindeks di mana setiap kunci adalah string, dan nilainya adalah string. Konfigurasi mendukung properti, objek, array, dan kamus.

Penyedia konfigurasi

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

Untuk informasi selengkapnya tentang berbagai penyedia konfigurasi, lihat Penyedia konfigurasi di .NET.

Lihat juga

• Penyedia konfigurasi di .NET
• Menerapkan penyedia konfigurasi kustom
• Bug konfigurasi harus dibuat di repositori github.com/dotnet/runtime
• Konfigurasi di ASP.NET Core