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.
- Zprostředkovatel konfigurace v souboru
- Zprostředkovatel konfigurace proměnné prostředí
- Zprostředkovatel konfigurace v příkazovém řádku
- Zprostředkovatele konfigurace „klíč na soubor“
- Zprostředkovatel konfigurace v paměti
Zprostředkovatel konfigurace v souboru
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ů vyvolá FormatException , když jsou v jednom poskytovateli 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.
Pro opětovné načtení je možné 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 appsettings.
Environment
.Soubory 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.Addpřidaný zprostředkovatel konfigurace přidá na konec IConfigurationSource
seznamu. Když jsou klíče nalezeny více zprostředkovateli, poslední zprostředkovatel přečíst klíč přepisuje předchozí zprostředkovatele.
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"
}
}
}
IConfigurationBuilder Po přidání zprostředkovatele konfigurace můžete z instance zavolatIConfigurationBuilder.Build(), aby se IConfigurationRoot objekt získal. Kořen konfigurace představuje kořen hierarchie konfigurace. Oddíly z konfigurace lze svázat s instancemi objektů .NET a později je možné je poskytnout prostřednictvím IOptions<TOptions> injektáže závislostí.
Poznámka:
Vlastnosti akce sestavení a kopírování do výstupního adresáře 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í.
- Nakonfiguruje zprostředkovatele konfigurace příkazového řádku, pokud daná
args
hodnota obsahuje argumenty.
Nastavení XML se přepíše nastavením v zprostředkovateli konfigurace proměnných prostředí a zprostředkovatelem 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>
Tip
Pokud chcete použít IConfiguration
typ v aplikacích WinForms, přidejte odkaz na balíček NuGet Microsoft.Extensions.Configuration.Xml . ConfigurationBuilder Vytvořte instanci volání a řetězu volání a AddXmlFileBuild(). 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í vyplývajícímu z této změny chování. Další informace naleznete v tématu Opakované elementy XML zahrnout 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. Microsoft.Extensions.Configuration.Ini
Nainstalujte balíček NuGet.
Následující kód vymaže všechny zprostředkovatele konfigurace a přidá jako IniConfigurationProvider
zdroj dva 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();
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
Zprostředkovatel konfigurace proměnné prostředí
Při použití výchozí konfigurace EnvironmentVariablesConfigurationProvider se načte konfigurace z párů klíč-hodnota proměnné prostředí po přečtení appsettings.json appsettings.Environment
. json a secret manager. Proto hodnoty klíče načtené z prostředí přepisují hodnoty načtené z appsettings.json, appsettings.Environment
. json a secret manager.
Oddělovač :
nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Bash například :
nepodporuje oddělovač. 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 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, že předchozí příkazy přepíší všechny appsettings.json a appsettings.Environment
. Nastavení json:
- 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 proměnných prostředí, zavolejte AddEnvironmentVariables řetězec:
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ího 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í zprostředkovatele 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 při zadání žádné předpony .AddEnvironmentVariables
Předpona připojovacího řetězce | Poskytovatel |
---|---|
CUSTOMCONNSTR_ |
Vlastní poskytovatel |
MYSQLCONNSTR_ |
MySQL |
SQLAZURECONNSTR_ |
Azure SQL Database |
SQLCONNSTR_ |
SQL Server |
Když je zjištěna proměnná prostředí a načtena do konfigurace s některou 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 |
Proměnné prostředí nastavené při spuštění Nastavení.json
Proměnné prostředí nastavené při spuštění Nastavení.json přepíší tyto sady v systémovém prostředí.
Nastavení služby Aplikace Azure
V Aplikace Azure Service vyberte na stránce Nastavení> Konfigurace nastavení nové aplikace. Nastavení aplikace Azure App Service se:
- Šifrují v neaktivním uloženém stavu a přenášejí přes šifrovaný kanál.
- Vystavují 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říkladSomeKey=
.
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.
Zprostředkovatele konfigurace „klíč na 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í cesta.
Opětovné načtení 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í hostitele voláte 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 konfigurace v paměti
MemoryConfigurationProvider použí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;
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á zprostředkovatele paměti za výchozí zprostředkovatele konfigurace. Příklad řazení zprostředkovatelů konfigurace najdete v tématu Zprostředkovatel konfigurace XML.
Viz také
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro