.NET'teki yapılandırma sağlayıcıları

.NET'te yapılandırma, yapılandırma sağlayıcılarıyla mümkündür. Çeşitli sağlayıcı türleri çeşitli yapılandırma kaynaklarına dayanır. Bu makalede tüm farklı yapılandırma sağlayıcıları ve bunlara karşılık gelen kaynaklar ayrıntılı olarak verilmiştir.

• Dosya yapılandırma sağlayıcı
• Ortam değişkeni yapılandırma sağlayıcısı
• Komut satırı yapılandırması sağlayıcı
• Dosya başına anahtar yapılandırma sağlayıcı
• Bellek yapılandırma sağlayıcı

Dosya yapılandırma sağlayıcı

FileConfigurationProvider dosya sisteminden yapılandırma yüklemek için temel sınıftır. Aşağıdaki yapılandırma sağlayıcıları FileConfigurationProvider öğesinden türemiştir:

• JSON yapılandırma sağlayıcısı
• XML yapılandırma sağlayıcı
• INI yapılandırma sağlayıcı

Anahtarlar büyük/küçük harfe duyarsızdır. Dosya konfigürasyon sağlayıcılarının tamamı, tek bir sağlayıcıda yinelenen anahtarlar bulunduğunda FormatException öğesini atar.

JSON yapılandırma sağlayıcısı

sınıfı bir JsonConfigurationProvider JSON dosyasından yapılandırma yükler. Microsoft.Extensions.Configuration.Json NuGet paketini yükleyin.

Aşırı yüklemeler şunları belirtebilir:

• Dosya isteğe bağlı mı.
• Dosya değişirse yapılandırmanın yeniden yüklenip yüklenmeyeceği.

Aşağıdaki kodu inceleyin:

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();

Yukarıdaki kod:

• yöntemine varsayılan olarak CreateApplicationBuilder(String[]) eklenen tüm mevcut yapılandırma sağlayıcılarını temizler.
• JSON yapılandırma sağlayıcısını, appsettings.json ve appsettings.Environment.json dosyalarını aşağıdaki seçeneklerle yüklemek üzere yapılandırır.
  • optional: true: Dosya isteğe bağlıdır.
  • reloadOnChange: true: Değişiklikler kaydedildiğinde dosya yeniden yüklenir.

Önemli

ile IConfigurationBuilder.Add yapılandırma sağlayıcıları eklenirken, eklenen yapılandırma sağlayıcısı listenin IConfigurationSource sonuna eklenir. Anahtarlar birden çok sağlayıcı tarafından bulunduğunda, anahtarı okuyan son sağlayıcı önceki sağlayıcıları geçersiz kılar.

Çeşitli yapılandırma ayarlarına sahip örnek bir appsettings.json dosyası aşağıda verilmiştir:

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

Örnekteki IConfigurationBuilder yapılandırma sağlayıcıları eklendikten sonra, nesnesini almak için IConfigurationBuilder.Build() öğesini çağırabilirsiniz. Yapılandırma kökü, yapılandırma hiyerarşisinin kökünü temsil eder. Yapılandırmadaki bölümler .NET nesnelerinin örneklerine bağlanabilir ve daha sonra bağımlılık enjeksiyonu yoluyla IOptions<TOptions> olarak sağlanabilir.

Not

JSON dosyasının Derleme Eylemi ve Çıkış Dizinine Kopyala özellikleri sırasıyla İçerik ve Daha yeniyse kopyala (veya Her zaman kopyala) olarak ayarlanmalıdır.

TransientFaultHandlingOptions Aşağıdaki gibi tanımlanan sınıfı göz önünde bulundurun:

namespace ConsoleJson.Example;

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

Aşağıdaki kod yapılandırma kökünü oluşturur, bir bölümü sınıf türüne TransientFaultHandlingOptions bağlar ve ilişkili değerleri konsol penceresine yazdırır:

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

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

Uygulama aşağıdaki örnek çıkışı yazar:

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

XML yapılandırma sağlayıcı

XmlConfigurationProvider sınıfı, çalışma zamanında bir XML dosyasından yapılandırmayı yükler. Microsoft.Extensions.Configuration.Xml NuGet paketini yükleyin.

Aşağıdaki kod, XML yapılandırma sağlayıcısını kullanarak XML dosyalarının yapılandırmasını gösterir.

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();

Yukarıdaki kod:

• yöntemine varsayılan olarak CreateApplicationBuilder(String[]) eklenen tüm mevcut yapılandırma sağlayıcılarını temizler.
• XML yapılandırma sağlayıcısını, appsettings.xml ve repeating-example.xml dosyalarını aşağıdaki seçeneklerle yükleyecek şekilde yapılandırır:
  • optional: true: Dosya isteğe bağlıdır.
  • reloadOnChange: true: Değişiklikler kaydedildiğinde dosya yeniden yüklenir.
• Ortam değişkenleri yapılandırma sağlayıcısını yapılandırıyor.
• Verilen args bağımsız değişkenler içeriyorsa komut satırı yapılandırma sağlayıcısını yapılandırır.

XML ayarları, Ortam değişkenleri yapılandırma sağlayıcısındaki ve Komut satırı yapılandırma sağlayıcısındakiayarlar tarafından geçersiz kılınabilir.

Çeşitli yapılandırma ayarlarına sahip örnek appsettings.xml dosyası aşağıda verilmiştir:

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

İpucu

WinForms uygulamalarında IConfiguration türünü kullanmak için Microsoft.Extensions.Configuration.Xml NuGet paketine bir referans ekleyin. örneğini oluşturun ve ve için zincir çağrıları yapın. Daha fazla bilgi için bkz . .NET Docs Sorunu #29679.

.NET 5 ve önceki sürümlerde, aynı öğe adını kullanan yinelenen öğeleri ayırt etmek için özniteliğini ekleyin name . .NET 6 ve sonraki sürümlerde, XML yapılandırma sağlayıcısı yinelenen öğeleri otomatik olarak dizine alır. Bu, anahtarda name "0" dizininin olmasını ve yalnızca bir öğe olmasını istemeniz dışında özniteliğini belirtmeniz gerekmediğini gösterir. (.NET 6 veya daha yeni bir sürüme yükseltiyorsanız, bu davranış değişikliğinden kaynaklanan bir kesmeyle karşılaşabilirsiniz. Daha fazla bilgi için bkz Yinelenen XML öğeleri dizin içerir.)

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

Aşağıdaki kod, önceki yapılandırma dosyasını okur, anahtarları ve değerleri görüntüler:

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

Uygulama aşağıdaki örnek çıkışı yazacak:

// 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

Nitelikler değerleri sağlamak için kullanılabilir:

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

Önceki yapılandırma dosyası, aşağıdaki anahtarları value ile yükler:

• key:attribute
• section:key:attribute

INI yapılandırma sağlayıcı

Bu IniConfigurationProvider sınıfı, çalışma zamanında bir INI dosyasından yapılandırma yükler.

Aşağıdaki kod tüm yapılandırma sağlayıcılarını temizler ve iki INI dosyasını kaynak olarak ekler IniConfigurationProvider :

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();

Not

Microsoft.Extensions.Configuration.Ini yöntemine erişebilmek için AddIniFile NuGet paketini yüklemeniz gerekir.

Çeşitli yapılandırma ayarlarına sahip örnek bir appsettings.ini dosyası aşağıda verilmiştir:

SecretKey="Secret key value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Aşağıdaki kod, önceki yapılandırma ayarlarını konsol penceresine yazarak görüntüler:

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

Uygulama aşağıdaki örnek çıkışı yazacak:

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

Ortam değişkeni yapılandırma sağlayıcısı

Varsayılan yapılandırmayı kullanarak, EnvironmentVariablesConfigurationProvider önce appsettings.json, appsettings.Environment.json ve Gizli dizi yöneticisi okuduktan sonra ortam değişkeni anahtar-değer çiftlerinden yapılandırma yükler. Bu nedenle, ortamdan okunan anahtar değerleri, appsettings.json, appsettings.Environment.json ve Gizli Yönetici'den okunan değerleri geçersiz kılar.

: Sınırlayıcı, tüm platformlarda ortam değişkeni hiyerarşik anahtarlarla çalışmaz. Örneğin, : sınırlayıcı Bash tarafından desteklenmez. Tüm platformlarda desteklenen çift alt çizgi ()__ ortam değişkenlerindeki sınırlayıcıların : yerini otomatik olarak alır.

TransientFaultHandlingOptions sınıfını düşünün.

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

Aşağıdaki set komutları, SecretKey ve TransientFaultHandlingOptions ortam anahtarlarını ve değerlerini ayarlar.

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

Bu ortam ayarları yalnızca ayarlandıkları komut penceresinden başlatılan işlemlerde ayarlanır. Visual Studio ile başlatılan web uygulamaları tarafından okunmuyorlar.

Visual Studio 2019 ve sonraki sürümlerle, Profilleri Başlat iletişim kutusunu kullanarak ortam değişkenlerini belirtebilirsiniz.

Windows'ta ortam anahtarlarını ve değerlerini ayarlamak için aşağıdaki setx komutları kullanılabilir. set öğesinin aksine setx ayarları kalıcıdır. /M değişkeni sistem ortamında ayarlar. /M anahtarı kullanılmazsa, bir kullanıcı ortamı değişkeni ayarlanır.

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Önceki komutların appsettings.json ve appsettings.Environment.json ayarlarının herhangi birini geçersiz kıldığını test etmek için:

• Visual Studio ile: Çıkın ve Visual Studio'yu yeniden başlatın.
• CLI ile: Yeni bir komut penceresi başlatın ve dotnet run girin.

Ön Ekler

Ortam değişkenleri için bir ön ek belirtmek için AddEnvironmentVariables bir dize ile çağırın.

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();

Önceki kodda:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") varsayılan yapılandırma sağlayıcılarından sonra eklenir. Yapılandırma sağlayıcılarını sıralama örneği için bkz . XML yapılandırma sağlayıcısı.
• Ön ek ile CustomPrefix_ ayarlanan ortam değişkenleri, varsayılan yapılandırma sağlayıcılarını geçersiz kılar. Bu, ön eki olmayan ortam değişkenlerini içerir.

Önek, yapılandırma anahtar-değer çiftleri okunduğunda kaldırılır.

Varsayılan yapılandırma, DOTNET_ ile ön eklenmiş ortam değişkenlerini ve komut satırı bağımsız değişkenlerini yükler. .NET tarafından konak ve uygulama yapılandırması için DOTNET_ öneki kullanılır, ancak kullanıcı yapılandırması için kullanılmaz.

Ana bilgisayar ve uygulama yapılandırması hakkında daha fazla bilgi için, bkz. .NET Genel Ana Bilgisayarı.

Bağlantı dizesi ön ekleri

Yapılandırma API’si, dört bağlantı dizesi ortam değişkeni için özel işleme kurallarına sahiptir. Bu bağlantı dizeleri, uygulama ortamı için Azure bağlantı dizelerinin yapılandırılmasında yer alır. Tabloda gösterilen ön eklere sahip ortam değişkenleri, varsayılan yapılandırmayla veya ön ek sağlanmadığında AddEnvironmentVariables uygulamaya yüklenir.

Bağlantı dizesi ön eki	Sağlayıcı
CUSTOMCONNSTR_	Özel sağlayıcı
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL Veritabanı
SQLCONNSTR_	SQL Server

Bir ortam değişkeni keşfedildiğinde ve tabloda gösterilen dört ön ekten herhangi biriyle konfigürasyona yüklendiğinde:

• Yapılandırma anahtarı, ortam değişkeni öneki kaldırılarak ve bir yapılandırma anahtarı bölümü (ConnectionStrings) eklenerek oluşturulur.
• Veritabanı bağlantı sağlayıcısını temsil eden yeni bir yapılandırma anahtar-değer çifti oluşturulur (belirtilen bir sağlayıcısı olmayan CUSTOMCONNSTR_ hariç).

Ortam değişkeni anahtarı	Dönüştürülmüş yapılandırma anahtarı	Sağlayıcı konfigürasyon kaydı
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Yapılandırma girdisi oluşturulmadı.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Anahtar: ConnectionStrings:{KEY}_ProviderName: Değer: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Anahtar: ConnectionStrings:{KEY}_ProviderName: Değer: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Anahtar: ConnectionStrings:{KEY}_ProviderName: Değer: System.Data.SqlClient

Önemli

Microsoft, kullanılabilir en güvenli kimlik doğrulama akışını kullanmanızı önerir. Azure SQL'e bağlanıyorsanız önerilen kimlik doğrulama yöntemi Azure kaynakları için Yönetilen Kimlikler'dir.

launchSettings.json'de ayarlanan ortam değişkenleri

launchSettings.json'de ayarlanan ortam değişkenleri, sistem ortamında ayarlananları geçersiz kılar.

Azure Uygulama Hizmeti ayarları

Azure App Serviceüzerinde, Ayarlar> sayfasında Ekle seçeneğini seçin. Azure App Service uygulama ayarları şunlardır:

• Bekleme sırasında şifrelenir ve şifrelenmiş bir kanal üzerinden iletilir.
• Ortam değişkenleri olarak açık hale getirilir.

Komut satırı yapılandırma sağlayıcısı

Varsayılan yapılandırmayı kullanarak, CommandLineConfigurationProvider aşağıdaki yapılandırma kaynaklarından sonra komut satırı bağımsız değişkenlerinin anahtar-değer çiftlerinden yapılandırmayı yükler.

• appsettings.json ve uygulama ayarları.Environment.json dosyaları.
• Ortamdaki Development uygulama gizli anahtarları (Gizli Yönetici).
• Ortam değişkenleri.

Varsayılan olarak, komut satırında ayarlanan yapılandırma değerleri diğer tüm yapılandırma sağlayıcılarıyla ayarlanan yapılandırma değerlerini geçersiz kılar.

Visual Studio 2019 ve sonraki sürümlerle, Profilleri Başlat iletişim kutusunu kullanarak komut satırı bağımsız değişkenlerini belirtebilirsiniz.

Komut satırı bağımsız değişkenleri

Aşağıdaki komut, = kullanarak anahtarları ve değerleri ayarlar:

dotnet run SecretKey="Secret key from command line"

Aşağıdaki komut, / kullanarak anahtarları ve değerleri ayarlar:

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

Aşağıdaki komut, -- kullanarak anahtarları ve değerleri ayarlar:

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

Anahtar değer:

• = öğesini izlemeli veya değer bir boşluktan sonra geldiğinde anahtarın ön eki -- veya / olmalıdır.
• = kullanılırsa gerekli değildir. Örneğin, SomeKey=.

Aynı komut içinde, = kullanan komut satırı bağımsız değişken anahtar-değer çiftlerini, boşluk kullanan anahtar-değer çiftleriyle karıştırmayın.

Dosya başına anahtar yapılandırma sağlayıcı

KeyPerFileConfigurationProvider, bir dizinin dosyalarını yapılandırma anahtar-değer çiftleri olarak kullanır. Anahtar, dosya adıdır. Değer, dosyanın içeriğidir. Dosya başına anahtar yapılandırma sağlayıcı, Docker barındırma senaryolarında kullanılır.

Dosya başına anahtar yapılandırmasını etkinleştirmek için bir AddKeyPerFile örneğinde ConfigurationBuilder genişletme yöntemini çağırın. Dosyalar için directoryPath mutlak bir yol olmalıdır.

Aşırı yükler şunları belirtmeye izin verir:

• Kaynağı yapılandıran bir Action<KeyPerFileConfigurationSource> temsilcisi.
• Dizinin isteğe bağlı olup olmadığı ve dizinin yolu.

Çift alt çizgi (__), dosya adlarında yapılandırma anahtarı sınırlayıcı olarak kullanılır. Örneğin, Logging__LogLevel__System dosya adı, Logging:LogLevel:System yapılandırma anahtarını üretir.

Uygulamanın yapılandırmasını belirtmek için ana bilgisayarı oluştururken ConfigureAppConfiguration çağırın:

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

Bellek yapılandırma sağlayıcı

MemoryConfigurationProvider, yapılandırma anahtar-değer çiftleri olarak bellek içi bir koleksiyon kullanır.

Aşağıdaki kod, yapılandırma sistemine bir bellek koleksiyonu ekler:

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();

Yukarıdaki kodda, MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) varsayılan yapılandırma sağlayıcılarından sonra bellek sağlayıcısını ekler. Yapılandırma sağlayıcılarını sıralama örneği için bkz . XML yapılandırma sağlayıcısı.

Ayrıca bkz.

• .NET'te yapılandırma
• .NET Genel Host
• Özel yapılandırma sağlayıcısı uygulama