Poskytovatelé konfigurace v .NET

Konfigurace v .NET je možná u zprostředkovatelů konfigurace. Existuje několik typů poskytovatelů, kteří spoléhají na různé zdroje konfigurace. Tento článek podrobně popisuje všechny různé zprostředkovatele konfigurace a jejich odpovídající zdroje.

• Poskytovatel konfigurace souborů
• Zprostředkovatel konfigurace proměnných prostředí
• Poskytovatel konfigurace příkazového řádku
• Poskytovatel konfigurace klíče na soubor
• Poskytovatel konfigurace paměti

Poskytovatel konfigurace souborů

FileConfigurationProvider je základní třída pro načítání konfigurace ze systému souborů. Následující poskytovatelé konfigurace jsou odvozeni z FileConfigurationProvider :

• Poskytovatel konfigurace JSON
• Poskytovatel konfigurace XML
• Zprostředkovatel konfigurace INI

Poskytovatel konfigurace JSON

Třída JsonConfigurationProvider načte konfiguraci ze souboru JSON. Nainstalujte Microsoft.Extensions.Configuration.Json NuGet balíček.

Přetížení mohou zadat:

• Jestli je soubor volitelný
• Jestli se konfigurace znovu načte, pokud se soubor změní

Vezměme si následující kód:

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

Předchozí kód:

• Vymaže všechny existující zprostředkovatele konfigurace, které byly přidány ve výchozím nastavení v CreateDefaultBuilder(String[]) metodě .
• Nakonfiguruje zprostředkovatele konfigurace JSON tak, aby načítá soubory appsettings.json a appsettings Environment . soubory JSON s následujícími možnostmi:
  • optional: true: Soubor je volitelný.
  • reloadOnChange: true: Soubor se při uložení změn znovu načte.

Nastavení JSON se přepíše nastavením ve zprostředkovateli konfigurace proměnných prostředí a zprostředkovateli konfigurace příkazového řádku.

Následuje příklad souboru appsettings.json s různým nastavením konfigurace:

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

Po přidání zprostředkovatelů konfigurace můžete z instance IConfigurationBuilder zavolat a získat objekt IConfigurationBuilder.Build() IConfigurationRoot . Kořen konfigurace představuje kořen hierarchie konfigurace. Oddíly z konfigurace mohou být vázány na instance objektů .NET a později poskytované prostřednictvím IOptions<TOptions> injektáže závislostí.

Vezměte TransientFaultHandlingOptions v úvahu třídu definovanou takto:

namespace ConsoleJson.Example;

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

Následující kód sestaví kořen konfigurace, vytvoří vazbu oddílu na typ třídy a vytiskne vázané TransientFaultHandlingOptions hodnoty do okna konzoly:

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

Aplikace by napsala následující ukázkový výstup:

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

Poskytovatel konfigurace XML

Třída XmlConfigurationProvider načte konfiguraci ze souboru XML za běhu. Nainstalujte Microsoft.Extensions.Configuration.Xml NuGet balíček.

Následující kód ukazuje konfiguraci souborů XML pomocí zprostředkovatele konfigurace XML.

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

Předchozí kód:

• Vymaže všechny existující zprostředkovatele konfigurace, které byly přidány ve výchozím nastavení v CreateDefaultBuilder(String[]) metodě .
• Konfiguruje zprostředkovatele konfigurace XML pro načtení appsettings.xml a repeating-example.xml souborů s následujícími možnostmi:
  • optional: true: Soubor je volitelný.
  • reloadOnChange: true: Soubor se při uložení změn znovu načte.
• Nakonfiguruje zprostředkovatele konfigurace proměnných prostředí.
• Nakonfiguruje zprostředkovatele konfigurace příkazového řádku, pokud daný args objekt obsahuje argumenty.

Nastavení XML se přepíše nastavením ve zprostředkovateli konfigurace proměnných prostředí a zprostředkovateli konfigurace příkazového řádku.

Následuje příklad appsettings.xml s různými nastaveními konfigurace:

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

V rozhraní .NET 5 a starších verzích přidejte atribut , který rozlišuje opakující se prvky, name které používají stejný název elementu. V rozhraní .NET 6 a novějších verzích zprostředkovatel konfigurace XML automaticky indexuje opakující se prvky. To znamená, že atribut nemusíte zazadat, s výjimkou případu, kdy chcete index "0" v klíči a existuje pouze name jeden prvek.

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

Následující kód přečte předchozí konfigurační soubor a zobrazí klíče a hodnoty:

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

Aplikace by napsala následující ukázkový výstup:

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

Atributy lze použít k poskytování hodnot:

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

Předchozí konfigurační soubor načte následující klíče pomocí value :

• key:attribute
• section:key:attribute

Zprostředkovatel konfigurace INI

Třída IniConfigurationProvider načte konfiguraci ze souboru INI za běhu. Nainstalujte Microsoft.Extensions.Configuration.Ini NuGet balíček.

Následující kód vymaže všechny zprostředkovatele konfigurace a přidá jako zdroj dva soubory IniConfigurationProvider INI:

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

Následuje příklad appsettings.ini s různými nastaveními konfigurace:

SecretKey="Secret key value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Následující kód zobrazí předchozí nastavení konfigurace tak, že je zapisuje do okna konzoly:

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

Aplikace by napsala následující ukázkový výstup:

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

Zprostředkovatel konfigurace proměnných prostředí

Při použití výchozí konfigurace načte konfigurace z párů klíč-hodnota proměnné prostředí po přečtení EnvironmentVariablesConfigurationProvider souboru appsettings.json, appsettings. Environment .json a Secret Manager. Proto hodnoty klíče přečtené z prostředí přepíší hodnoty přečtené z appsettings.json a appsettings. Environment .json a Secret Manager.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Dvojité podtržítko ( ) je automaticky nahrazeno a je __ : podporováno všemi platformami. Bash například : oddělovač nepodporuje, ale __ je.

Následující set příkazy:

• Nastavte klíče prostředí a hodnoty předchozího příkladu na Windows.
• Otestujte nastavení tak, že je změníte z výchozích hodnot. Příkaz dotnet run se musí spustit v adresáři projektu.

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

dotnet run

Předchozí nastavení prostředí:

• Jsou nastavené jenom v procesech spuštěných z příkazového okna, ve které byly nastaveny.
• Webové aplikace spuštěné s tímto Visual Studio.

V Visual Studio 2019 verze 16.10 Preview 4 a novější můžete zadat proměnné prostředí pomocí dialogového okna Spouštěcí profily.

Následující příkazy setx lze použít k nastavení klíčů a hodnot prostředí v Windows. Na set rozdíl od nastavení jsou nastavení setx zachována. /M nastaví proměnnou v systémovém prostředí. Pokud /M se přepínač nepouží, nastaví se proměnná uživatelského prostředí.

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

dotnet run

Pokud chcete otestovat, že předchozí příkazy přepíší appsettings.json a appsettings. Environment .json:

• Pomocí Visual Studio: Ukončete a restartujte Visual Studio.
• Pomocí rozhraní příkazového řádku: Spusťte nové příkazové okno a zadejte dotnet run .

Volání AddEnvironmentVariables s řetězcem pro zadání předpony pro proměnné prostředí:

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

V předchozím kódu:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") se přidá za výchozí zprostředkovatele konfigurace. Příklad řazení zprostředkovatelů konfigurace najdete v tématu Poskytovatel konfigurace XML.
• Proměnné prostředí nastavené předponou CustomPrefix_ přepíší výchozí zprostředkovatele konfigurace. To zahrnuje proměnné prostředí bez předpony.

Předpona je při čtení párů klíč-hodnota konfigurace odříznutá.

Vlastní předponu otestujte pomocí následujících příkazů:

set CustomPrefix__SecretKey="Secret key with CustomPrefix_ environment"
set CustomPrefix__TransientFaultHandlingOptions__Enabled=true
set CustomPrefix__TransientFaultHandlingOptions__AutoRetryDelay=00:00:21

dotnet run

Výchozí konfigurace načte proměnné prostředí a argumenty příkazového řádku s předponou DOTNET_ . Tato DOTNET_ předpona se používá v .NET pro konfiguraci hostitele a aplikace, ale ne pro konfiguraci uživatele.

Další informace o konfiguraci hostitele a aplikace najdete v tématu Obecný hostitel .NET.

Na Azure App Servicevyberte na stránce Konfigurace Nastavení > nová aplikace. Azure App Service nastavení aplikace:

• Šifrované v klidovém stavu a přenášené přes zašifrovaný kanál.
• Vystaveno jako proměnné prostředí.

Předpony připojovacího řetězce

Rozhraní API pro konfiguraci má speciální pravidla zpracování pro proměnné prostředí pro čtyři připojovací řetězce. Tyto připojovací řetězce jsou součástí konfigurace připojovacích řetězců Azure pro prostředí aplikace. Proměnné prostředí s předponami, které jsou uvedené v tabulce, se načtou do aplikace s výchozí konfigurací nebo když není dodána žádná předpona AddEnvironmentVariables .

Když je proměnná prostředí zjištěna a načtena do konfigurace se všemi čtyřmi předponami, které jsou uvedeny v tabulce:

• Konfigurační klíč se vytvoří odebráním předpony proměnné prostředí a přidáním konfiguračního klíče ( ConnectionStrings ).
• Vytvoří se nová dvojice klíč-hodnota konfigurace, která představuje poskytovatele připojení databáze (s výjimkou CUSTOMCONNSTR_ , který nemá zadaného poskytovatele).

Proměnné prostředí nastavené v souboru launchSettings. JSON

Proměnné prostředí nastavené v launchSettings. JSON přepíší ty nastavené v prostředí systému.

Zprostředkovatel konfigurace příkazového řádku

Použijete-li výchozí konfiguraci, CommandLineConfigurationProvider načte konfiguraci z dvojice klíč-hodnota argumentu klíč-hodnota po následujících zdrojích konfigurace:

• appSettings. JSON a appSettings. Environment .. soubory JSON .
• Tajné klíče aplikace (správce tajného klíče) v Development prostředí
• Proměnné prostředí.

Ve výchozím nastavení jsou hodnoty konfigurace nastavené na příkazovém řádku přepsat hodnoty konfigurace nastavené všemi ostatními poskytovateli konfigurace.

s Visual Studio 2019 verze 16,10 preview 4 a novější můžete zadat argumenty příkazového řádku pomocí dialogového okna spustit profily .

Argumenty příkazového řádku

Následující příkaz nastaví klíče a hodnoty pomocí = :

dotnet run SecretKey="Secret key from command line"

Následující příkaz nastaví klíče a hodnoty pomocí / :

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

Následující příkaz nastaví klíče a hodnoty pomocí -- :

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

Hodnota klíče:

• Musí následovat po = , nebo klíč musí mít předponu -- nebo, / Pokud se hodnota řídí mezerou.
• Není vyžadováno = , pokud je použit. Například, SomeKey=.

V rámci stejného příkazu Nekombinujte páry klíč-hodnota argumentu příkazového řádku, které = se používají s páry klíč-hodnota, které používají mezeru.

Poskytovatel konfigurace klíče na soubor

KeyPerFileConfigurationProviderPoužívá soubory adresáře jako konfigurační páry klíč-hodnota. Klíč je název souboru. Hodnota je obsah souboru. Poskytovatel konfigurace klíče na soubor se používá ve scénářích hostování Docker.

Chcete-li aktivovat konfiguraci klíče na soubor, zavolejte AddKeyPerFile metodu rozšíření na instanci ConfigurationBuilder . directoryPathDo souborů musí být absolutní cesta.

Přetížení umožňují zadat:

• Action<KeyPerFileConfigurationSource>Delegát, který konfiguruje zdroj.
• Zda je adresář nepovinný a cesta k adresáři.

Dvojité podtržítko ( __ ) se používá jako oddělovač konfiguračního klíče v názvech souborů. Například název souboru Logging__LogLevel__System vytvoří konfigurační klíč Logging:LogLevel:System .

Zavolat ConfigureAppConfiguration při sestavování hostitele k určení konfigurace aplikace:

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

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

Poskytovatel konfigurace paměti

MemoryConfigurationProviderPoužívá kolekci v paměti jako konfigurační páry klíč-hodnota.

Následující kód přidá kolekci paměti do konfiguračního systému:

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

V předchozím kódu MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) přidá poskytovatele paměti po výchozích poskytovatelích konfigurace. Příklad řazení zprostředkovatelů konfigurace najdete v tématu Poskytovatel konfigurace XML.

Viz také

• Konfigurace v .NET
• Obecný hostitel .NET
• Implementace vlastního zprostředkovatele konfigurace