Zprostředkovatelé konfigurace v .NET

Konfigurace v .NET je možná u poskytovatelů konfigurace. Několik typů poskytovatelů spoléhá 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 souboru
• Poskytovatel konfigurace proměnných prostředí
• Zprostředkovatel konfigurace v příkazovém řádku
• Zprostředkovatel konfigurace „klíč pro každý soubor“
• Poskytovatel konfigurace paměti

Poskytovatel souborové konfigurace

FileConfigurationProvider je základní třída pro načítání konfigurace ze souborového systému. Následující zprostředkovatelé konfigurace jsou odvozeni z FileConfigurationProvider:

• Zprostředkovatel konfigurace JSON
• Zprostředkovatel konfigurace v souboru XML
• Zprostředkovatel konfigurace v souboru INI

U klíčů se nerozlišuje velikost písmen. Všichni zprostředkovatelé konfigurace souborů vyvolají FormatException, když jsou v jednom zprostředkovateli nalezeny duplicitní klíče.

Zprostředkovatel konfigurace JSON

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

Přetížení mohou určit:

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

Uvažujte následující kód:

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

Předchozí kód:

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

Důležité

Při přidávání zprostředkovatelů konfigurace se IConfigurationBuilder.Addna konec IConfigurationSource seznamu přidá přidaný zprostředkovatel konfigurace. Když více poskytovatelů najde klíče, poslední poskytovatel, který klíč přečte, přepíše klíče od předchozích poskytovatelů.

Příklad souboru appsettings.json s různými nastaveními 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 zavolat IConfigurationBuilder.Build(), abyste získali objekt IConfigurationRoot. Kořen konfigurace představuje kořen hierarchie konfigurace. Oddíly z konfigurace lze svázat s instancemi objektů .NET a později je poskytnout prostřednictvím IOptions<TOptions> injektáže závislostí.

Poznámka:

Vlastnosti Akce sestavení a Kopírovat do výstupního adresáře u souboru JSON musí být nastaveny na Obsah a Kopírovat, pokud je novější (nebo vždy kopírovat).

Vezměte v úvahu třídu definovanou TransientFaultHandlingOptions následujícím způsobem:

namespace ConsoleJson.Example;

public sealed 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 TransientFaultHandlingOptions typ třídy a vytiskne vázané hodnoty do okna konzoly:

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

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

Aplikace zapíše následující ukázkový výstup:

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

Zprostředkovatel konfigurace v souboru XML

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

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

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

Předchozí kód:

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

Nastavení XML jsou přepsána nastavením v zprostředkovateli konfigurace proměnných prostředí a zprostředkovateli konfigurace příkazového řádku.

Příklad souboru 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>

Návod

Pokud chcete použít IConfiguration typ v aplikacích WinForms, přidejte odkaz na balíček NuGet Microsoft.Extensions.Configuration.Xml . Vytvořte instanci ConfigurationBuilder a řetězte volání na AddXmlFile a Build(). Další informace najdete v tématu Problém s dokumentem .NET č. 29679.

V .NET 5 a starších verzích přidejte name atribut pro rozlišení opakujících se prvků, které používají stejný název elementu. V .NET 6 a novějších verzích poskytovatel konfigurace XML automaticky indexuje opakující se elementy. To znamená, že nemusíte zadávat name atribut, s výjimkou případu, kdy chcete index "0" v klíči a existuje pouze jeden prvek. (Pokud upgradujete na .NET 6 nebo novější, může dojít k přerušení v důsledku této změny chování. Další informace naleznete v tématu Opakované elementy XML zahrnující index.)

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

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

K poskytování hodnot lze použít atributy:

<?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 s hodnotou value:

• key:attribute
• section:key:attribute

Zprostředkovatel konfigurace v souboru INI

Třída IniConfigurationProvider načte konfiguraci ze souboru INI za běhu.

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

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

Poznámka:

Chcete-li mít přístup k Microsoft.Extensions.Configuration.Ini metodě, musíte nainstalovat AddIniFile balíček NuGet.

Příklad souboru 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 napíšete do okna konzoly:

foreach ((string key, string? value) in
    builder.Configuration.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

Poskytovatel konfigurace proměnných prostředí

Při použití výchozí konfigurace EnvironmentVariablesConfigurationProvider se konfigurace načítá z párů proměnná klíč-hodnota prostředí poté, co se přečtou soubory appsettings.json appsettings.Environment.json a Správce tajemství. Proto klíčové hodnoty načtené z prostředí přepisují hodnoty načtené z appsettings.json, appsettings.Environment.json a Správce tajných klíčů.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Například oddělovač : není podporován Bash. Dvojitá podtržítka (__), která je podporována na všech platformách, automaticky nahradí všechny : oddělovače v proměnných prostředí.

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

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

Následující set příkazy nastavily klíče prostředí a hodnoty SecretKey a TransientFaultHandlingOptions.

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

Tato nastavení prostředí jsou nastavena pouze v procesech spuštěných z příkazového okna, ve které byly nastaveny. Webové aplikace spouštěné pomocí sady Visual Studio je nečtou.

V sadě Visual Studio 2019 a novější můžete pomocí dialogového okna Spustit profily zadat proměnné prostředí.

Následující příkazy setx lze použít k nastavení klíčů a hodnot prostředí ve Windows. Na rozdíl od příkazu set se nastavení příkazu setx zachovají. /M nastaví proměnnou v systémovém prostředí. Pokud není použit přepínač /M, 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

Chcete-li otestovat, zda předchozí příkazy přepíší všechna nastavení appsettings.json a appsettings.Environmentjson:

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

Předpony

Pokud chcete zadat předponu pro proměnné prostředí, zavolejte AddEnvironmentVariables s řetězcem:

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

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 Zprostředkovatel konfigurace XML.
• Proměnné prostředí nastavené s předponou CustomPrefix_ přepíší výchozí poskytovatele konfigurace. To zahrnuje proměnné prostředí bez předpony.

Když jsou přečteny konfigurační páry klíč-hodnota, je předpona odstraněna.

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

Další informace o konfiguraci hostitele a aplikace viz Obecný hostitel .NET.

Předpony připojovacích řetězců

Rozhraní API pro konfiguraci má speciální pravidla zpracování pro proměnné prostředí čtyř připojovacích řetězců. Tyto připojovací řetězce se používají v konfiguraci připojovacích řetězců Azure pro prostředí aplikací. Proměnné prostředí s předponami zobrazenými v tabulce se načtou do aplikace s výchozí konfigurací nebo pokud není žádná předpona zadána.AddEnvironmentVariables

Předpona připojovacího řetězce	Poskytovatel
CUSTOMCONNSTR_	Vlastní poskytovatel
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL databáze
SQLCONNSTR_	SQL Server

Když je zjištěna proměnná prostředí a načtena do konfigurace s jednou ze čtyř předpon uvedených v tabulce:

• Je vytvořen konfigurační klíč odebráním předpony proměnné prostředí a přidáním části konfiguračního klíče (ConnectionStrings).
• Vytvoří se nový pár klíč-hodnota konfigurace, který představuje zprostředkovatele připojení k databázi (s výjimkou předpony CUSTOMCONNSTR_, která nemá žádného uvedeného zprostředkovatele).

Klíč proměnné prostředí	Převedený konfigurační klíč	Položka konfigurace zprostředkovatele
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Položka konfigurace není vytvořena.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Klíč: ConnectionStrings:{KEY}_ProviderName: Hodnota: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Klíč: ConnectionStrings:{KEY}_ProviderName: Hodnota: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Klíč: ConnectionStrings:{KEY}_ProviderName: Hodnota: System.Data.SqlClient

Důležité

Microsoft doporučuje používat nejbezpečnější dostupný tok ověřování. Pokud se připojujete k Azure SQL, Spravované identity pro prostředky Azure jsou doporučenou metodou ověřování.

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

Proměnné prostředí nastavené v launchSettings.json přepíší proměnné prostředí nastavené v systémovém prostředí.

Nastavení služby Aplikace Azure

Na Azure App Servicevyberte Přidat na stránce Nastavení>Proměnné prostředí. Nastavení aplikace Azure App Service jsou:

• Zašifrované v klidovém stavu a přenášeno přes šifrovaný kanál.
• Jsou vystaveny jako proměnné prostředí.

Zprostředkovatel konfigurace v příkazovém řádku

Při použití výchozí konfigurace se CommandLineConfigurationProvider načte konfigurace z párů klíč-hodnota argumentu příkazového řádku za následujícími zdroji konfigurace:

• appsettings.json a appsettings.Environment.soubory json.
• Tajné kódy aplikací (Secret Manager) v Development prostředí.
• Proměnné prostředí.

Ve výchozím nastavení hodnoty konfigurace nastavené na příkazovém řádku přepisují konfigurační hodnoty nastavené se všemi ostatními zprostředkovateli konfigurace.

V sadě Visual Studio 2019 a novějších 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 /, když hodnota následuje po mezeře.
• Není vyžadována, pokud je použito =. Například SomeKey=.

V rámci stejného příkazu nemíchejte páry klíč-hodnota argumentů příkazového řádku, které používají =, s páry klíč-hodnota, které používají mezeru.

Poskytovatel konfigurace klíče na každý soubor

KeyPerFileConfigurationProvider používá soubory v adresáři jako konfigurační páry klíč-hodnota. Klíč je název souboru. Hodnota je obsah souboru. Zprostředkovatel konfigurace „klíč na soubor“ se používá ve scénářích hostování Dockeru.

Pokud chcete aktivovat konfiguraci „klíč na soubor“, zavolejte rozšiřující metodu AddKeyPerFile v instanci ConfigurationBuilder. Cesta directoryPath k souborům musí být absolutní.

Přetížení umožňuje určit:

• Delegáta Action<KeyPerFileConfigurationSource>, který konfiguruje zdroj.
• Jestli je adresář volitelný a cestu k tomuto adresáři.

Jako oddělovač konfiguračních klíčů v názvech souborů se používá dvojité podtržítko (__). Například název souboru Logging__LogLevel__System vytváří konfigurační klíč Logging:LogLevel:System.

Při sestavování hostu použijte ConfigureAppConfiguration k určení konfigurace aplikace:

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

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

Zprostředkovatel paměťové konfigurace

MemoryConfigurationProvider používá sbírku v paměti pro ukládání konfiguračních párů 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;

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

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

Viz také

• Konfigurace v .NET
• Obecný hostitel .NET
• Implementujte vlastního poskytovatele konfigurace