.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 duyarlı değildir. Tüm dosya yapılandırma sağlayıcıları, tek bir sağlayıcıda FormatException yinelenen anahtarlar bulunduğunda öğesini oluşturur.

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 normal mi değil mi.
• 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 uygulama ayarlarını yüklenecek şekilde yapılandırıyor..Environmentjson dosyaları ve aşağıdaki seçenekler:
  • optional: true: Dosya isteğe bağlıdır.
  • reloadOnChange: true: Değişiklikler kaydedildiğinde dosya yeniden yüklenir.

Önemli

ile IConfigurationBuilder.Addyapılandırma sağlayıcıları eklenirken, eklenen yapılandırma sağlayıcısı listenin sonuna IConfigurationSource 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"
        }
    }
}

Örnekten IConfigurationBuilder yapılandırma sağlayıcıları eklendikten sonra nesnesini almak IConfigurationRoot için öğesini çağırabilirsinizIConfigurationBuilder.Build(). 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 ekleme yoluyla sağlanabilir IOptions<TOptions> .

Not

JSON dosyasının Derleme Eylemi ve Çıkış Dizinine Kopyala özellikleri sırasıyla İçerik ve 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ı

sınıfı, XmlConfigurationProvider çalışma zamanında bir XML dosyasından yapılandırma 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ı aşağıdaki seçeneklerle appsettings.xml ve repeating-example.xml dosyalarını yüklenecek şekilde yapılandırılı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ılı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 türünü kullanmak IConfiguration için Microsoft.Extensions.Configuration.Xml NuGet paketine bir başvuru ekleyin. ve Build()için ve zincir çağrılarının ConfigurationBuilder örneğini AddXmlFile oluşturma. 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 sonraki bir sürüme yükseltiyorsanız, davranışta bu değişiklikten 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ı

sınıfı, IniConfigurationProvider çalışma zamanında bir INI dosyasından yapılandırma yükler. Microsoft.Extensions.Configuration.Ini NuGet paketini yükleyin.

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

Ç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ı EnvironmentVariablesConfigurationProvider kullanarak, appsettings.json, uygulama ayarları okundıktan sonra ortam değişkeni anahtar-değer çiftlerinden yapılandırma yüklenir.Environment. json ve Gizli dizi yöneticisi. Bu nedenle, ortamdan okunan anahtar değerleri, appsettings.json, uygulama ayarları..Environment. json ve Gizli dizi yöneticisi.

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

Sınıfını TransientFaultHandlingOptions göz önünde bulundurun:

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

Aşağıdaki set komutlar ve ortam anahtarlarını ve değerlerini SecretKeyTransientFaultHandlingOptionsayarlar.

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 tüm appsettings.json ve uygulama ayarlarını geçersiz kıldığını test etmek için.Environment. json ayarları:

• 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 dize ile çağrısında AddEnvironmentVariables bulunur:

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.

Ön eki, yapılandırma anahtar-değer çiftleri okunduğunda çıkarılır.

Varsayılan yapılandırma, ön ekli DOTNET_ortam değişkenlerini ve komut satırı bağımsız değişkenlerini yükler. Ön DOTNET_ ek, .NET tarafından konak ve uygulama yapılandırması için 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ğlandığında AddEnvironmentVariablesuygulamaya yüklenir.

Bağlantı dizesi ön eki	Provider
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ı yapılandırması girdisi
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

Başlatmada ayarlanan ortam değişkenleri Ayarlar.json

Başlatmada ayarlanan ortam değişkenleri Ayarlar.json sistem ortamında ayarlananları geçersiz kılar.

hizmet ayarlarını Azure Uygulaması

Azure Uygulaması Hizmeti'nin Ayarlar> Configuration sayfasında Yeni uygulama ayarı'nı 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 kullanıma sunulur.

Komut satırı yapılandırması sağlayıcı

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

• appsettings.json ve uygulama ayarları.Environment.json dosyaları.
• Ortamdaki Development uygulama gizli dizileri (Gizli Dizi Yöneticisi).
• 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şkeni 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 ConfigurationBuilder örneğinde AddKeyPerFile 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
• Genel Ana Bilgisayar
• Özel yapılandırma sağlayıcısı uygulama