Sdílet prostřednictvím

Zprostředkovatelé konfigurace v .NET

  • Článek

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

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:

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

Dialogové okno Spustit profily zobrazující 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

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 se doporučují metodou ověřování.

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

Proměnné prostředí nastavené v launchSettings.json přepíší tyto sady 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 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 .

Dialogové okno Spustit profily s argumenty příkazového řádku

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.

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é