Konfigurace v ASP.NET Core

Konfigurace aplikace v ASP.NET Core se provádí pomocí jednoho nebo více zprostředkovatelů konfigurace. Zprostředkovatelé konfigurace čtou konfigurační data z párů klíč-hodnota s využitím různých zdrojů konfigurace:

• Soubory nastavení, jako je appsettings.json
• Proměnné prostředí, včetně konfigurace aplikace Azure
• Azure Key Vault
• Argumenty příkazového řádku
• Vlastní zprostředkovatelé, nainstalovaní nebo vytvoření
• Objekty .NET v paměti

Tento článek poskytuje informace o konfiguraci v ASP.NET Core. Informace o používání konfigurace v aplikacích non-ASP.NET Core najdete v tématu Konfigurace .NET.

Další Blazor pokyny ke konfiguraci, které doplňují nebo nahrazují zde uvedené pokyny, najdete v ASP.NET Core Blazor konfiguraci.

Tento článek se týká především konfigurace aplikace. Zde jsou uvedeny další typy konfigurace, například soubory nastavení spuštění a web.config soubor, ale jejich primární dokumentace je jinde:

• Spusťte soubory nastavení (launch.json/launchSettings.json), což jsou konfigurační soubory nástrojů pro Development prostředí. Další informace naleznete v tématu prostředí runtime ASP.NET Core. Některé podrobnosti o nastavení spuštění jsou popsány v tomto článku v části Přepsání nastavení proměnných prostředí.
• web.config, což je konfigurační soubor serveru pro internetovou informační službu (IIS). Další informace naleznete v tématu Hostitel ASP.NET Core ve Windows se službou IIS a modul ASP.NET Core (ANCM) pro službu IIS.

Další informace o migraci konfigurace aplikace ze starších verzí ASP.NET najdete v tématu Migrace konfigurace do ASP.NET Core.

Warning

Tento článek ukazuje použití připojovací řetězec. Při použití místní databáze pro vývoj a testování není vyžadováno ověření uživatele databáze prostřednictvím připojovacího řetězce. V produkčních prostředích připojovací řetězce někdy obsahují heslo pro ověření přístupu k databázi nebo databázových operací. Přihlašovací údaje vlastníka prostředku (ROPC) v připojovacím řetězci představují bezpečnostní riziko, kterému by se mělo v produkčních aplikacích vyhnout. Produkční aplikace by měly používat nejbezpečnější dostupný tok ověřování. Další informace o ověřování pro aplikace nasazené do testovacího nebo produkčního prostředí najdete v tématech o zabezpečení ASP.NET Core.

Příklady v tomto článku používají primární konstruktory dostupné v jazyce C# 12 (.NET 8) nebo novější. Další informace naleznete v tématu Deklarování primárních konstruktorů pro třídy a struktury (kurz dokumentace jazyka C#) a primární konstruktory (Průvodce jazykem C#).

Čtení hodnot konfigurace

Konfigurace se obvykle čte vyřešením IConfiguration služby (Microsoft.Extensions.Configuration oboru názvů) a použitím klíče z párů klíč-hodnota konfigurace pro získání hodnoty konfigurace.

Následující kód komponenty Razor ukazuje, jak je z konfigurace získána hodnota, emailová adresa technického kontaktu, pomocí klíče TechnicalContactEmail.

@inject IConfiguration Config

Technical Contact: @Config["TechnicalContactEmail"]

Konfigurace aplikací a hostitelů

Aplikace ASP.NET Core konfigurují a spouští hostitele. Tento hostitel je zodpovědný za spouštění aplikací a správu doby života. Konfigurační páry klíč-hodnota hostitele jsou zahrnuty v konfiguraci aplikace. I když u poskytovatelů konfigurace hostitele můžete provádět určitou konfiguraci aplikace, doporučujeme provádět pouze takovou konfiguraci, která je nezbytná pro hostitele v konfiguraci hostitele.

Konfigurace aplikace je nejvyšší prioritou. Další informace o tom, jak se při sestavování hostitele používají zprostředkovatelé konfigurace a jak zdroje konfigurace ovlivňují konfiguraci hostitele, viz Přehled základů ASP.NET Core.

Výchozí zdroje konfigurace aplikací

ASP.NET Core webové aplikace volají WebApplication.CreateBuilder pro inicializaci nové instance třídy WebApplicationBuilder s předem nakonfigurovanými výchozími hodnotami:

var builder = WebApplication.CreateBuilder(args);

Další informace najdete v tématu Obecný hostitel .NET v ASP.NET Core.

Výchozí konfigurace aplikace se načte v následujícím pořadí od nejvyšší po nejnižší prioritu:

1. Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
2. Proměnné prostředí nejsou opatřeny předponou ASPNETCORE_ nebo DOTNET_ při použití poskytovatele konfigurace proměnných prostředí.
3. Tajné kódy uživatelů , když aplikace běží v Development prostředí pomocí zprostředkovatele konfigurace souborů.
4. Konfigurace souboru nastavení prostředí aplikace prostřednictvím appsettings.{ENVIRONMENT}.json, kde je {ENVIRONMENT} zástupný symbol pro prostředí aplikace pomocí zprostředkovatele konfigurace JSON. Například appsettings.Production.json se používá v produkčním prostředí a appsettings.Development.json používá se během vývoje.
5. Obecná konfigurace souboru nastavení aplikace pomocí appsettings.jsonzprostředkovatele konfigurace JSON
6. Záložní konfigurace hostitele.

Note

Pro účely získání hodnot konfigurace za běhu nedoporučujeme volat CreateBuilder více než jednou. Doporučujeme použít ConfigurationManager (například: builder.Configuration, WebApplicationBuilder.Configuration) nebo použít ConfigurationBuilder z příslušného zdroje konfigurace.

Pokud chcete povolit argumenty příkazového řádku k řízení nastavení, jako je název prostředí, což je důležité pro určení souboru nastavení aplikace založeného na prostředí, který se má načíst, použije se zprostředkovatel konfigurace příkazového řádku dvakrát jako zdroj konfigurace na začátku a na konci konfigurace. Vzhledem k tomu, že se poskytovatel používá na konci, má nejvyšší prioritu.

Pokud je hodnota konfigurace nastavená v konfiguraci hostitele a aplikace, použije se konfigurace aplikace.

Výchozí zdroje konfigurace hostitele

Výchozí zdroje konfigurace hostitele od nejvyšší po nejnižší prioritu při použití na konfiguraci webové aplikace (WebApplicationBuilder):

1. Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
2. DOTNET_Proměnné prostředí s předponou pomocí Poskytovatele konfigurace proměnných prostředí.
3. ASPNETCORE_Proměnné prostředí s předponou pomocí Poskytovatele konfigurace proměnných prostředí.

Výchozí zdroje konfigurace hostitele od nejvyšší po nejnižší prioritu použité u obecného hostitele nebo webového hostitele:

1. ASPNETCORE_Proměnné prostředí s předponou pomocí Poskytovatele konfigurace proměnných prostředí.
2. Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
3. DOTNET_Proměnné prostředí s předponou pomocí Poskytovatele konfigurace proměnných prostředí.

Další informace o konfiguraci hostitele najdete v následujících zdrojích informací:

• Obecný hostitel: Doporučuje se pro aplikace ASP.NET Core, které cílí na .NET 6 nebo novější, které přijímají minimální model hostování.
• Webový hostitel: Požadováno pro aplikace ASP.NET Core, které jsou zaměřeny na verze před .NET 6, a framework to udržuje pouze kvůli zpětné kompatibilitě v .NET 6 a novějších verzích.

Proměnné hostitele

V počáteční fázi inicializace tvůrce hostitelů jsou nastaveny následující proměnné a není možné je ovlivnit konfigurací aplikace:

• Název aplikace
• Název prostředí
• Kořen obsahu.
• Kořenový adresář webu.
• Jestli se mají hledat hostující spouštěcí sestavení a která sestavení se mají hledat.
• Proměnné přečtené kódem aplikace a knihovny ze HostBuilderContext.ConfigurationIHostBuilder.ConfigureAppConfiguration zpětných volání.

Jiná nastavení hostitele se čtou z konfigurace aplikace místo konfigurace hostitele.

URLS je jedním z mnoha běžných nastavení hostitele, která se nespustí konfigurací hostitele. URLS se načte později z konfigurace aplikace. Konfigurace hostitele je záložní pro konfiguraci aplikace, takže konfiguraci hostitele lze použít k nastavení URLS, ale hodnota se přepíše jakýmkoli zdrojem konfigurace, který v konfiguraci aplikace nastavuje URLS, jako jsou soubory nastavení aplikace (appsettings.{ENVIRONMENT}.json, kde je zástupný symbol {ENVIRONMENT} název prostředí, nebo appsettings.json).

Další informace najdete v tématu Změna kořenového adresáře obsahu, názvu aplikace a prostředí azměna kořenového adresáře obsahu, názvu aplikace a prostředí pomocí proměnných prostředí nebo příkazového řádku.

Zabezpečení a tajné kódy uživatelů

Pokyny pro konfigurační data:

• Nikdy neukládejte hesla ani jiné citlivé údaje v kódu zprostředkovatele konfigurace nebo v textových konfiguračních souborech. K ukládání tajných kódů při vývoji můžete používat nástroj Secret Manager.
• Nepoužívejte produkční tajné kódy ve vývojových nebo testovacích prostředích.
• Tajné kódy zadávejte mimo projekt, aby nemohly být omylem potvrzeny do úložiště zdrojového kódu.
• Produkční aplikace by měly používat nejbezpečnější dostupný tok ověřování. Další informace najdete v tématu Zabezpečené toky ověřování.

Zdroj konfigurace souboru uživatelských tajemství výchozích zdrojů konfigurace je registrován po zdrojích konfigurace JSON pro soubory nastavení aplikace. Proto klíče tajných klíčů uživatelů mají přednost před klíči v appsettings.json a appsettings.{ENVIRONMENT}.json.

Další informace o ukládání hesel nebo jiných citlivých dat:

• prostředí ASP.NET Core Runtime
• Bezpečné ukládání tajných kódů aplikací ve vývojovém prostředí v ASP.NET Core: Obsahuje rady týkající se používání proměnných prostředí k ukládání citlivých dat. Nástroj Secret Manager používá zprostředkovatele konfigurace souborů k ukládání tajných kódů uživatelů do souboru JSON v místním systému.
• Azure Key Vault bezpečně ukládá tajné klíče aplikací pro aplikace ASP.NET Core. Další informace viz Zprostředkovatel konfigurace služby Azure Key Vault v ASP.NET Core.

Konfigurace přístupu pomocí vkládání závislostí

Konfiguraci je možné vložit do služeb pomocí vkládání závislostí (DI) rozlišením IConfiguration služby. V následujícím příkladu je hodnota konfigurace uložená pro konfigurační klíč reprezentovaný zástupným symbolem {KEY} přiřazena k value. Pokud se klíč nenajde, null přiřadí se:value

public class CustomService(IConfiguration config)
{
    public void CustomMethod()
    {
        var value = config["{KEY}"];
    }
}

Konfigurace přístupu v Program souboru

Následující kód přistupuje ke konfiguraci v Program souboru pomocí WebApplicationBuilder.Configuration (builder.Configuration):

var defaultConnectionString = 
   builder.Configuration.GetValue<string>("ConnectionStrings:DefaultConnection");

Po sestavení aplikace (za řádkem var app = builder.Build();) použijte WebApplication.Configuration (app.Configuration):

var defaultLogLevel = app.Configuration.GetValue<string>("Logging:LogLevel:Default");

Konfigurace přístupu ve Startup třídě

Tato část se obecně týká aplikací ASP.NET Core před vydáním .NET 6.

Následující kód zobrazí konfigurační data v metodách Startup:

public class Startup
{
    public Startup(IConfiguration config)
    {
        Config = config;
    }

    public IConfiguration Config { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = Config["ConnectionStrings.DefaultConnection"]}");

        ...
    }

    public void Configure(...)
    {
        var defaultLogLevel = Config["Logging:LogLevel:Default"]}");

        ...
    }
}

Zobrazení konfiguračních nastavení při spuštění pro účely ladění

Následující kód při spuštění aplikace zobrazí páry klíč-hodnota konfigurace aplikace.

Po sestavení aplikace v Program souboru (za řádkem var app = builder.Build();) umístěte následující kód, který obsahuje direktivu kompilátoru pro konfiguraci DEBUG:

#if DEBUG
foreach (var c in app.Configuration.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

Konfigurační klíče a hodnoty

Konfigurační klíče:

• Nerozlišují malá a velká písmena. Například ConnectionString a connectionstring se považují za ekvivalentní klíče.
• Pokud klíč a hodnota nastaví více než jeden zprostředkovatel konfigurace, použije se hodnota od posledního přidaného zprostředkovatele. Další informace naleznete viz Výchozí konfigurace.
• Hierarchické klíče
  • V rozhraní API pro konfiguraci funguje oddělovač dvojtečka (:) na všech platformách.
  • V proměnných prostředí nefunguje oddělovač dvojtečky na všech platformách. Dvojitá podtržítka (__) jsou podporována všemi platformami a při čtení konfigurace aplikace se automaticky převedou na dvojtečku (:).
  • V Azure Key Vaultu hierarchické klíče používají dvojité pomlčky jako oddělovač (--). Zprostředkovatel konfigurace služby Azure Key Vault automaticky nahradí dvojité pomlčky (--) dvojtečkou (:), když se tajné kódy načtou do konfigurace aplikace.
• ConfigurationBinder podporuje vazby polí na objekty pomocí indexů polí v konfiguračních klíčích. Vazba pole je popsaná v části Vazba pole .

Konfigurační hodnoty jsou řetězce. Hodnoty null nelze uložit v konfiguraci ani svázat s objekty.

Uspořádání hierarchických konfiguračních dat

Rozhraní API pro konfiguraci čte hierarchická konfigurační data zploštěním hierarchických dat pomocí oddělovače v konfiguračních klíčích, což jsou obvykle dvojtečky (:). Dvojitá podtržítka (__) se obvykle používají s konfigurací proměnných prostředí pro podporu napříč platformami.

Note

V komplexních scénářích konfigurace aplikací je nejlepší seskupit a číst související hierarchická konfigurační data pomocí vzoru možností.

Zvažte následující hierarchická konfigurační data:

• ConnectionStrings
  • DefaultConnection (Value =no-loc text="Data Source=LocalSqlServer\MSSQLDev;"::")
• Logging
  • LogLevel
    • Default (Hodnota = Information)
    • Microsoft (Hodnota = Warning)
    • Microsoft.Hosting.Lifetime (Hodnota = Information)
• AllowedHosts (Hodnota = *)

Následující tabulka zobrazuje klíče použité k obnovení hodnot v předchozích konfiguračních datech. Oddělovač není nutný pro AllowedHosts.

Klíč (oddělovač dvojtečky)	Klávesa (oddělovač dvojitého podtržítka)
ConnectionStrings:DefaultConnection	ConnectionStrings__DefaultConnection
Protokolování:LogLevel:Default	Logging__LogLevel__Default
Protokolování:LogLevel:Microsoft	Logging__LogLevel__Microsoft
Protokolování:LogLevel:Microsoft.Hosting.Lifetime	Logging__LogLevel__Microsoft.Hosting.Lifetime
PovolenéHostitele	PovolenéHostitele

Note

V komplexních scénářích konfigurace aplikací doporučujeme seskupovat a číst související hierarchická konfigurační data pomocí vzoru Možnosti.

Metody GetSection a GetChildren jsou k dispozici k izolování oddílů a podřízených oddílů v konfiguračních datech. Tyto metody jsou popsány, kde GetSection, GetChildrena Exists jsou pokryty.

Pokud struktura elementu obsahuje pole, index pole by měl být považován za další název elementu v cestě. Zvažte následující hierarchická konfigurační data jako pole.

MainObject (pole):

• První položka v poli
  • Object0
  • Object1
    • SubObject0
    • SubObject1
• Druhá položka v poli
  • Object0
  • Object1
    • SubObject0
    • SubObject1

Klíče s oddělovači dvojtečky:

• MainObject:0:Object0
• MainObject:0:Object1:SubObject0
• MainObject:0:Object1:SubObject1
• MainObject:1:Object0
• MainObject:1:Object1:SubObject0
• MainObject:1:Object1:SubObject1

Klíče s oddělovači podtržítka, které se doporučují pro kompatibilitu mezi platformami, když je konfigurace poskytována proměnnými prostředí:

• MainObject__0__Object0
• MainObject__0__Object1:SubObject0
• MainObject__0__Object1:SubObject1
• MainObject__1__Object0
• MainObject__1__Object1:SubObject0
• MainObject__1__Object1:SubObject1

Vzhledem k tomu, že konfigurace pocházející z polí je zploštěna a očíslována postupně pro každý zdroj konfigurace, který aplikace používá, mohou být hodnoty neočekávaně přepsány, pokud při strukturování a čtení dat z více zdrojů není potřeba věnovat pozornost. Zvažte následující konfigurační páry klíč-hodnota:

Modules hodnoty (pole):

• Module1
• Module2
• Module3

Pole je zploštěné a postupně indexované, čímž vytváří konfigurační páry klíč-hodnota v následující tabulce.

Key	Hodnota
Modules:0	Module1
Modules:1	Module2
Modules:2	Module3

Po vytvoření předchozí konfigurace načte jiný zdroj konfigurace následující konfiguraci:

Modules hodnoty (pole):

• Module4
• Module5

Toto pole je také zploštěno a indexováno postupně.

Key	Hodnota
Modules:0	Module4
Modules:1	Module5

Připomeňme si, že poslední zdroj konfigurace pro daný klíč nastaví hodnotu tohoto klíče, poslední sada párů klíč-hodnota konfigurace se zobrazí v následující tabulce.

Key	Hodnota
Modules:0	Module4
Modules:1	Module5
Modules:2	Module3

Nejde o překvapivý výsledek vzhledem k tomu, jak framework zploští a indexuje maticová data ze zdrojů konfigurace, ale je třeba mít na paměti, jak se vyhnout neočekávaným přepisům.

Aby se zabránilo takovým přepisům, strukturujte indexování polí tak, aby odpovídalo různým zdrojům konfigurace, které poskytují stejná data pole. Alternativním řešením je oddělovat hodnoty pole v řetězcové hodnotě jednoho páru klíč-hodnota, například pomocí čárky, středníku nebo svislítka jako oddělovače. Napište vlastní kód pro rozdělení řetězce a přiřaďte hodnoty oddělené oddělovačem vašemu poli.

Zprostředkovatelé konfigurace

V následující tabulce jsou uvedeni zprostředkovatelé konfigurace dostupní pro aplikace ASP.NET Core.

Provider	Poskytuje konfiguraci z...
Zprostředkovatel konfigurace služby Azure Key Vault	Azure Key Vault
Zprostředkovatel konfigurace aplikací Azure	Azure App Configuration
Zprostředkovatel konfigurace příkazového řádku	Parametry příkazového řádku
Vlastní zprostředkovatel konfigurace	Vlastní zdroj
Zprostředkovatel konfigurace proměnných prostředí	Proměnné prostředí
Zprostředkovatel konfigurace souborů	Soubory INI, JSON a XML
Zprostředkovatel konfigurace klíče na soubor	Soubory adresářů
Zprostředkovatel konfigurace paměti	Kolekce v paměti
Tajné kódy uživatelů	Soubor v adresáři profilu uživatele

Zdroje konfigurace jsou čteny v pořadí, v jakém jsou určeni jejich zprostředkovatelé konfigurace. Seřaďte zprostředkovatele konfigurace v kódu tak, aby odpovídali prioritám základních zdrojů konfigurace, které aplikace vyžaduje.

Typická posloupnost zprostředkovatelů konfigurace je:

1. Obecná nastavení aplikace prostřednictvím appsettings.json.
2. Nastavení prostředí aplikace prostřednictvím appsettings.{ENVIRONMENT}.json, kde {ENVIRONMENT} zástupný symbol je prostředí aplikace (příklady: Development, Production).
3. Tajné kódy uživatelů.
4. Proměnné prostředí pomocí zprostředkovatele konfigurace proměnných prostředí.
5. Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku

Běžným postupem je přidat zprostředkovatele konfigurace příkazového řádku jako poslední v řadě zprostředkovatelů, aby argumenty příkazového řádku mohly přepsat konfiguraci nastavenou jinými zprostředkovateli.

Předchozí posloupnost zprostředkovatelů se používá ve výchozí konfiguraci.

Pokud chcete zkontrolovat zprostředkovatele konfigurace aplikace, injektovatIConfiguration, přetypovat na IConfigurationRoot a číst Providers vlastnost.

V následující ConfigurationProvidersRazor komponentě se zobrazí povolené zprostředkovatele konfigurace v pořadí, v jakém jsou přidáni do aplikace.

Pages/ConfigurationProviders.razor:

@page "/configuration-providers"
@inject IConfiguration Config

<h1>Configuration Providers</h1>

@if (ConfigRoot is not null)
{
    <ul>
        @foreach (var provider in ConfigRoot.Providers)
        {
            <li>@provider</li>
        }
    </ul>
}

@code {
    private IConfigurationRoot? ConfigRoot;

    protected override void OnInitialized()
    {
        ConfigRoot = (IConfigurationRoot)Config;
    }
}

Předchozí Razor komponenta vytvoří následující výstup, kde {APP NAMESPACE} zástupný znak je jmenný prostor aplikace:

MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'ASPNETCORE_'
MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'DOTNET_'
JsonConfigurationProvider for 'appsettings.json' (Optional)
JsonConfigurationProvider for 'appsettings.Development.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.Development.json' (Optional)
EnvironmentVariablesConfigurationProvider
Microsoft.Extensions.Configuration.ChainedConfigurationProvider

V části Výchozí zdroje konfigurace aplikací uvedené dříve v tomto článku jsou zdroje konfigurace uvedené od nejvyšší po nejnižší prioritu. Předchozí ConfigurationProviders komponenta zobrazuje zdroje v pořadí, v jakém je aplikace čte. Například Zprostředkovatel konfigurace JSON pro soubor nastavení aplikace mimo prostředí (appsettings.json) je dříve v předchozím seznamu, protože je přidaný před poskytovatelem souboru nastavení aplikace vývojového prostředí (appsettings.Development.json). Poskytovatelé konfigurace jsou spouštěni od začátku seznamu po jeho konec. U odpovídajícího konfiguračního klíče mezi dvěma zprostředkovateli konfigurace JSON nastavení aplikace má poslední nastavení přednost, což je hodnota z appsettings.Development.json.

Konfigurace souboru nastavení aplikace (appsettings.json, appsettings.{ENVIRONMENT}.json)

Čtení konfigurace načtené ze souborů nastavení aplikace pomocí zprostředkovatele konfigurace JSON

Vezměme například následující soubor appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=LocalSqlServer\\MSSQLDev;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Vložte instanci IConfiguration, abyste mohli číst konfigurační hodnoty.

Následující AppSettingsConfigurationRazor komponenta čte výchozí připojovací řetězec databáze a výchozí konfiguraci na úrovni protokolování. IConfiguration se vloží do horní části komponenty a používá se ke čtení konfiguračních hodnot. Oddělovač dvojtečky (:) se používá v konfiguračních klíčích typu řetězec k vyhledání odpovídajících vlastností JSON. Například struktura JSON pro výchozí objekt připojovacího řetězce (DefaultConnection) je vnořená pod objektem připojovacích řetězců (ConnectionStrings), takže zápis řetězce pro přístup k výchozímu připojovacímu řetězci používá dvojtečku k oddělení DefaultConnection a ConnectionStrings v pořadí, v jakém se objekty zobrazují v souboru nastavení aplikace: ConnectionStrings:DefaultConnection.

Pages/AppSettingsConfiguration.razor:

@page "/app-settings-configuration"
@inject IConfiguration Config

<h1>App Settings Configuration</h1>

<ul>
    <li>Default Connection String: @Config["ConnectionStrings:DefaultConnection"]
    <li>Default Log Level: @Config["Logging:LogLevel:Default"]
</ul>

Stejný přístup se používá v modelu stránky Pages:Razor

using Microsoft.Extensions.Configuration;

...

public class AppSettingsPageModel(IConfiguration config) : PageModel
{
    public ContentResult OnGet()
    {
        var defaultConnectionString = config["ConnectionStrings:DefaultConnection"];
        var defaultLogLevel = config["Logging:LogLevel:Default"];

        return Content(
            $"Default Connection String: {defaultConnectionString}\n" +
            $"Default Log Level: {defaultLogLevel}");
    }
}

Výchozí JsonConfigurationProvider konfigurace se načítá v následujícím pořadí:

1. appsettings.json
2. appsettings.{ENVIRONMENT}.json, kde {ENVIRONMENT} zástupný symbol je prostředí aplikace (příklady: appsettings.Production.json, appsettings.Development.json). Verze tohoto souboru pro prostředí se načte na základě IHostingEnvironment.EnvironmentName.

Hodnoty appsettings.{ENVIRONMENT}.json přepíšou hodnoty klíčů v appsettings.json.

Standardně:

• Ve vývojovém prostředí konfigurace appsettings.Development.json přepíše hodnoty, které jsou nalezeny v appsettings.jsonsouboru.
• V produkčním prostředí appsettings.Production.json konfigurace přepíše hodnoty nalezené v appsettings.json souboru.

Předchozí příklad jen čte řetězce a nepodporuje výchozí hodnotu. Pokud musí být hodnota konfigurace zaručena s výchozí hodnotou, přečtěte si část Extrakce jedné hodnoty z konfigurace pomocí převodu typu (GetValue).

Při použití výchozí konfigurace zdrojů aplikace jsou soubory appsettings.json a appsettings.{ENVIRONMENT}.json povoleny, když je nastaveno [nastavení] reloadOnChange na true. To znamená, že změny provedené v souborech appsettings.json nebo appsettings.{ENVIRONMENT}.json se projeví okamžitě po uložení.

Komentáře v appsettings.json a appsettings.{ENVIRONMENT}.json souborech se podporují pomocí komentářů ve stylu JavaScriptu nebo C#. Některá integrovaná vývojová prostředí (IDE) zobrazují chyby při úpravách souboru JSON obsahujícího komentáře, protože oficiální specifikace JSON (RFC 7159) neumožňuje komentáře v souborech JSON. Obvykle můžete ignorovat chyby a upozornění související s komentáři, ale obvykle můžete také zakázat upozornění nebo chyby pomocí nastavení v integrovaném vývojovém prostředí (IDE). V editoru Visual Studio Code například přidejte do settings.json souboru následující kód, aby se chyby zakázaly:

"files.associations": {
  "appsettings*.json": "jsonc"
}

Předchozí nastavení označuje VS Code, že soubory nastavení aplikace, včetně souborů založených na prostředí, jsou přidružené k formátu souboru JSONC (JSON s komentáři), který podporuje komentáře.

Pro jiná integrovaná vývojová prostředí (IDE) nahlédněte do dokumentace k vývojovému prostředí a do kanálů podpory produktů, abyste zjistili, jak vypnout chyby nebo varování týkající se komentářů v souborech JSON.

Zprostředkovatel konfigurace systémových proměnných

Výchozí zprostředkovatel konfigurace proměnných prostředí (EnvironmentVariablesConfigurationProvider) načte konfiguraci z proměnných prostředí, které nemají předponu ASPNETCORE_ nebo DOTNET_. Další informace o proměnných prostředí ASPNETCORE_ a DOTNET_ najdete v sekci Výchozí zdroje konfigurace hostitele a DOTNET_ proměnné prostředí (dokumentace k .NET Core).

Pomocí výchozího zprostředkovatele konfigurace proměnných prostředí načte aplikace konfiguraci z párů klíč-hodnota proměnné po přečtení appsettings.json, appsettings.{ENVIRONMENT}.json a uživatelských tajemství. Proto hodnoty klíčů načtené z prostředí přepisují hodnoty načtené z appsettings.json, appsettings.{ENVIRONMENT}.json a tajných kódů uživatelů.

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 v Bashi. Dvojité podtržítko, __ je podporováno všemi platformami a automaticky nahrazeno dvojtečkou, :.

Pokyny k nastavení proměnných prostředí v příkazovém prostředí ve Windows nebo v příkazovém prostředí PowerShellu pro různé platformy najdete v následujících materiálech:

• set (proměnná prostředí)
• setx
• about_Environment_Variables (dokumentace k PowerShellu)

Vlastní předpona pro proměnné prostředí

Můžete přidat zprostředkovatele konfigurace pro proměnné prostředí s vlastní předponou. V souboru Program zavolejte AddEnvironmentVariables s řetězcem pro určení předpony po zavolání WebApplication.CreateBuilder. Poskytovatel je přidán za výchozí poskytovatele konfigurace, takže nový poskytovatel má vyšší prioritu, a to i vůči proměnným prostředí se stejným názvem bez předpony.

V následujícím příkladu se proměnné prostředí přidají s předponou CustomPrefix_ :

builder.Configuration.AddEnvironmentVariables(prefix: "CustomPrefix_");

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

Nastavení spuštění přepisují nastavení proměnných prostředí.

Proměnné prostředí nastavené v launchSettings.json přepisují proměnné nastavené v systémovém prostředí. Například webové šablony ASP.NET Core vygenerují soubor launchSettings.json, který nastaví konfiguraci koncových bodů takto:

"applicationUrl": "https://localhost:5001;http://localhost:5000"

Nakonfigurování applicationUrl nastaví proměnnou prostředí ASPNETCORE_URLS a přepíše hodnoty nastavené v prostředí.

Uvozování proměnných prostředí v Linuxu

V Linuxu musí být hodnota adresy URL proměnných prostředí uvozena řídicím znakem, aby ji mohl systemd parsovat. V následujícím příkladu se nástroj systemd-escape Pro Linux používá k výnosu http:--localhost:5001 z http://localhost:5001:

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Nastavení aplikace Azure App Service (proměnné prostředí)

Pokyny k nastavení aplikací služby Azure App Service (proměnná prostředí) najdete v následujících zdrojích informací:

• Konfigurace aplikace App Service (dokumentace k Azure)
• Předpony připojovacího řetězce databáze Azure

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 následující tabulce se načtou do aplikace s výchozí konfigurací nebo když do aplikace není zadána žádná předpona AddEnvironmentVariables.

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

Když je proměnná prostředí objevena a načtena do konfigurace s některou ze čtyř předpon zobrazených v předchozí 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 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

Command-line

Pomocí výchozích zdrojů konfigurace se CommandLineConfigurationProvider načte konfigurace z párů klíč-hodnota argumentu příkazového řádku za následujícími zdroji konfigurace:

• Soubory appsettings.json a appsettings.{ENVIRONMENT}.json.
• Tajné kódy aplikací 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é všemi ostatními zprostředkovateli konfigurace.

Argumenty příkazového řádku

Následující dotnet run příkaz nastaví klíče a hodnoty pomocí znaménka rovná se (=):

dotnet run ConnectionStrings:DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;" Logging:LogLevel:Default=Information

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

dotnet run /ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" /Logging:LogLevel:Default Information

Následující příkaz nastaví klíče a hodnoty pomocí dvojitých pomlček (--):

dotnet run --ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" --Logging:LogLevel:Default Information

Konvence argumentů:

• Hodnota klíče musí následovat za znaménkem rovná se (=) nebo musí mít předponu dvojité pomlčky (--) nebo lomítka (/), pokud hodnota následuje za mezerou.
• Nepřiřazení hodnoty za znaménkem rovná se (=) způsobí přiřazení prázdného řetězce pro konfigurační nastavení. Například zadaní ConnectionStrings:DefaultConnection= je platné a výsledkem je přiřazení prázdného řetězce k výchozímu připojovacímu řetězci.
• Ve stejném příkazu nekombinujte páry klíč-hodnota argumentu oddělené znaménkem rovná se (=) s páry klíč-hodnota oddělené mezerou.

Mapování přepínačů

Mapování přepínačů umožňuje logiku nahrazení jmen klíčů pomocí slovníku záměn předaného metodě AddCommandLine.

Při použití slovníku mapování přepínačů se ve slovníku hledá klíč, který odpovídá klíči poskytnutému argumentem příkazového řádku. Pokud je klíč příkazového řádku nalezen ve slovníku, je hodnota ze slovníku předána zpět k nastavení páru klíč-hodnota do konfigurace aplikace. Mapování přepínačů je vyžadováno pro všechny klíče příkazových řádků s předponou s jednou pomlčkou (-).

Základní pravidla slovníku mapování přepínačů:

• Přepínače musí začínat jednou pomlčkou (-) nebo dvojitou čárkou (--).
• Slovník mapování přepínačů nesmí obsahovat duplicitní klíče.

V následujícím příkladu je slovník mapování přepínačů (switchMappings) předán do AddCommandLine souboru aplikace Program:

var switchMappings = 
    new Dictionary<string, string>(){ { "-k1", "key1" }, { "-k2", "key2" } };

builder.Configuration.AddCommandLine(args, switchMappings);

Následující dotnet run příkazy ukazují nahrazení klíče (value1 do key1 a value2 do key2):

• dotnet run -k1 value1 -k2 value2
• dotnet run --k1=value1 --k2=value2
• dotnet run --k1 value1 --k2 value2
• dotnet run /k1=value1 /k2=value2
• dotnet run /k1 value1 /k2 value2

U aplikací, které používají mapování přepínačů, by volání CreateDefaultBuilder nemělo předávat argumenty. Volání CreateDefaultBuilder metody AddCommandLine nezahrnuje mapované přepínače a neexistuje žádný způsob, jak předat slovník mapování přepínačů do CreateDefaultBuilder. Řešení není předávat argumenty do CreateDefaultBuilder, ale místo toho umožnit metodě ConfigurationBuilder metody AddCommandLine zpracovávat argumenty i slovník mapování přepínačů.

Nastavení argumentů prostředí a příkazového řádku pomocí sady Visual Studio

Argumenty prostředí a příkazového řádku lze nastavit v sadě Visual Studio z dialogového okna pro spouštění profilů:

• V Průzkumníku řešení klikněte pravým tlačítkem na projekt a vyberte Vlastnosti.
• Vyberte kartu Ladění > Obecné a vyberte Otevřít uživatelské rozhraní pro ladění profilů spouštění.

Zprostředkovatel konfigurace souborů

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 INI
• Zprostředkovatel konfigurace JSON
• Zprostředkovatel konfigurace XML

Zprostředkovatel konfigurace INI

Načte IniConfigurationProvider konfiguraci z párů klíč-hodnota souboru INI. Následující příklad ukazuje, jak použít zprostředkovatele. Přetížení mohou určit, zda je soubor volitelný a zda se konfigurace znovu načte při změnách souboru.

IniConfig.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;"

[Logging:LogLevel]
Default=Debug
Microsoft=Debug

IniConfig.Production.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLProd;"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Načtěte konfiguraci voláním AddIniFile. Následující příklad vytvoří zdroj konfigurace pro každý z předchozích souborů. Soubor mimo prostředí znovu načte konfiguraci, pokud je soubor změněn (reloadOnChange parametr, výchozí: false). Verze souboru prostředí určuje, že soubor je volitelný (optional parametr, výchozí hodnota: false). Pokud chcete zadat opětovné načtení souboru při změně (reloadOnChange: true), musíte také určit, zda je soubor nepovinný (optional).

builder.Configuration
    .AddIniFile("IniConfig.ini", optional: false, reloadOnChange: true);
    .AddIniFile($"IniConfig.{builder.Environment.EnvironmentName}.ini", optional: true);

Zprostředkovatel konfigurace JSON

Načte JsonConfigurationProvider konfiguraci z párů klíč-hodnota souboru JSON. Následující příklad ukazuje, jak použít zprostředkovatele. Přetížení mohou určit, zda je soubor volitelný a zda se konfigurace znovu načte při změnách souboru.

Volání AddJsonFile s cestou k souboru (nebo názvem souboru, pokud se soubor nachází v kořenovém adresáři aplikace). V následujícím příkladu je soubor volitelný (optional parametr, výchozí: false) a určuje, že se konfigurace znovu načte, pokud se soubor změní (reloadOnChange parametr, výchozí: false). Pokud chcete zadat opětovné načtení souboru při změně (reloadOnChange: true), musíte také určit, zda je soubor nepovinný (optional).

builder.Configuration.AddJsonFile("config.json", optional: true, reloadOnChange: true);

Zprostředkovatel konfigurace XML

Načte XmlConfigurationProvider konfiguraci z párů klíč-hodnota souboru XML. Následující příklad ukazuje, jak použít zprostředkovatele. Přetížení mohou určit, zda je soubor volitelný a zda se konfigurace znovu načte při změnách souboru.

XmlFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnection>Data Source=LocalSqlServer\\MSSQLDev;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Debug</Default>
      <Microsoft>Debug</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

XmlFile.Production.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnectionString>Data Source=LocalSqlServer\\MSSQLProd;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Načtěte konfiguraci voláním AddXmlFile. Následující příklad vytvoří zdroj konfigurace pro každý z předchozích souborů. Soubor mimo prostředí znovu načte konfiguraci, pokud je soubor změněn (reloadOnChange parametr, výchozí: false). Verze souboru prostředí určuje, že soubor je volitelný (optional parametr, výchozí hodnota: false). Pokud chcete zadat opětovné načtení souboru při změně (reloadOnChange: true), musíte také určit, zda je soubor nepovinný (optional).

builder.Configuration
    .AddXmlFile("XmlFile.xml", optional: false, reloadOnChange: true);
    .AddXmlFile($"XmlFile.{builder.Environment.EnvironmentName}.xml", optional: true);

Opakující se elementy, které používají stejný název elementu, fungují, pokud je k jejich odlišení použit atribut name:

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

var value_00 = Config["section:section0:key:key0"];
var value_01 = Config["section:section0:key:key1"];
var value_10 = Config["section:section1:key:key0"];
var value_11 = Config["section:section1:key:key1"];

Podporují se atributy, které poskytují hodnoty:

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

Předchozí konfigurace načte následující klíče:value

• key:attribute
• section:key:attribute

Zprostředkovatel konfigurace s klíčem pro každý soubor

KeyPerFileConfigurationProvider používá soubory v adresáři jako konfigurační páry klíč-hodnota. Klíč je název souboru. Hodnota obsahuje obsah souboru. Zprostředkovatel konfigurace klíče pro jednotlivé soubory 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.

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
builder.Configuration.AddKeyPerFile(directoryPath: path, optional: true);

Zprostředkovatel konfigurace 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:

var configSettings = new Dictionary<string, string>
{
    { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
    { "Logging:LogLevel:Default", "Information" }
};

builder.Configuration.AddInMemoryCollection(configSettings);

Další příklad, který používá prvek MemoryConfigurationProvider, naleznete v části Vazba pole.

Konfigurace koncového bodu Kestrel

KestrelKonfigurace konkrétního koncového bodu přepíše všechny konfigurace koncových bodů mezi servery . Konfigurace koncových bodů mezi servery zahrnují následující:

• UseUrls.
• --urls na příkazovém řádku.
• ASPNETCORE_URLS prostředí.

Vezměte v úvahu následující konfigurační oddíl Kestrel v souboru appsettings.json:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:9999"
    }
  }
},

Aplikace se spustí na příkazovém řádku s dotnet run a s následující konfigurací koncového bodu pro více serverů:

dotnet run --urls="https://localhost:7777"

Kestrel se váže na koncový bod nastavený specificky pro Kestrel v souboru appsettings.json (https://localhost:9999) a nikoliv na konfiguraci koncového bodu mezi servery předanou příkazu dotnet run (https://localhost:7777).

Zvažte ale Kestrel-specifický koncový bod, který je nakonfigurován jako proměnná prostředí:

• Klíč: Kestrel__Endpoints__Https__Url
• Hodnota: https://localhost:8888

V předchozí proměnné prostředíHttps je název koncového bodu specifického proKestrel. Předchozí konfigurace nastavení aplikace také definuje Kestrelkonkrétní koncový bod s názvem Https. Podle výchozích zprostředkovatelů konfigurace hostitele se proměnné prostředí načítají z po appsettings.{ENVIRONMENT}.json. Proto se předchozí proměnná prostředí (Kestrel__Endpoints__Https__Url) používá pro koncový bod (Https).

Extrahování jedné hodnoty z konfigurace pomocí převodu typu (GetValue)

ConfigurationBinder.GetValue extrahuje jednu hodnotu z konfigurace s určeným klíčem a převede ji na určený typ:

var number = Config.GetValue<int>("NumberKey", 99);

V předchozím kódu:

• Config je injektovaný IConfiguration.
• Pokud NumberKey se v konfiguraci nenajde, použije se výchozí hodnota 99 .

Práce s oddíly, získání podřízených oddílů a určení, jestli oddíl existuje

V následujících příkladech si vezměme následující soubor subsection.json:

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

Zprostředkovatel konfigurace je přidán voláním subsection.json pro AddJsonFile.

GetSection

IConfiguration.GetSection vrátí pododdíl konfigurace s určeným klíčem pododdílu.

Následující kód vrátí hodnoty pro section1, kde Config je vložen IConfiguration:

var subsection = Config.GetSection("section1");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

Následující kód vrátí hodnoty pro section2:subsection0, kde Config je vložen IConfiguration:

var subsection = Config.GetSection("section2:subsection0");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

GetSection nikdy nevrací hodnotu null. Pokud není nalezen odpovídající oddíl, je vrácena prázdná hodnota IConfigurationSection.

Když GetSection vrátí odpovídající oddíl, hodnota Value není vyplněna. Když oddíl existuje, vrátí se Key a Path.

GetChildren a Exists

Následující kód volá

• ConfigurationExtensions.Exists a ověřte, že section2 existuje.
• IConfiguration.GetChildren a vrací hodnoty pro pododdíly section2.

var section = Config.GetSection("section2");

if (!section.Exists())
{
    throw new Exception("section2 doesn't exist!");
}

var children = section.GetChildren();

foreach (var subSection in children)
{
    int i = 0;
    var key1 = subSection.Key + ":key" + i++.ToString();
    var key2 = subSection.Key + ":key" + i.ToString();
    Console.WriteLine($"{key1} value: {section[key1]}");
    Console.WriteLine($"{key2} value: {section[key2]}");
}

Výstup:

no-loc text="pododdíl0:klíč0 hodnota: hodnota200":::
no-loc text="pododdíl0:klíč1 hodnota: hodnota201":::
no-loc text="pododdíl1:klíč0 hodnota: hodnota210":::
no-loc text="pododdíl1:klíč1 hodnota: hodnota211":::

Navázání pole

ConfigurationBinder.Bind podporuje vazby polí na objekty pomocí indexů polí v konfiguračních klíčích. Jakýkoli formát pole, který vystavuje číselný segment klíče, může vytvořit vazbu pole na pole třídy POCO.

array.json:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

Zprostředkovatel konfigurace je přidán voláním array.json pro AddJsonFile.

Následující kód přečte konfigurační hodnoty:

ArrayExample.cs:

public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

var array = Config.GetSection("array").Get<ArrayExample>();

if (array is null)
{
    throw new ArgumentNullException(nameof(array));
}

string output = String.Empty;

for (int j = 0; j < array.Entries?.Length; j++)
{
    Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
}

Výstup:

Index: 0 Value: value00
Index: 1 Value: value10
Index: 2 Value: value20
Index: 3 Value: value40
Index: 4 Value: value50

V předchozím výstupu má Index 3 hodnotu value40, která odpovídá "4": "value40", v array.json. Indexy navázaného pole jsou souvislé a nejsou vázány na index konfiguračního klíče. Konfigurační vazebník nedokáže vázat hodnoty null ani vytvořit položky null ve vázaných objektech.

Vlastní zprostředkovatel konfigurace

Ukázková aplikace ukazuje, jak vytvořit základního zprostředkovatele konfigurace, který čte konfigurační páry klíč-hodnota z databáze pomocí Entity Framework (EF).

Zprostředkovatel má následující vlastnosti:

• Pro účely ukázky se používá databáze EF v paměti. Pokud chcete použít databázi, která vyžaduje připojovací řetězec, implementujte sekundární ConfigurationBuilder k poskytnutí připojovacího řetězce z jiného zprostředkovatele konfigurace.
• Zprostředkovatel při spuštění přečte databázovou tabulku do konfigurace. Zprostředkovatel neprovádí dotazy do databáze pro jednotlivé klíče.
• Možnost opětovného načtení při změně není implementována, takže aktualizace databáze po spuštění aplikace nemá na konfiguraci aplikace žádný vliv.

Definujte entitu EFConfigurationValue pro ukládání konfiguračních hodnot do databáze.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; } = string.Empty;
    public string Value { get; set; } = string.Empty;
}

Přidejte EFConfigurationContext pro ukládání a přístup k nakonfigurovaným hodnotám.

EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(
        DbContextOptions<EFConfigurationContext> options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

Vytvořte třídu, která implementuje IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => 
        _optionsAction = optionsAction;

    public IConfigurationProvider Build(IConfigurationBuilder builder) => 
        new EFConfigurationProvider(_optionsAction);
}

Vytvořte vlastního zprostředkovatele konfigurace děděním hodnot z ConfigurationProvider. Zprostředkovatel konfigurace inicializuje databázi, když je prázdná. Vzhledem k tomu, že konfigurační klíče nerozlišují malá a velká písmena, vytvoří se slovník použitý k inicializaci databáze pomocí porovnání nerozlišujícího velká a malá písmena StringComparer.OrdinalIgnoreCase.

EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            if (dbContext == null || dbContext.Values == null)
            {
                throw new Exception("Null DB context");
            }
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues =
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                    { "quote1", "I aim to misbehave." },
                    { "quote2", "I swallowed a bug." },
                    { "quote3", "You can't stop the signal, Mal." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue
            {
                Id = kvp.Key,
                Value = kvp.Value
            })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Rozšiřující metoda AddEFConfiguration umožňuje přidání zdroje konfigurace do ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
               this IConfigurationBuilder builder,
               Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Následující kód ukazuje, jak použít vlastní EFConfigurationProvider v souboru aplikace Program:

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

Příklad přístupu ke konfiguraci pomocí výhodných metod při spouštění viz Spuštění aplikace: výhodné metody.

Přidání konfigurace z externího sestavení

Implementace IHostingStartup umožňuje přidávat vylepšení aplikace při spuštění z externího sestavení mimo třídu Startup aplikace. Další informace viz Použití hostujících spouštěcích sestavení v ASP.NET Core.

Generátor zdrojů vazby konfigurace

Generátor zdroje vazby konfigurace poskytuje AOT a konfiguraci přívětivou pro oříznutí. Další informace naleznete v tématu Generátor zdrojů vazby konfigurace.

Dodatečné zdroje

• Konfigurace Blazor pro ASP.NET Core
• Zdrojový kód konfigurace
• Zobrazení nebo stažení ukázkového kódu (postup stažení)
• Vzor možností v ASP.NET Core