.NET'te 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 yapılandırma kaynaklarına bağlı olan çeşitli türlerde sağlayıcılar vardır. Bu makalede, tüm farklı yapılandırma sağlayıcıları ve ilgili kaynakları ayrıntılı olarak ve ayrıntılı olarak ve ayrıntılı olarak sağlanmaktadır.

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

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

FileConfigurationProvider , dosya sisteminden yapılandırma yüklemenin temel sınıfıdır. Aşağıdaki yapılandırma sağlayıcıları, 'den FileConfigurationProvider türetmektedir:

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

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

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

Aşırı yüklemeler şunları belirterek şunları ifade ediyor olabilir:

• Dosyanın isteğe bağlı olup olmadığı
• Dosya değişirse yapılandırmanın yeniden yükleniyor olup olmadığı

Aşağıdaki kodu inceleyin:

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

namespace ConsoleJson.Example;

class Program
{
    static async Task Main(string[] args)
    {
        using IHost host = CreateHostBuilder(args).Build();

        // Application code should start here.

        await host.RunAsync();
    }

    static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, configuration) =>
            {
                configuration.Sources.Clear();

                IHostEnvironment env = hostingContext.HostingEnvironment;

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

                IConfigurationRoot configurationRoot = configuration.Build();

                TransientFaultHandlingOptions options = new();
                configurationRoot.GetSection(nameof(TransientFaultHandlingOptions))
                                 .Bind(options);

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

Yukarıdaki kod:

• yöntemine varsayılan olarak eklenen tüm mevcut yapılandırma sağlayıcılarını CreateDefaultBuilder(String[]) temizler.
• JSON yapılandırma sağlayıcısını appsettings.json ve appsettings 'i yük olacak şekilde yapılandırıyor. Environment aşağıdaki seçeneklere sahip json dosyaları:
  • optional: true: Dosya isteğe bağlıdır.
  • reloadOnChange: true: Değişiklikler kaydedilebilirse dosya yeniden yüklenir.

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

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

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

IConfigurationBuilderÖrnekten, yapılandırma sağlayıcıları eklendikten sonra nesnesini almak IConfigurationBuilder.Build() için IConfigurationRoot ç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ğlı olabilir ve daha sonra bağımlılık ekleme IOptions<TOptions> yoluyla sağlanmalıdır.

Aşağıdaki gibi TransientFaultHandlingOptions tanımlanan sınıfı düşünün:

namespace ConsoleJson.Example;

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

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

IConfigurationRoot configurationRoot = configuration.Build();

TransientFaultHandlingOptions options = new();
configurationRoot.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ı

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

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

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

namespace ConsoleXml.Example;

class Program
{
    static async Task Main(string[] args)
    {
        using IHost host = CreateHostBuilder(args).Build();

        // Application code should start here.

        await host.RunAsync();
    }

    static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, configuration) =>
            {
                configuration.Sources.Clear();

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

                configuration.AddEnvironmentVariables();

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

Yukarıdaki kod:

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

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

Çeşitli yapılandırma appsettings.xml bir dosya örneği aşağıdaki gibidir:

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

.NET 5 ve önceki sürümlerde, aynı öğe adını kullanan yinelenen öğeleri ayırt name etmek için özniteliğini ekleyin. .NET 6 ve sonraki sürümlerde XML yapılandırma sağlayıcısı yinelenen öğeleri otomatik olarak dizinler. Bu, anahtarda "0" dizinini ve yalnızca bir öğenin yer almak istemesi dışında özniteliği belirtmeniz name gerek yoktur.

<?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 ve anahtarları ve değerleri görüntüler:

IConfigurationRoot configurationRoot = configuration.Build();

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ışı yazar:

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

Öznitelikler, 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ı ile aşağıdaki anahtarları value yükler:

• key:attribute
• section:key:attribute

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

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

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

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

namespace ConsoleIni.Example;

class Program
{
    static async Task Main(string[] args)
    {
        using IHost host = CreateHostBuilder(args).Build();

        // Application code should start here.

        await host.RunAsync();
    }

    static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, configuration) =>
            {
                configuration.Sources.Clear();

                IHostEnvironment env = hostingContext.HostingEnvironment;

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

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

Çeşitli yapılandırma appsettings.ini bir dosya örneği aşağıdaki gibidir:

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
    configuration.Build().AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

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

// 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 appsettings.json , appsettings okunduktan sonra ortam değişkeni anahtar-değer çiftlerinden yapılandırmayı yükler. Environment .json ve Gizli Gizli Yönetici. Bu nedenle, ortamdan okunan anahtar değerleri appsettings.json, appsettings'den okunan değerleri geçersiz kılar. Environment .json ve Gizli Gizli Yönetici.

Ayırıcı, : tüm platformlarda ortam değişkeni hiyerarşik anahtarlarla birlikte çalışmaz. Çift alt çizgi ( ) otomatik olarak bir __ ile değiştirilir ve tüm : platformlar tarafından desteklenir. Örneğin, : ayıracı Bash tarafından desteklanmaz,ancak __ bu şekildedir.

Aşağıdaki set komutlar:

• Yukarıdaki örnekteki ortam anahtarlarını ve değerlerini Windows.
• Ayarları varsayılan değerlerinden değiştirerek test edin. Komutun dotnet run proje dizininde çalışması gerekir.

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

dotnet run

Yukarıdaki ortam ayarları:

• Yalnızca ayarlandıkları komut penceresinden başlatılan işlemlerde ayarlanır.
• Bu, uygulamayla başlatılan web uygulamaları tarafından Visual Studio.

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

Aşağıdaki setx komutları, ortam anahtarlarını ve değerlerini Windows. 'den set setx farklı olarak ayarlar kalıcıdır. /M , sistem ortamında değişkeni ayarlar. Anahtar /M 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

dotnet run

Yukarıdaki komutların appsettings.json ve appsettings'i geçersiz kılarak test etmek için. Environment .json:

• Şu Visual Studio: Çıkış ve yeniden başlatma Visual Studio.
• CLI ile: Yeni bir komut penceresi başlatıp dotnet run girin.

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

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

namespace ConsoleEnvironment.Example;

class Program
{
    static async Task Main(string[] args)
    {
        using IHost host = CreateHostBuilder(args).Build();

        // Application code should start here.

        await host.RunAsync();
    }

    static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, configuration) =>
                configuration.AddEnvironmentVariables(
                    prefix: "CustomPrefix_"));
}

Yukarıdaki 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 ayarlanmış ortam CustomPrefix_ değişkenleri varsayılan yapılandırma sağlayıcılarını geçersiz kılar. Bu, ön ek olmadan ortam değişkenlerini içerir.

Yapılandırma anahtar-değer çiftleri okunurken ön ek çıkarılmış olur.

Aşağıdaki komutlar özel ön eki test ediyor:

set CustomPrefix_SecretKey="Secret key with CustomPrefix_ environment"
set CustomPrefix_TransientFaultHandlingOptions__Enabled=true
set CustomPrefix_TransientFaultHandlingOptions__AutoRetryDelay=00:00:21

dotnet run

Varsayılan yapılandırma, ortam değişkenlerini ve ön ekli komut satırı bağımsız değişkenlerini DOTNET_ 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ılamaz.

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

Yeni Azure App Servicesayfasında Yeni uygulama ayarı'Ayarlar > seçin. Azure App Service ayarları şu şekildedir:

• Rest 'de şifrelenir ve şifreli bir kanal üzerinden iletilir.
• Ortam değişkenleri olarak sunulur.

Bağlantı dizesi önekleri

Yapılandırma API 'sinin dört bağlantı dizesi ortam değişkeni için özel işleme kuralları vardır. Bu bağlantı dizeleri, uygulama ortamı için Azure bağlantı dizelerini yapılandırmaya dahil edilir. Tabloda gösterilen öneklerle ortam değişkenleri, varsayılan yapılandırmayla veya uygulamasına hiçbir önek sağlanmadığında uygulamaya yüklenir AddEnvironmentVariables .

Bir ortam değişkeni keşfedildiğinde ve tabloda gösterilen dört önekle yapılandırmaya yüklendiğinde:

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

LaunchSettings. JSON içinde ayarlanan ortam değişkenleri

Launchsettings. JSON dosyasında ayarlanan ortam değişkenleri, Sistem ortamındaki kümeyi geçersiz kılar.

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şkeninden anahtar-değer çiftlerinden yapılandırma yükler:

• appSettings. JSON ve appSettings. Environment . JSON dosyaları.
• Ortamdaki uygulama gizli dizileri (gizli yönetici) Development .
• Ortam değişkenleri.

Varsayılan olarak, komut satırı üzerinde 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 sürüm 16,10 preview 4 ve üzeri sürümlerde, komut satırı bağımsız değişkenlerini başlatma profilleri iletişim kutusunu kullanarak 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ğeri:

• =' İ izlemelidir, ya da anahtarın bir -- / boşluk izleyen değeri veya öneki olmalıdır.
• Kullanılıyorsa gerekli değildir = . Örneğin, SomeKey=.

Aynı komut içinde, = bir boşluk kullanan anahtar-değer çiftleri ile birlikte kullanılan komut satırı bağımsız değişkeni anahtar-değer çiftlerini karıştırmayın.

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

, KeyPerFileConfigurationProvider Dizin 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ısı Docker barındırma senaryolarında kullanılır.

Dosya başına anahtar yapılandırmasını etkinleştirmek için, AddKeyPerFile bir örneğinde genişletme yöntemini çağırın ConfigurationBuilder . directoryPathDosyaların mutlak bir yol olması gerekir.

Aşırı yüklemeler belirtmeye izin ver:

• Action<KeyPerFileConfigurationSource>Kaynağı yapılandıran bir temsilci.
• Dizinin isteğe bağlı olup olmadığını ve dizinin yolunu belirtir.

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

ConfigureAppConfigurationUygulamanın yapılandırmasını belirtmek için Konağı oluştururken ç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ısı

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

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

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

namespace ConsoleMemory.Example;

class Program
{
    static async Task Main(string[] args)
    {
        using IHost host = CreateHostBuilder(args).Build();

        // Application code should start here.

        await host.RunAsync();
    }

    static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((_, configuration) =>
                configuration.AddInMemoryCollection(
                    new Dictionary<string, string>
                    {
                        ["SecretKey"] = "Dictionary MyKey Value",
                        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
                        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
                        ["Logging:LogLevel:Default"] = "Warning"
                    }));
}

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ıyı ekler. Yapılandırma sağlayıcılarını sipariş eden bir örnek için bkz. XML yapılandırma sağlayıcısı.

Ayrıca bkz.

• .NET 'teki yapılandırma
• .NET genel ana bilgisayar
• Özel yapılandırma sağlayıcısı uygulama