Konfigurációszolgáltatók a .NET-ben

A .NET-ben történő konfiguráció a konfigurációszolgáltatókkal lehetséges. Számos szolgáltató különböző konfigurációs forrásokra támaszkodik. Ez a cikk az összes különböző konfigurációs szolgáltatót és azok megfelelő forrásait ismerteti.

• Fájlkonfigurációs szolgáltató
• Környezeti változókonfigurációs szolgáltató
• Parancssori konfigurációszolgáltató
• Fájlonkénti kulcskonfigurációs szolgáltató
• Memóriakonfigurációs szolgáltató

Fájlkonfigurációs szolgáltató

FileConfigurationProvider A konfiguráció fájlrendszerből való betöltésének alaposztálya. A következő konfigurációs szolgáltatók a következőkből származnak FileConfigurationProvider:

• JSON-konfigurációszolgáltató
• XML-konfigurációszolgáltató
• INI-konfigurációszolgáltató

A kulcsok nem érzékenyek a kis- és nagybetűkre. Az összes fájlkonfigurációs szolgáltató eldobja, FormatException ha az ismétlődő kulcsok egyetlen szolgáltatóban találhatók.

JSON-konfigurációszolgáltató

Az JsonConfigurationProvider osztály egy JSON-fájlból tölti be a konfigurációt. Telepítse a Microsoft.Extensions.Configuration.Json NuGet-csomagot.

A túlterhelések a következőket adhatók meg:

• A fájl megadása nem kötelező.
• Azt jelzi, hogy a konfiguráció újra betöltődik-e, ha a fájl megváltozik.

Tekintse meg az alábbi kódot:

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

A fenti kód a következőket végzi el:

• Törli a metódusban alapértelmezés szerint hozzáadott összes meglévő konfigurációs szolgáltatót CreateApplicationBuilder(String[]) .
• A JSON-konfigurációszolgáltatót a appsettings.json és az appsettings betöltésére konfigurálja.Environmentjson-fájlok a következő beállításokkal:
  • optional: true: A fájl nem kötelező.
  • reloadOnChange: true: A fájl újratöltődik a módosítások mentésekor.

Fontos

Ha konfigurálási szolgáltatókatIConfigurationBuilder.Addad hozzá, a hozzáadott konfigurációszolgáltató a lista végére IConfigurationSource kerül. Ha több szolgáltató is talált kulcsokat, a kulcsok olvasásának utolsó szolgáltatója felülbírálja a korábbi szolgáltatókat.

Példa appsettings.json különböző konfigurációs beállításokkal rendelkező fájlra:

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

A példányból a IConfigurationBuilder konfigurációszolgáltatók hozzáadása után meghívhatja IConfigurationBuilder.Build() az objektum lekérését IConfigurationRoot . A konfigurációs gyökér a konfigurációs hierarchia gyökerét jelöli. A konfiguráció szakaszai a .NET-objektumok példányaihoz köthetők, és később függőséginjektálás útján is megadhatók IOptions<TOptions> .

Feljegyzés

A JSON-fájl buildelési műveletének és a Másolás kimeneti könyvtárba tulajdonságának a Tartalom és a Másolás értékre kell állítania, ha újabb (vagy mindig másolás).

Vegye figyelembe az TransientFaultHandlingOptions alábbi osztályt:

namespace ConsoleJson.Example;

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

Az alábbi kód létrehozza a konfiguráció gyökerét, egy szakaszt az osztálytípushoz TransientFaultHandlingOptions köt, és a kötött értékeket a konzolablakba nyomtatja:

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

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

Az alkalmazás a következő mintakimenetet írja:

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

XML-konfigurációszolgáltató

Az XmlConfigurationProvider osztály futtatáskor betölti a konfigurációt egy XML-fájlból. Telepítse a Microsoft.Extensions.Configuration.Xml NuGet-csomagot.

Az alábbi kód bemutatja az XML-fájlok XML-konfigurációszolgáltatóval való konfigurálását.

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

A fenti kód a következőket végzi el:

• Törli a metódusban alapértelmezés szerint hozzáadott összes meglévő konfigurációs szolgáltatót CreateApplicationBuilder(String[]) .
• Az XML-konfigurációszolgáltatót úgy konfigurálja, hogy betöltse a appsettings.xml és repeating-example.xml fájlokat a következő beállításokkal:
  • optional: true: A fájl nem kötelező.
  • reloadOnChange: true: A fájl újratöltődik a módosítások mentésekor.
• Konfigurálja a környezeti változók konfigurációs szolgáltatóját.
• Konfigurálja a parancssori konfigurációszolgáltatót, ha az adott args argumentumokat tartalmaz.

Az XML-beállításokat felül kell bírálni a környezeti változók konfigurációszolgáltatójának és a parancssori konfigurációszolgáltatónak a beállításai alapján.

Példa appsettings.xml különböző konfigurációs beállításokkal rendelkező fájlra:

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

Tipp.

A Típus WinForms-alkalmazásokban való használatához IConfiguration adjon hozzá egy hivatkozást a Microsoft.Extensions.Configuration.Xml NuGet-csomaghoz. Példányosíthatja és láncba kapcsolhatja a ConfigurationBuilder hívásokat.AddXmlFileBuild() További információ: .NET Docs Issue #29679.

A .NET 5-ös és korábbi verzióiban adja hozzá az attribútumot az name azonos elemnevet használó ismétlődő elemek megkülönböztetéséhez. A .NET 6-os és újabb verzióiban az XML-konfigurációszolgáltató automatikusan indexeli az ismétlődő elemeket. Ez azt jelenti, hogy nem kell megadnia az name attribútumot, kivéve, ha a kulcsban a "0" indexet szeretné használni, és csak egy elem van. (Ha .NET 6-os vagy újabb verzióra frissít, előfordulhat, hogy a viselkedés megváltozása miatt megszakad. További információ: Az ismétlődő XML-elemek közé tartozik az 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>

Az alábbi kód beolvassa az előző konfigurációs fájlt, és megjeleníti a kulcsokat és értékeket:

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

Az alkalmazás a következő mintakimenetet írja:

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

Az attribútumok az értékek megadására használhatók:

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

Az előző konfigurációs fájl a következő kulcsokat tölti be a következőkkel value:

• key:attribute
• section:key:attribute

INI-konfigurációszolgáltató

Az IniConfigurationProvider osztály futásidőben betölti a konfigurációt egy INI-fájlból. Telepítse a Microsoft.Extensions.Configuration.Ini NuGet-csomagot.

Az alábbi kód törli az összes konfigurációs szolgáltatót, és forrásként két INI-fájlt ad hozzá IniConfigurationProvider :

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élda appsettings.ini különböző konfigurációs beállításokkal rendelkező fájlra:

SecretKey="Secret key value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Az alábbi kód az előző konfigurációs beállításokat jeleníti meg a konzolablakba való írással:

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

Az alkalmazás a következő mintakimenetet írja:

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

Környezeti változókonfigurációs szolgáltató

Az alapértelmezett konfiguráció használatával a konfiguráció betöltődik a EnvironmentVariablesConfigurationProvider környezeti változó kulcs-érték párjaiból appsettings.json, appsettings.Environment Json és Secret Manager. Ezért a környezetből beolvasott kulcsértékek felülbírálják a appsettings.json, appsettings.Environment Json és Secret Manager.

Az : elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. A Bash például : nem támogatja a határolót. Az összes platformon támogatott dupla aláhúzásjel (__) automatikusan lecseréli a környezeti változók elválasztóit : .

Fontolja meg az osztályt TransientFaultHandlingOptions :

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

Az alábbi set parancsok a környezet kulcsait és értékeit TransientFaultHandlingOptionsSecretKey állítják be.

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

Ezek a környezeti beállítások csak a parancsablakból indított folyamatokban vannak beállítva. A Visual Studióval indított webalkalmazások nem olvassák őket.

A Visual Studio 2019 és újabb verzióival környezeti változókat adhat meg a Profilok indítása párbeszédpanelen.

A következő setx-parancsokkal állíthatja be a környezeti kulcsokat és értékeket Windows rendszeren. setx A beállításokkal ellentétben seta rendszer megőrzi a beállításokat. /M beállítja a változót a rendszerkörnyezetben. Ha nem használja a /M kapcsolót, egy felhasználói környezeti változó van beállítva.

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

Annak tesztelése, hogy az előző parancsok felülírják-e a appsettings.json és az alkalmazásbeállításokat.Environment json-beállítások:

• A Visual Studio használata: Kilépés és újraindítás a Visual Studióval.
• A parancssori felülettel: Indítsa el az új parancsablakot, és írja be dotnet run.

Előtagok

A környezeti változók előtagjának megadásához sztringgel hívja meg AddEnvironmentVariables a következőt:

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

A fenti kód a következőket végzi el:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") az alapértelmezett konfigurációszolgáltatók után lesz hozzáadva. A konfigurációszolgáltatók megrendelésére példaként tekintse meg az XML-konfigurációszolgáltatót.
• Az előtaggal CustomPrefix_ beállított környezeti változók felülbírálják az alapértelmezett konfigurációszolgáltatókat. Ide tartoznak az előtag nélküli környezeti változók.

Az előtag a konfigurációs kulcs-érték párok olvasásakor törlődik.

Az alapértelmezett konfiguráció betölti a környezeti változókat és a parancssori argumentumokat DOTNET_. Az DOTNET_ előtagot a .NET használja a gazdagép- és alkalmazáskonfigurációhoz, a felhasználói konfigurációhoz azonban nem.

A gazdagép- és alkalmazáskonfigurációval kapcsolatos további információkért lásd: .NET Generic Host.

Csatlakozás ion sztringelőtagok

A Configuration API négy kapcsolati sztring környezeti változó speciális feldolgozási szabályaival rendelkezik. Ezek a kapcsolati sztring részt vesznek az Azure-kapcsolati sztring alkalmazáskörnyezethez való konfigurálásában. A táblázatban látható előtagokkal rendelkező környezeti változók az alapértelmezett konfigurációval töltődnek be az alkalmazásba, vagy ha nincs megadva előtag.AddEnvironmentVariables

Csatlakozás ion karakterlánc előtagja	Szolgáltató
CUSTOMCONNSTR_	Egyéni szolgáltató
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL Database
SQLCONNSTR_	SQL Server

Amikor felfedez egy környezeti változót, és betöltődik a konfigurációba a táblázatban látható négy előtag bármelyikével:

• A konfigurációs kulcs a környezeti változó előtagjának eltávolításával és egy konfigurációs kulcsszakasz ()ConnectionStrings hozzáadásával jön létre.
• Létrejön egy új konfigurációs kulcs-érték pár, amely az adatbázis-kapcsolat szolgáltatóját jelöli (kivéve CUSTOMCONNSTR_, amely nem rendelkezik megadott szolgáltatóval).

Környezeti változókulcs	Konvertált konfigurációs kulcs	Szolgáltató konfigurációs bejegyzése
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	A konfigurációs bejegyzés nem jött létre.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kulcs: ConnectionStrings:{KEY}_ProviderName Érték: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Kulcs: ConnectionStrings:{KEY}_ProviderName Érték: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kulcs: ConnectionStrings:{KEY}_ProviderName Érték: System.Data.SqlClient

Indításkor beállított környezeti változók Gépház.json

Az indításkor beállított környezeti változók felülbírálják a rendszerkörnyezetben beállítottakat Gépház.json felülbírálják őket.

Azure-alkalmazás szolgáltatásbeállítások

A Azure-alkalmazás Szolgáltatásban válassza az Új alkalmazás beállítást a Gépház> Configuration lapon. Azure-alkalmazás szolgáltatásalkalmazás beállításai a következők:

• Inaktív állapotban titkosítva és titkosított csatornán keresztül továbbítva.
• Környezeti változókként van közzétéve.

Parancssori konfigurációszolgáltató

Az alapértelmezett konfiguráció használatával a konfiguráció a CommandLineConfigurationProvider parancssori argumentum kulcs-érték párjaiból töltődik be a következő konfigurációs források után:

• appsettings.json és appsettings.Environment.JSON-fájlok.
• Alkalmazás titkos kódjai (Secret Manager) a Development környezetben.
• Környezeti változók.

Alapértelmezés szerint a parancssorban beállított konfigurációs értékek felülbírálják az összes többi konfigurációszolgáltatónál beállított konfigurációs értékeket.

A Visual Studio 2019-es és újabb verzióival parancssori argumentumokat adhat meg a Profilok indítása párbeszédpanelen.

Parancssori argumentumok

A következő parancs a következő paranccsal =állítja be a kulcsokat és az értékeket:

dotnet run SecretKey="Secret key from command line"

A következő parancs a következő paranccsal /állítja be a kulcsokat és az értékeket:

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

A következő parancs a következő paranccsal --állítja be a kulcsokat és az értékeket:

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

A kulcs értéke:

• Követnie =kell, vagy a kulcsnak előtaggal kell rendelkeznie -- , vagy / ha az érték szóközt követ.
• Használat esetén = nincs szükség rá. Például: SomeKey=.

Ugyanazon a parancson belül ne keverje össze a parancssori argumentum kulcs-érték párjait, amelyek szóközt használó kulcs-érték párokkal használhatók = .

Fájlonkénti kulcskonfigurációs szolgáltató

A KeyPerFileConfigurationProvider címtár fájljait használja konfigurációs kulcs-érték párként. A kulcs a fájlnév. Az érték a fájl tartalma. A fájlonkénti kulcskonfigurációs szolgáltatót a Docker üzemeltetési forgatókönyvei használják.

A fájlonkénti kulcskonfiguráció aktiválásához hívja meg a AddKeyPerFile bővítménymetódust egy példányon ConfigurationBuilder. A directoryPath fájloknak abszolút elérési útnak kell lenniük.

A túlterhelések lehetővé teszik az alábbiak megadását:

• A Action<KeyPerFileConfigurationSource> forrást konfiguráló meghatalmazott.
• Nem kötelező megadni a könyvtárat és a könyvtár elérési útját.

A dupla aláhúzás (__) konfigurációs kulcs elválasztóként használatos a fájlnevekben. A fájlnév Logging__LogLevel__System például létrehozza a konfigurációs kulcsot Logging:LogLevel:System.

Hívás ConfigureAppConfiguration a gazdagép létrehozásakor az alkalmazás konfigurációjának megadásához:

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

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

Memóriakonfigurációs szolgáltató

A MemoryConfigurationProvider rendszer egy memórián belüli gyűjteményt használ konfigurációs kulcs-érték párként.

A következő kód egy memóriagyűjteményt ad hozzá a konfigurációs rendszerhez:

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

Az előző kódban MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) adja hozzá a memóriaszolgáltatót az alapértelmezett konfigurációs szolgáltatók után. A konfigurációszolgáltatók megrendelésére példaként tekintse meg az XML-konfigurációszolgáltatót.

Lásd még

• Konfiguráció a .NET-ben
• .NET Általános gazdagép
• Egyéni konfigurációszolgáltató implementálása