Konfigurace v ASP.NET Core

Autoři: Rick Anderson a Kirk Larkin

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í
• Azure Key Vault
• Azure App Configuration
• Argumenty příkazového řádku
• Vlastní zprostředkovatelé, nainstalovaní nebo vytvoření
• Soubory adresáře
• 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 konzoly viz Konfigurace .NET.

Pokyny Blazor ke konfiguraci, které přidávají nebo nahrazují pokyny v tomto uzlu, najdete v tématu ASP.NET Blazor Základní konfigurace.

Konfigurace aplikace a hostitele

Aplikace ASP.NET Core konfigurují a spouští hostitele. Tento hostitel je zodpovědný za spouštění aplikací a správu doby života. Šablony ASP.NET Core vytvoří třídu WebApplicationBuilder, která bude hostitele obsahovat. Ačkoli některé konfigurace lze provádět ve zprostředkovatelích konfigurace hostitele i aplikace, obecně platí, že v konfiguraci hostitele by se měla provádět pouze konfigurace nezbytná pro tohoto hostitele.

Konfigurace aplikace má nejvyšší prioritu a je podrobně popsána v následující části. Konfigurace hostitele následuje po konfiguraci aplikace a je popsána v tomto článku.

Výchozí zdroje konfigurace aplikace

Webové aplikace ASP.NET Core vytvořené pomocí příkazu dotnet new nebo sady Visual Studio generují následující kód:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder inicializuje novou instanci třídy WebApplicationBuilder s předkonfigurovanými výchozími hodnotami. Inicializovaná třída WebApplicationBuilder (builder) poskytuje výchozí konfiguraci aplikace v následujícím pořadí od nejvyšší po nejnižší prioritu:

1. Argumenty příkazového řádku používající zprostředkovatele konfigurace v příkazovém řádku.
2. Proměnné prostředí bez předpon používající zprostředkovatele konfigurace pro proměnné prostředí bez předpon.
3. Tajné kódy uživatelů, když aplikace běží v prostředí Development.
4. appsettings.{Environment}.jsonpomocí zprostředkovatele konfigurace JSON. Příklad: appsettings.Production.json a appsettings.Development.json.
5. appsettings.json pomocí zprostředkovatele konfigurace JSON.
6. Nouzový přechod do konfigurace hostitele popsané v další části.

Výchozí zdroje konfigurace hostitele

Následující seznam obsahuje výchozí zdroje konfigurace hostitele od nejvyšší po nejnižší prioritu pro WebApplicationBuilder:

1. Argumenty příkazového řádku používající zprostředkovatele konfigurace v příkazovém řádku.
2. Proměnné prostředí s předponou DOTNET_ používající zprostředkovatele konfigurace pro proměnné prostředí.
3. Proměnné prostředí s předponou ASPNETCORE_ používající zprostředkovatele konfigurace pro proměnné prostředí.

U obecného hostitele a webového hostitele .NET jsou výchozí zdroje konfigurace hostitele od nejvyšší po nejnižší prioritu:

1. Proměnné prostředí s předponou ASPNETCORE_ používající zprostředkovatele konfigurace pro proměnné prostředí.
2. Argumenty příkazového řádku používající zprostředkovatele konfigurace v příkazovém řádku.
3. Proměnné prostředí s předponou DOTNET_ používající zprostředkovatele konfigurace pro proměnné prostředí.

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

Proměnné hostitele

Následující proměnné jsou uzamčeny na začátku při inicializaci příkazů builder hostitele a nelze je ovlivnit konfigurací aplikace:

• Název aplikace
• Název prostředí například Development, Production a Staging
• Kořen obsahu
• Kořen 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 z vlastnosti HostBuilderContext.Configuration ve zpětných voláních IHostBuilder.ConfigureAppConfiguration.

Všechna ostatní nastavení hostitele se načtou z konfigurace aplikace místo konfigurace hostitele.

URLS je jedním z mnoha běžných nastavení hostitele, které není spouštěcím nastavením. Stejně jako všechna ostatní nastavení hostitele, která nejsou uvedena v předchozím seznamu, se hodnoty URLS později přečtou z konfigurace aplikace. Konfigurace hostitele je nouzová možnost pro konfiguraci aplikace, takže konfiguraci hostitele lze použít k nastavení adres URLS, ale bude přepsána jakýmkoli zdrojem konfigurace v konfiguraci aplikace, jako je například appsettings.json.

Další informace viz Změna kořene obsahu, názvu aplikace a prostředí a Změna kořene obsahu, názvu aplikace a prostředí pomocí proměnných prostředí nebo příkazového řádku.

Zbývající části tohoto článku se týkají konfigurace aplikace.

Zprostředkovatelé konfigurace aplikace

Následující kód zobrazuje povolené zprostředkovatele konfigurace v pořadí, v jakém byli přidáni:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

Předchozí seznam výchozích zdrojů konfigurace v pořadí od nejvyšší po nejnižší prioritu zobrazuje zprostředkovatele v opačném pořadí, než v jakém jsou přidáváni do aplikace generované šablonou. Například zprostředkovatel konfigurace JSON se přidá před zprostředkovatele konfigurace příkazového řádku.

Později přidaní zprostředkovatelé konfigurace mají vyšší prioritu a přepisují předchozí nastavení klíče. Například pokud je hodnota MyKey nastavena v souboru appsettings.json i v prostředí, použije se hodnota prostředí. Při používání výchozích zprostředkovatelů konfigurace přepíše zprostředkovatel konfigurace v příkazovém řádku všechny ostatní zprostředkovatele.

Další informace o CreateBuilder viz Výchozí nastavení pro builder.

appsettings.json

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

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Následující kód z ukázkového stažení zobrazí několik předchozích nastavení konfigurace:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Výchozí JsonConfigurationProvider načte konfiguraci v následujícím pořadí:

1. appsettings.json
2. appsettings.{Environment}.json: Například soubory appsettings.Production.json a appsettings.Development.json. Verze tohoto souboru pro prostředí se načte na základě IHostingEnvironment.EnvironmentName. Další informace viz Použití více prostředí v ASP.NET Core.

Hodnoty appsettings.{Environment}.json přepíšou hodnoty klíčů v appsettings.json. Například ve výchozím nastavení:

• Ve vývojovém prostředí přepíše konfigurace appsettings.Development.json hodnoty v appsettings.json.
• V produkčním prostředí přepíše konfigurace appsettings.Production.json hodnoty v appsettings.json. Například při nasazování aplikace do Azure.

Pokud musí být nějaká hodnota konfigurace zaručena, podívejte se na GetValue. Předchozí příklad čte pouze řetězce a nepodporuje výchozí hodnotu.

Při použití výchozí konfigurace jsou soubory appsettings.json a appsettings.{Environment}.json povoleny pomocí reloadOnChange: true. Změny provedené v souboru appsettings.jsona appsettings.{Environment}.json po spuštění aplikace čtou poskytovatel konfigurace JSON.

Komentáře v appsettings.json

Komentáře v appsettings.json a appsettings.{Environment}.json souborech se podporují pomocí komentářů ve stylu JavaScriptu nebo C#.

Vytvoření vazby hierarchických konfiguračních dat pomocí vzoru možností

Upřednostňovaným způsobem čtení souvisejících hodnot konfigurace je použití vzoru možností. Pokud chcete například přečíst následující konfigurační hodnoty:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Vytvořte následující třídu PositionOptions:

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; } = String.Empty;
    public string Name { get; set; } = String.Empty;
}

Třída možností:

• Musí být neabstraktní s veřejným konstruktorem bez parametrů.
• Všechny veřejné vlastnosti pro čtení i zápis typu jsou vázané.
• Pole nejsou vázaná. V předchozím kódu není pole Position vázáno. Pole Position se používá, aby řetězec "Position" nemusel být v aplikaci pevně zakódován při vytváření vazby třídy na zprostředkovatele konfigurace.

Následující kód:

• Zavolá metodu ConfigurationBinder.Bind pro svázání třídy PositionOptions s oddílem Position.
• Zobrazí konfigurační data pole Position.

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

    public Test22Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

V předchozím kódu se ve výchozím nastavení změní konfigurační soubor JSON po spuštění aplikace.

ConfigurationBinder.Get<T> naváže a vrátí určený typ. ConfigurationBinder.Get<T> může být pohodlnější než použití ConfigurationBinder.Bind. Následující kód ukazuje, jak používat ConfigurationBinder.Get<T> s třídou PositionOptions:

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions? positionOptions { get; private set; }

    public Test21Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

V předchozím kódu se ve výchozím nastavení změní konfigurační soubor JSON po spuštění aplikace.

Alternativním přístupem při používání vzoru možností je vytvoření vazby oddílu Position a jeho přidání do kontejneru služby vkládání závislostí. V následujícím kódu se PositionOptions přidá do kontejneru služby s příkazem Configure a sváže se s konfigurací:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));

var app = builder.Build();

Pomocí předchozího kódu přečte následující kód možnosti pozice:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

V předchozím kódu se změny konfiguračního souboru JSON po spuštění aplikace nepřečtou. Pokud chcete po spuštění aplikace přečíst změny, použijte IOptionsSnapshot.

Při použití výchozí konfigurace jsou soubory appsettings.json a appsettings.{Environment}.json povoleny pomocí reloadOnChange: true. Změny provedené v souboru appsettings.jsona appsettings.{Environment}.json po spuštění aplikace čtou poskytovatel konfigurace JSON.

Informace o přidání dalších konfiguračních souborů JSON najdete v tomto dokumentu v zprostředkovateli konfigurace JSON.

Kombinování kolekce služeb

Vezměme například následující kód, který registruje služby a konfiguruje možnosti:

using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
    builder.Configuration.GetSection(ColorOptions.Color));

builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();

var app = builder.Build();

Související skupiny registrací lze přesunout do rozšiřující metody pro registraci služeb. Například konfigurační služby jsou přidány do následující třídy:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }

        public static IServiceCollection AddMyDependencyGroup(
             this IServiceCollection services)
        {
            services.AddScoped<IMyDependency, MyDependency>();
            services.AddScoped<IMyDependency2, MyDependency2>();

            return services;
        }
    }
}

Ostatní služby jsou registrovány v podobné třídě. Následující kód používá nové rozšiřující metody k registraci služeb:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddConfig(builder.Configuration)
    .AddMyDependencyGroup();

builder.Services.AddRazorPages();

var app = builder.Build();

Poznámka Každá rozšiřující metoda services.Add{GROUP_NAME} přidává a potenciálně konfiguruje služby. AddControllersWithViews například přidá kontrolery služeb MVC s požadavkem zobrazení a AddRazorPages přidá požadavky Razor Pages pro služby.

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

Ve výchozím nastavení se zdroj konfigurace tajných kódů uživatelů zaregistruje po zdrojích konfigurace JSON. 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:

• Používání více prostředí v ASP.NET Core
• 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.

Proměnné prostředí bez předpony

Proměnné prostředí bez předpony jsou proměnné prostředí, které nemají předponu ASPNETCORE_ nebo DOTNET_. Například šablony webových aplikací ASP.NET Core nastavují "ASPNETCORE_ENVIRONMENT": "Development" v launchSettings.json. Další informace o proměnných prostředí ASPNETCORE_ a DOTNET_ viz:

• Seznam výchozích zdrojů konfigurace od nejvyšší po nejnižší prioritu včetně proměnných prostředí bez předpony, s předponou ASPNETCORE_ a s předponou DOTNETCORE_.
• Proměnné prostředí s předponou DOTNET_ používané mimo Microsoft.Extensions.Hosting.

Při použití výchozí konfigurace načte EnvironmentVariablesConfigurationProvider konfiguraci z párů klíč-hodnota proměnných prostředí po přečtení appsettings.json, appsettings.{Environment}.json a tajných kódů uživatelů. 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. Bash například : nepodporuje oddělovač. Dvojité podtržítko je __:

• Podporuje všemi platformami.
• Automaticky nahrazen dvojtečka, :.

Následující příkazy:

• Nastaví klíče prostředí a hodnoty z předchozího příkladu ve Windows.
• Otestují nastavení při používání ukázkového stažení. Příkaz dotnet run musí být spuštěn v adresáři projektu.

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Předchozí nastavení prostředí:

• Je nastaveno pouze v procesech spuštěných z příkazového okna, ve kterém byly nastaveny.
• Nebudou přečteny prohlížeči spuštěnými pomocí sady Visual Studio.

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 MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Otestování, jestli předchozí příkazy přepisují appsettings.json a appsettings.{Environment}.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.

Zavolejte metodu AddEnvironmentVariables s řetězcem k určení předpony pro proměnné prostředí:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

V předchozím kódu:

• builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_") se přidá za výchozí zprostředkovatele konfigurace. Příklad řazení zprostředkovatelů konfigurace najdete v tématu Zprostředkovatel konfigurace JSON.
• Proměnné prostředí nastavené s předponou MyCustomPrefix_ 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.

Vlastní předponu otestujete následujícími příkazy:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Výchozí konfigurace načte proměnné prostředí a argumenty příkazového řádku s předponou DOTNET_ a ASPNETCORE_. Předpony DOTNET_ a ASPNETCORE_ se používají v ASP.NET Core pro konfiguraci hostitele a aplikace, ne však pro konfiguraci uživatelů. Další informace o konfiguraci hostitele a aplikace viz Obecný hostitel .NET.

V Azure App Service vyberte Nové nastavení aplikace na stránce Nastavení > Konfigurace. Nastavení aplikace Azure App Service se:

• Zašifrováno a přenášeno rest přes šifrovaný kanál.
• Vystavují jako proměnné prostředí.

Další informace viz Azure Apps: Přepsání konfigurace aplikace pomocí webu Azure Portal.

Informace o připojovacích řetězcích k databázi Azure viz Předpony připojovacích řetězců.

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

Názvy proměnných prostředí odráží strukturu souboru appsettings.json. Každý element v hierarchii je oddělen dvojitým podtržítkem (preferováno) nebo dvojtečkou. Pokud struktura elementů obsahuje pole, měl by být index pole považován za další název elementu na této cestě. Uvažujme následující soubor appsettings.json a jeho ekvivalentní hodnoty reprezentované jako proměnné prostředí.

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

Proměnné prostředí

setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information

Proměnné prostředí nastavené ve vygenerovaném souboru launchSettings.json

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. Použijte linuxový nástroj systemd-escape, který poskytuje http:--localhost:5001.

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

Zobrazení proměnných prostředí

Následující kód zobrazuje proměnné prostředí a hodnoty při spuštění aplikace, což může být užitečné při ladění nastavení prostředí:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

foreach (var c in builder.Configuration.AsEnumerable())
{
    Console.WriteLine(c.Key + " = " + c.Value);
}

Příkazový řádek

Při použití výchozí konfigurace načte CommandLineConfigurationProviderkonfiguraci z párů klíč-hodnota argumentů příkazového řádku po následujících zdrojích konfigurace:

• Soubory appsettings.json a appsettings.{Environment}.json.
• Tajné kódy aplikací ve vývojovém prostředí.
• Proměnné prostředí.

Ve výchozím nastavení hodnoty konfigurace nastavené v příkazovém řádku přepisují hodnoty konfigurace nastavené pomocí všech ostatních zprostředkovatelů konfigurace.

Argumenty příkazového řádku

Následující příkaz nastaví klíče a hodnoty pomocí =:

dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick

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

dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick

Následující příkaz nastaví klíče a hodnoty pomocí --:

dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick

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 MySetting=.

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.

Mapování přepínačů

Mapování přepínačů umožňuje používat logiku nahrazování názvů klíčů. Poskytněte slovník náhrad přepínačů 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í mít na začátku - nebo --.
• Slovník mapování přepínačů nesmí obsahovat duplicitní klíče.

Pokud chcete používat slovník mapování přepínačů, předejte ho do volání AddCommandLine:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

builder.Configuration.AddCommandLine(args, switchMappings);

var app = builder.Build();

Spuštěním následujícího příkazu otestujete nahrazení klíčů:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Následující kód zobrazuje hodnoty klíčů pro nahrazené klíče:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

U aplikací, které používají mapování přepínačů, by volání CreateDefaultBuilder nemělo předávat argumenty. Volání AddCommandLine metody CreateDefaultBuilder 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ě AddCommandLine metody ConfigurationBuilder 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í.

Hierarchická konfigurační data

Rozhraní API pro konfiguraci čte hierarchická konfigurační data tak, že hierarchická data zplošťuje pomocí oddělovače v konfiguračních klíčích.

Ukázkové stažení obsahuje následující soubor appsettings.json:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Následující kód z ukázkového stažení zobrazuje několik nastavení konfigurace:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Upřednostňovaným způsobem čtení hierarchických konfiguračních dat je použití vzoru možností. Další informace viz Vytvoření vazby hierarchických konfiguračních dat v tomto dokumentu.

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 dále v částech GetSection, GetChildren a Exists.

Konfigurační klíče a hodnoty

Upozorňující

Tento článek ukazuje použití připojovací řetězec. U místní databáze nemusí být uživatel ověřený, ale v produkčním prostředí připojovací řetězec někdy obsahují heslo k ověření. Přihlašovací údaje vlastníka prostředku (ROPC) jsou bezpečnostní riziko, kterému byste se měli vyhnout v produkčních databázích. 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ématu Zabezpečené toky ověřování.

Konfigurační klíče:

• Nerozlišují malá a velká písmena. Například ConnectionString a connectionstring se považují za ekvivalentní klíče.
• Pokud je klíč a hodnota nastaveny ve více než jednom poskytovateli 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í nemusí oddělovač dvojtečka fungovat na všech platformách. Dvojité podtržítko, __, je podporováno všemi platformami a je automaticky převáděno na dvojtečku :.
  • Ve službě Azure Key Vault používají hierarchické klíče -- jako oddělovač. Zprostředkovatel konfigurace Azure Key Vault při načtení tajných kódů do konfigurace aplikace automaticky nahradí oddělovače -- oddělovači :.
• ConfigurationBinder podporuje vazby polí na objekty pomocí indexů polí v konfiguračních klíčích. Vazba pole je popsána v části Vazba pole na třídu.

Konfigurační hodnoty:

• Jsou řetězce.
• Hodnoty null nelze uložit v konfiguraci ani svázat s objekty.

Poskytovatelé konfigurace

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

Poskytovatel	Poskytuje konfiguraci z
Zprostředkovatel konfigurace služby Azure Key Vault	Azure Key Vault
Zprostředkovatel konfigurace Azure App	Azure App Configuration
Zprostředkovatel konfigurace v příkazovém řádku	Parametry příkazového řádku
Vlastní zprostředkovatel konfigurace	Vlastní zdroj
Zprostředkovatel konfigurace pro proměnné prostředí	Proměnné prostředí
Zprostředkovatel konfigurace v souboru	Soubory INI, JSON a XML
Zprostředkovatele konfigurace „klíč na soubor“	Soubory adresáře
Zprostředkovatel konfigurace v paměti	Kolekce v paměti
Tajné klíče 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. appsettings.json
2. appsettings.{Environment}.json
3. Tajné klíče uživatelů
4. Proměnné prostředí používající zprostředkovatele konfigurace pro proměnné prostředí.
5. Argumenty příkazového řádku používající zprostředkovatele konfigurace v příkazovém řádku.

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

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

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

Upozorňující

Tento článek ukazuje použití připojovací řetězec. U místní databáze nemusí být uživatel ověřený, ale v produkčním prostředí připojovací řetězec někdy obsahují heslo k ověření. Přihlašovací údaje vlastníka prostředku (ROPC) jsou bezpečnostní riziko, kterému byste se měli vyhnout v produkčních databázích. 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ématu Zabezpečené toky ověřování.

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 uvedenými v tabulce jsou do aplikace načteny s výchozí konfigurací nebo pokud není do AddEnvironmentVariables poskytnuta žádná předpona.

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

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

Zprostředkovatel konfigurace v souboru INI

IniConfigurationProvider načte konfiguraci z párů klíč-hodnota v souboru INI za běhu.

Následující kód přidá několik zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

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

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

V předchozím kódu jsou nastavení v souborech MyIniConfig.ini a MyIniConfig.{Environment}.ini přepsána nastaveními ve zprostředkovatelích:

• Zprostředkovatel konfigurace pro proměnné prostředí.
• Zprostředkovatel konfigurace v příkazovém řádku.

Ukázkové stažení obsahuje následující soubor MyIniConfig.ini:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Následující kód z ukázkového stažení zobrazí několik předchozích nastavení konfigurace:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Zprostředkovatel konfigurace JSON

Načte JsonConfigurationProvider konfiguraci z párů klíč-hodnota souboru JSON.

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.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Předchozí kód:

• Nakonfiguruje zprostředkovatele konfigurace JSON tak, aby soubor MyConfig.json načetl s následujícími možnostmi:
  • optional: true: Soubor je volitelný.
  • reloadOnChange: true: Soubor se znovu načte při uložení změn.
• Přečte výchozí zprostředkovatele konfigurace před souborem MyConfig.json. Nastavení v souboru MyConfig.json přepisují nastavení ve výchozích zprostředkovatelích konfigurace včetně zprostředkovatele konfigurace pro proměnné prostředí a zprostředkovatele konfigurace v příkazovém řádku.

Obvykle nechcete, aby vlastní soubor JSON přepisuje hodnoty nastavené ve zprostředkovateli konfigurace proměnných prostředí a zprostředkovatel konfigurace příkazového řádku.

Zprostředkovatel konfigurace v souboru XML

XmlConfigurationProvider načte konfiguraci z párů klíč-hodnota v souboru XML za běhu.

Následující kód přidá několik zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

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

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

V předchozím kódu jsou nastavení v souborech MyXMLFile.xml a MyXMLFile.{Environment}.xml přepsána nastaveními ve zprostředkovatelích:

• Zprostředkovatel konfigurace pro proměnné prostředí.
• Zprostředkovatel konfigurace v příkazovém řádku.

Ukázkové stažení obsahuje následující soubor MyXMLFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Následující kód z ukázkového stažení zobrazí několik předchozích nastavení konfigurace:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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>

Následující kód přečte předchozí konfigurační soubor a zobrazí klíče a hodnoty:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

    public IndexModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

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ř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 obsahuje 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((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.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:

var builder = WebApplication.CreateBuilder(args);

var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Následující kód z ukázkového stažení zobrazí předchozí nastavení konfigurace:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

V předchozím kódu se config.AddInMemoryCollection(Dict) přidá za výchozí zprostředkovatele konfigurace. Příklad řazení zprostředkovatelů konfigurace najdete v tématu Zprostředkovatel konfigurace JSON.

Další příklad použití zprostředkovatele MemoryConfigurationProvider viz Navázání pole.

Konfigurace koncového bodu Kestrel

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

• UseUrls
• --urls v příkazovém řádku
• Proměnná prostředí ASPNETCORE_URLS

Vezměme si například následující soubor appsettings.json použitý ve webové aplikaci ASP.NET Core:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
} 

Pokud je předchozí zvýrazněný kód použit ve webové aplikaci ASP.NET Core a aplikace je spuštěna z příkazového řádku s následující konfigurací koncových bodů mezi servery:

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

Kestrel se váže na koncový bod nakonfigurovaný konkrétně pro Kestrel v souboru appsettings.json (https://localhost:9999), a ne https://localhost:7777.

Vezměme si například konkrétní koncový bod Kestrel nakonfigurovaný jako proměnnou prostředí:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

V předchozí proměnné prostředí je Https název konkrétního koncového bodu Kestrel. Předchozí soubor appsettings.json také definuje konkrétní koncový bod Kestrel s názvem Https. Ve výchozím nastavení jsou proměnné prostředí používající zprostředkovatele konfigurace pro proměnné prostředí přečteny po souboru appsettings.{Environment}.json, proto se pro koncový bod Https použije předchozí proměnná prostředí.

GetValue

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

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

    public TestNumModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Pokud se v předchozím kódu v konfiguraci nenajde NumberKey, použije se výchozí hodnota 99.

GetSection, GetChildren a Exists

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

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

Následující kód přidá MySubsection.json do zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

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:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

Následující kód vrátí hodnoty pro section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["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á IConfiguration.GetChildren a vrací hodnoty pro section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = "";
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Předchozí kód volá ConfigurationExtensions.Exists, aby se ověřilo, že oddíl existuje:

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.

Vezměme si například MyArray.json z ukázkového stažení:

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

Následující kód přidá MyArray.json do zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Následující kód přečte konfiguraci a zobrazí hodnoty:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample? _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
       _array = Config.GetSection("array").Get<ArrayExample>();
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }
        string s = String.Empty;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

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

Předchozí kód vrátí následující 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 MyArray.json. Indexy navázaného pole jsou souvislé a nejsou vázány na index konfiguračního klíče. Konfigurační vazač není schopen vázat hodnoty null nebo vytvářet 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á. Protože konfigurační klíče nerozlišují velká a malá písmena, je slovník použitý k inicializaci databáze vytvořen s porovnávačem nerozlišujícím 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ího zprostředkovatele EFConfigurationProvider v souboru Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

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

Konfigurace může být vložena do služeb pomocí vkládání závislostí překladem služby IConfiguration:

public class Service
{
    private readonly IConfiguration _config;

    public Service(IConfiguration config) =>
        _config = config;

    public void DoSomething()
    {
        var configSettingValue = _config["ConfigSetting"];

        // ...
    }
}

Informace o tom, jak získat přístup k hodnotám pomocí IConfiguration, viz části GetValue a GetSection, GetChildren a Exists v tomto článku.

Konfigurace přístupu v Razor Pages

Následující kód zobrazí konfigurační data na stránce Razor Page:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

V následujícím kódu se MyOptions přidá do kontejneru služby s příkazem Configure a sváže se s konfigurací:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

var app = builder.Build();

Následující kód používá direktivu Razor@inject k překladu a zobrazení hodnot možností:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Přístup ke konfiguraci v souboru zobrazení MVC

Následující kód zobrazí konfigurační data v zobrazení MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Přístup ke konfiguraci v Program.cs

Následující kód přistupuje ke konfiguraci v souboru Program.cs.

var builder = WebApplication.CreateBuilder(args);

var key1 = builder.Configuration.GetValue<string>("KeyOne");

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");

app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);

app.Run();

V appsettings.json předchozím příkladu:

{
  ...
  "KeyOne": "Key One Value",
  "KeyTwo": 1999,
  "KeyThree": true
}

Konfigurace možností pomocí delegáta

Možnosti nakonfigurované v delegátovi přepisují hodnoty nastavené ve zprostředkovatelích konfigurace.

V následujícím kódu je do kontejneru služby přidána služba IConfigureOptions<TOptions>. Pomocí delegáta konfiguruje hodnoty pro MyOptions:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "Value configured in delegate";
    myOptions.Option2 = 500;
});

var app = builder.Build();

Následující kód zobrazí hodnoty možností:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

V předchozím příkladu jsou hodnoty Option1 a Option2 určeny v appsettings.json a následně přepsány nakonfigurovaným delegátem.

Konfigurace hostitele vs. aplikace

Před konfigurací a spuštěním aplikace je nakonfigurován a spuštěn hostitel. Tento hostitel je zodpovědný za spouštění aplikací a správu doby života. Aplikace i hostitel se konfigurují pomocí zprostředkovatelů konfigurace popsaných v tomto tématu. Do konfigurace aplikace jsou zahrnuty také konfigurační páry klíč-hodnota hostitele. 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í konfigurace hostitele

Podrobnosti o výchozí konfiguraci při používání webového hostitele najdete ve verzi tohoto tématu pro ASP.NET Core 2.2.

• Konfigurace hostitele je poskytována z:
  • Proměnné prostředí s předponou DOTNET_ (například DOTNET_ENVIRONMENT) používající zprostředkovatele konfigurace pro proměnné prostředí. Když jsou načteny konfigurační páry klíč-hodnota, je předpona (DOTNET_) odstraněna.
  • Argumenty příkazového řádku používající zprostředkovatele konfigurace v příkazovém řádku.
• Vytvoří se výchozí konfigurace webového hostitele (ConfigureWebHostDefaults):
  • Kestrel se používá jako webový server a je nakonfigurovaný pomocí zprostředkovatelů konfigurace aplikace.
  • Přidejte middleware pro filtrování hostitelů.
  • Přidejte middleware předávaných hlaviček, pokud je proměnná prostředí ASPNETCORE_FORWARDEDHEADERS_ENABLED nastavena na true.
  • Povolte integraci se službou IIS.

Další konfigurace

Toto téma se týká pouze konfigurace aplikace. Další aspekty spouštění a hostování aplikací ASP.NET Core se konfigurují pomocí konfiguračních souborů, kterým se toto téma nevěnuje:

• launch.json/launchSettings.json jsou konfigurační soubory nástrojů pro vývojové prostředí popsané:
  • V tématu Použití více prostředí v ASP.NET Core.
  • V rámci dokumentace tam, kde se soubory používají ke konfiguraci aplikací ASP.NET Core pro scénáře vývoje.
• web.config je konfigurační soubor serveru popsaný v následujících tématech:
  • Hostování ASP.NET Core ve Windows pomocí služby IIS
  • Modul ASP.NET Core (ANCM) pro službu IIS

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

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

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.

Další materiály

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