Konfigurace v ASP.NET Core

Článek
07/05/2022
92 min ke čtení

Konfigurace aplikace v ASP.NET Core se provádí pomocí jednoho nebo více poskytovatelů konfigurace. Poskytovatelé konfigurace čtou konfigurační data z párů klíč-hodnota pomocí různých zdrojů konfigurace:

Soubory nastavení, například appsettings.json
Proměnné prostředí
Azure Key Vault
Azure App Configuration
Argumenty příkazového řádku
Vlastní poskytovatelé, nainstalované nebo vytvořené
Soubory adresáře
Objekty .NET v paměti

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

Konfigurace aplikací a hostitelů

ASP.NET Core aplikace nakonfigurují a spustí hostitele. Hostitel zodpovídá za správu spuštění a životnosti aplikace. Šablony ASP.NET Core vytvoří, WebApplicationBuilder který obsahuje hostitele. I když je možné provést určitou konfiguraci v hostiteli i poskytovatelích konfigurace aplikací, obecně platí, že v konfiguraci hostitele by se měla provést pouze konfigurace, která je nezbytná pro hostitele.

Konfigurace aplikace je nejvyšší prioritou a je podrobně popsána v další části. Konfigurace hostitele se řídí konfigurací aplikace a je popsána v tomto článku.

Výchozí zdroje konfigurace aplikací

ASP.NET Core webové aplikace vytvořené pomocí nového dotnetu nebo sady Visual Studio vygenerují následující kód:

var builder = WebApplication.CreateBuilder(args);

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

Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
Proměnné prostředí bez předpony používající poskytovatele konfigurace proměnných prostředí bez předpony.
Uživatelské tajné kódy při spuštění aplikace v Development prostředí.
appsettings.{Environment}.jsonJSpomocí zprostředkovatele konfigurace ON. Příklad: appsettings.Production.json a appsettings.Development.json.
appsettings.json pomocí JSzprostředkovatele konfigurace ON.
Náhradní 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:

ASPNETCORE_-předpona proměnných prostředí pomocí zprostředkovatele konfigurace proměnných prostředí.
Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
DOTNET_-předpona proměnných prostředí pomocí zprostředkovatele konfigurace proměnných prostředí.

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

Vysvětlení v tomto komentáři Na GitHubu najdete vysvětlení, proč v konfiguraci ASPNETCORE_ hostitele mají proměnné prostředí s předponou vyšší prioritu než argumenty příkazového řádku.

Proměnné hostitele

Při počáteční inicializaci tvůrce hostitelů jsou uzamčeny následující proměnné a nelze je ovlivnit konfigurací aplikace:

Název aplikace
Název prostředí, například Development, Productiona Staging
Kořen obsahu
Webový kořen
Zda chcete vyhledat hostování spouštěcích sestavení a sestavení, která se mají vyhledat.
Proměnné čtené podle kódu aplikace a knihovny z HostBuilderContext.Configuration v zpětných voláních IHostBuilder.ConfigureAppConfiguration .

Každé jiné nastavení hostitele se čte z konfigurace aplikace místo konfigurace hostitele.

URLS je jedním z mnoha běžných nastavení hostitele, které není nastavení bootstrap. Stejně jako každé jiné nastavení hostitele, které není v předchozím seznamu, URLS je přečteno později z konfigurace aplikace. Konfigurace hostitele je záložní součástí konfigurace aplikace, takže konfiguraci hostitele lze použít k nastavení URLS, ale přepíše se jakýmkoli zdrojem konfigurace v konfiguraci aplikace, jako je appsettings.json.

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

Zbývající části tohoto článku odkazují na konfiguraci aplikace.

Zprostředkovatelé konfigurace aplikací

Následující kód zobrazí povolené zprostředkovatele konfigurace v pořadí, v jakém byly přidány:

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 s nejvyšší prioritou zobrazuje poskytovatele v opačném pořadí, v jakém se přidají do vygenerované aplikace šablony. Například JSposkytovatel konfigurace ON se přidá před zprostředkovatele konfigurace příkazového řádku.

Poskytovatelé konfigurace přidaní později mají vyšší prioritu a přepsat předchozí nastavení klíče. Pokud je například MyKey nastavená v obou appsettings.json prostředích i v prostředí, použije se hodnota prostředí. Pomocí výchozích zprostředkovatelů konfigurace přepíše poskytovatel konfigurace příkazového řádku všechny ostatní zprostředkovatele.

Další informace najdete v CreateBuildertématu Výchozí nastavení tvůrce.

`appsettings.json`

Zvažte následující appsettings.json soubor:

{
  "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čtení konfigurace v následujícím pořadí:

appsettings.json
appsettings.{Environment}.json : Například soubory appsettings.Production.json a appsettings.Development.json soubory. Verze prostředí souboru se načte na IHostingEnvironment.EnvironmentNamezákladě . Další informace najdete v tématu Použití více prostředí v ASP.NET Core.

appsettings.{Environment}.json hodnoty přepisuje klíče v appsettings.json. Ve výchozím nastavení by například:

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

Pokud musí být zaručená hodnota konfigurace, přečtěte si téma GetValue. Předchozí příklad čte pouze řetězce a nepodporuje výchozí hodnotu.

Při použití výchozí konfigurace jsou povoleny soubory appsettings.json s appsettings.{Environment}.jsonopětovným načtenímOnChange: true. Změny provedené v souboru appsettings.json a appsettings.{Environment}.jsonpo spuštění aplikace načtou JSposkytovatel konfigurace ON.

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í PositionOptions třídu:

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

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

Třída options:

Nesmí být abstraktní s veřejným konstruktorem bez parametrů.
Všechny veřejné vlastnosti čtení a zápisu typu jsou vázané.
Pole nejsou vázána. V předchozím kódu Position není vázán. Toto Position pole se používá, takže řetězec "Position" nemusí být pevně zakódován v aplikaci při vazbě třídy k poskytovateli konfigurace.

Následující kód:

Volá ConfigurationBinder.Bind pro vytvoření vazbyPositionOptions třídy k oddílu Position .
Position Zobrazí konfigurační data.

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

Ve výchozím nastavení se v předchozím kódu změní konfigurační JSsoubor ON po spuštění aplikace.

ConfigurationBinder.Get<T> vytvoří vazbu a vrátí zadaný typ. ConfigurationBinder.Get<T> může být pohodlnější než použití ConfigurationBinder.Bind. Následující kód ukazuje, jak se používá ConfigurationBinder.Get<T> se PositionOptions třídou:

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

Ve výchozím nastavení se v předchozím kódu změní konfigurační JSsoubor ON po spuštění aplikace.

Alternativním přístupem při použití vzoru možností je vytvořit vazbu oddílu Position a přidat ho do kontejneru služby injektáže závislostí. V následujícím kódu PositionOptions se přidá do kontejneru služby s Configure vazbou na konfiguraci:

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 JSsouboru ON po spuštění aplikace nečtou . Pokud chcete číst změny po spuštění aplikace, použijte IOptionsSnapshot.

Při použití výchozí konfigurace appsettings.json jsou povolené soubory a appsettings.{Environment}.json soubory s opětovným načtenímOnChange: true. Změny provedené appsettings.json v souboru a appsettings.{Environment}.json po spuštění JSaplikace přečte poskytovatel konfigurace ON.

Informace o přidání dalších JSkonfiguračních souborů ON najdete v tomto dokumentu v tématu O poskytovateli konfigurace.JS

Kombinování kolekce služeb

Zvažte následující možnosti registrace služeb a konfigurace možností:

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í je možné přesunout do metody rozšíření pro registraci služeb. Konfigurační služby se například přidají 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;
        }
    }
}

Zbývající služby jsou zaregistrované v podobné třídě. Následující kód používá nové metody rozšíření 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á services.Add{GROUP_NAME} metoda rozšíření přidává a potenciálně konfiguruje služby. Přidá například AddControllersWithViews služby, které kontrolery MVC s zobrazeními vyžadují, a AddRazorPages přidá stránky služeb Razor . Doporučujeme, aby aplikace dodržovaly konvenci pojmenování vytváření metod rozšíření v Microsoft.Extensions.DependencyInjection oboru názvů. Vytváření metod rozšíření v Microsoft.Extensions.DependencyInjection oboru názvů:

Zapouzdřuje skupiny registrací služeb.
Poskytuje pohodlný přístup technologie IntelliSense ke službě.

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

Pokyny k konfiguračním datům:

Nikdy neukládáte hesla ani jiná citlivá data v kódu zprostředkovatele konfigurace nebo v konfiguračních souborech prostého textu. Nástroj Secret Manager se dá použít k ukládání tajných kódů ve vývoji.
Nepoužívejte produkční tajné kódy ve vývojových nebo testovacích prostředích.
Zadejte tajné kódy mimo projekt, aby se nechtěně nedají potvrdit do úložiště zdrojového kódu.

Ve výchozím nastavení se zdroj konfigurace tajných kódů uživatele zaregistruje po JSzdrojích konfigurace ON. Proto mají klíče tajných kódů uživatelů 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í při vývoji v ASP.NET Core: Obsahuje rady k 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 ON v JSmístním systému.

Azure Key Vault bezpečně ukládá tajné kódy aplikací pro aplikace ASP.NET Core. Další informace najdete v tématu Poskytovatel konfigurace Azure Key Vault v ASP.NET Core.

Proměnné prostředí, které nejsou předpony

Proměnné prostředí, které nejsou předponou, jsou jiné než předpony předponami ASPNETCORE_ nebo DOTNET_. Například šablony ASP.NET Core webových aplikací nastavené "ASPNETCORE_ENVIRONMENT": "Development" v launchSettings.json. Další informace o ASPNETCORE_ proměnných prostředí a DOTNET_ o proměnných prostředí najdete tady:

Seznam výchozích zdrojů konfigurace s nejvyšší až nejnižší prioritou , včetně předpon, ASPNETCORE_předpony a DOTNETCORE_proměnných prostředí s předponou.
DOTNET_ proměnné prostředí používané mimo Microsoft.Extensions.Hosting

Pomocí výchozí konfigurace načte EnvironmentVariablesConfigurationProvider konfiguraci z párů klíč-hodnota proměnné prostředí po přečtení appsettings.jsona appsettings.{Environment}.jsontajných kódů uživatele. Proto klíčové hodnoty načtené z prostředí přepíší hodnoty načtené z appsettings.json, appsettings.{Environment}.jsona tajné kódy uživatele.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. __, dvojité podtržítko je:

Podporované všemi platformami. Oddělovač například :Bash nepodporuje, ale __ je.
Automaticky nahrazeno znakem :

set Následující příkazy:

Nastavte klíče prostředí a hodnoty předchozího příkladu ve Windows.
Otestujte nastavení při použití ukázkového stahování. 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í:

Jsou nastaveny pouze v procesech spuštěných z příkazového okna, ve které byly nastaveny.
Prohlížeče spuštěné v sadě Visual Studio nebudou číst.

Následující příkazy setx lze použít k nastavení klíčů a hodnot prostředí ve Windows. Na rozdíl od setnastavení setx se zachovají. /M nastaví proměnnou v systémovém prostředí. /M Pokud se přepínač nepoužívá, 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

Testování přepsání appsettings.json předchozích příkazů a appsettings.{Environment}.json:

Pomocí sady Visual Studio: Ukončete a restartujte Visual Studio.
Pomocí rozhraní příkazového řádku: Spusťte nové příkazové okno a zadejte dotnet run.

Volání AddEnvironmentVariables pomocí řetězce pro zadání předpony proměnných 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 JSON Configuration Provider.
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.

Předpona je při čtení párů klíč-hodnota konfigurace vypnutá.

Následující příkazy otestují vlastní předponu:

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_ ASP.NET Core používají pro konfiguraci hostitele a aplikace, ale ne pro konfiguraci uživatele. Další informace o konfiguraci hostitele a aplikace najdete v tématu .NET Generic Host.

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

Zašifrované neaktivní a přenášené přes šifrovaný kanál.
Vystaveno jako proměnné prostředí.

Další informace najdete v tématu Azure Apps: Přepsání konfigurace aplikace pomocí webu Azure Portal.

Informace o připojovacích řetězcích azure database najdete v tématu Předpony připojovacích řetězců připojovacích řetězců připojení k Azure.

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

Názvy proměnných appsettings.json prostředí odrážejí strukturu souboru. Každý prvek v hierarchii je oddělen dvojitým podtržítkem (nejlépe) nebo dvojtečkam. Pokud struktura elementu obsahuje pole, měl by být index pole považován za další název elementu v této cestě. Zvažte následující appsettings.json soubor 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 launchSettings.json

Proměnné prostředí nastavené v launchSettings.json přepsání sady v systémovém prostředí. Například webové šablony ASP.NET Core vygenerují launchSettings.json soubor, který nastaví konfiguraci koncového bodu na:

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

Konfigurace sad proměnných applicationUrlASPNETCORE_URLS prostředí a přepsání hodnot nastavených v prostředí

Řídicí proměnné prostředí v Linuxu

V Linuxu musí být hodnota proměnných prostředí URL řídicí, aby systemd ji bylo možné analyzovat. Použití linuxového nástroje systemd-escape , který přináší http:--localhost:5001

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

Zobrazení proměnných prostředí

Následující kód zobrazí 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 se načte CommandLineConfigurationProvider konfigurace z párů klíč-hodnota argumentu příkazového řádku za následujícími zdroji konfigurace:

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

Ve výchozím nastavení hodnoty konfigurace nastavené na příkazovém řádku přepíší konfigurační hodnoty nastavené u 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 =nebo klíč musí mít předponu -- nebo / když hodnota následuje za mezerou.
Pokud se používá, nevyžaduje = se. Například, MySetting=.

Ve stejném příkazu nekombinujte páry klíč-hodnota argumentu příkazového řádku, které používají = páry klíč-hodnota, které používají mezeru.

Přepnout mapování

Mapování přepínačů umožňují logiku nahrazení názvů klíčů . Zadejte slovník náhradních přepínačů metody AddCommandLine .

Při použití slovníku mapování přepínačů se slovník zkontroluje pro klíč, který odpovídá klíči poskytnutému argumentem příkazového řádku. Pokud se klíč příkazového řádku najde ve slovníku, předá se hodnota slovníku zpět, aby se pár klíč-hodnota nastavil do konfigurace aplikace. Mapování přepínače se vyžaduje pro libovolný klíč příkazového řádku s předponou s jednou pomlčkou (-).

Přepnout pravidla klíče slovníku mapování:

Přepínače musí začínat nebo ---.
Slovník mapování přepínačů nesmí obsahovat duplicitní klíče.

Pokud chcete použít 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 otestujte nahrazení klíče:

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

Následující kód ukazuje hodnoty klíče 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í CreateDefaultBuilder metody AddCommandLine neobsahuje mapované přepínače a neexistuje způsob, jak předat slovník mapování přepínače do CreateDefaultBuilder. Řešení nepředá argumenty CreateDefaultBuilder , ale místo toho umožní ConfigurationBuilder metodě metody AddCommandLine zpracovat 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 je možné nastavit v sadě Visual Studio z dialogového okna spouštěcích profilů:

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

Hierarchická konfigurační data

Rozhraní API konfigurace čte hierarchická konfigurační data zploštěním hierarchických dat pomocí oddělovače v konfiguračních klíčích.

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

{
  "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 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ý způsob čtení hierarchických konfiguračních dat používá vzor možností. Další informace najdete v tématu Vytvoření vazby hierarchických konfiguračních dat v tomto dokumentu.

GetSection a GetChildren metody jsou k dispozici k izolaci oddílů a podřízených částí oddílu v konfiguračních datech. Tyto metody jsou popsány dále v GetSection, GetChildren a Exist.

Konfigurační klíče a hodnoty

Konfigurační klíče:

Nerozlišují malá a velká písmena. Jedná se například ConnectionStringconnectionstring o ekvivalentní klíče.
Pokud je klíč a hodnota nastavena ve více než jednom poskytovateli konfigurace, použije se hodnota od posledního přidaného zprostředkovatele. Další informace najdete v tématu Výchozí konfigurace.
Hierarchické klíče
- V rámci konfiguračního rozhraní API funguje oddělovač dvojtečky (:) na všech platformách.
- V proměnných prostředí nemusí oddělovač dvojtečky fungovat na všech platformách. Dvojité podtržítko, __je podporováno všemi platformami a je automaticky převedeno na dvojtečku :.
- V Azure Key Vault se hierarchické klíče používají -- jako oddělovač. Poskytovatel konfigurace Azure Key Vault automaticky nahradí, když se tajné kódy --: načtou do konfigurace aplikace.
Podporuje ConfigurationBinder vazby polí k objektům pomocí maticových indexů v konfiguračních klíčích. Maticová vazba je popsaná v matici s oddílem třídy .

Hodnoty konfigurace:

Jsou řetězce.
Hodnoty null nelze uložit v konfiguraci ani vázané na objekty.

Zprostředkovatelé konfigurace

Následující tabulka ukazuje poskytovatele konfigurace, kteří jsou k dispozici pro ASP.NET Core aplikace.

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

Zdroje konfigurace se čtou v pořadí, v jakém jsou zadané jejich poskytovatelé konfigurace. Objednávejte poskytovatele konfigurace v kódu tak, aby vyhovovaly prioritám podkladových zdrojů konfigurace, které aplikace vyžaduje.

Typická posloupnost poskytovatelů konfigurace je:

appsettings.json
appsettings.{Environment}.json
Tajné kódy uživatelů
Proměnné prostředí používající zprostředkovatele konfigurace proměnných prostředí
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 naposledy v řadě zprostředkovatelů, aby argumenty příkazového řádku mohly přepsat konfiguraci nastavenou ostatními poskytovateli.

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

Předpony připojovacího řetězce

Rozhraní API konfigurace má speciální pravidla zpracování pro čtyři proměnné prostředí připojovacího řetězce. Tyto připojovací řetězce jsou zapojeny do konfigurace připojovacích řetězců Azure pro aplikační prostředí. Proměnné prostředí s předponami zobrazenými v tabulce se načtou do aplikace s výchozí konfigurací nebo při zadání žádné předpony .AddEnvironmentVariables

Předpona připojovacího řetězce	Poskytovatel
`CUSTOMCONNSTR_`	Vlastní poskytovatel
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Azure SQL Database
`SQLCONNSTR_`	SQL Server

Při zjištění a načtení proměnné prostředí do konfigurace s některou ze čtyř předpon zobrazených v tabulce:

Konfigurační klíč se vytvoří odebráním předpony proměnné prostředí a přidáním oddílu 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 stavované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 se nevytvořila.
`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`

Poskytovatel konfigurace souborů

FileConfigurationProvider je základní třída pro načítání konfigurace ze systému souborů. Následující poskytovatelé konfigurace pocházejí z FileConfigurationProvider:

Zprostředkovatel konfigurace INI
JSZprostředkovatel konfigurace ON
Zprostředkovatel konfigurace XML

Zprostředkovatel konfigurace INI

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

Následující kód vymaže všechny poskytovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
          .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

V předchozím kódu se nastavení v souborech MyIniConfig.ini přepíše MyIniConfig.{Environment}.ini nastavením v následující části:

Zprostředkovatel konfigurace proměnných prostředí
Zprostředkovatel konfigurace příkazového řádku

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

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

JSZprostředkovatel konfigurace ON

Načtení JsonConfigurationProvider konfigurace z JSpárů klíč-hodnota souboru ON.

Přetížení můžou určovat:

Jestli je soubor nepovinný.
Jestli se konfigurace znovu načte, pokud se soubor změní.

Vezměme si následující kód:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyConfig.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Předchozí kód:

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

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

Zprostředkovatel konfigurace XML

Načtení XmlConfigurationProvider konfigurace z párů klíč-hodnota souboru XML za běhu.

Následující kód vymaže všechny poskytovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
          .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

V předchozím kódu se nastavení v souborech MyXMLFile.xml přepíše MyXMLFile.{Environment}.xml nastavením v následující části:

Zprostředkovatel konfigurace proměnných prostředí
Zprostředkovatel konfigurace příkazového řádku

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

<?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 prvky, které používají stejný název elementu, fungují, pokud name se atribut používá k rozlišení prvků:

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

Atributy lze použít k zadání hodnot:

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

key:attribute
section:key:attribute

Poskytovatel konfigurace klíče na soubor

Používá KeyPerFileConfigurationProvider soubory adresáře jako páry klíč-hodnota konfigurace. Klíč je název souboru. Hodnota obsahuje obsah souboru. Poskytovatel konfigurace klíče na soubor se používá ve scénářích hostování Dockeru.

Chcete-li aktivovat konfiguraci klíče na soubor, zavolejte metodu AddKeyPerFile rozšíření instance .ConfigurationBuilder K directoryPath souborům musí být absolutní cesta.

Přetížení umožňují zadat:

Delegát Action<KeyPerFileConfigurationSource> , který nakonfiguruje zdroj.
Určuje, jestli je adresář volitelný a cesta k adresáři.

Dvojitá podtržítka (__) se používá jako oddělovač konfiguračního klíče v názvech souborů. Například název Logging__LogLevel__System souboru vytvoří konfigurační klíč Logging:LogLevel:System.

Volání ConfigureAppConfiguration při sestavování hostitele 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 paměti

Používá MemoryConfigurationProvider kolekci v paměti jako páry klíč-hodnota konfigurace.

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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

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

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 config.AddInMemoryCollection(Dict) se přidá za výchozí zprostředkovatele konfigurace. Příklad řazení zprostředkovatelů konfigurace najdete v tématu JSON Configuration Provider.

Viz Vytvoření vazby pole pro jiný příklad pomocí MemoryConfigurationProvider.

Kestrel konfigurace koncového bodu

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

Zvažte následující appsettings.json soubor 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": "*"
}

Když se v ASP.NET Core webové aplikaci použije předchozí zvýrazněný kód a aplikace se spustí na příkazovém řádku s následující konfigurací koncového bodu mezi servery:

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

Kestrel vytvoří vazbu ke koncovému bodu nakonfigurovaného speciálně pro Kestrel soubor appsettings.json (https://localhost:9999) a ne https://localhost:7777.

Kestrel Zvažte konkrétní koncový bod nakonfigurovaný jako proměnnou prostředí:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

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

GetValue

ConfigurationBinder.GetValue extrahuje jednu hodnotu z konfigurace se zadaným klíčem a převede ji na zadaný 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 konfiguraci nenajde předchozí kód NumberKey , použije se výchozí hodnota 99 .

GetSection, GetChildren a Existuje

Příklady, které následují, zvažte následující MySubsection.json soubor:

{
  "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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MySubsection.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Getsection

IConfiguration.GetSection vrátí pododdíl konfigurace se zadaný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 se nevrátí null. Pokud se odpovídající oddíl nenajde, vrátí se prázdný IConfigurationSection oddíl.

Když GetSection vrátí odpovídající oddíl, Value nezaplní se. A Key a Path vrátí se, když oddíl existuje.

GetChildren a existuje

Následující volání IConfiguration.GetChildren kódu a vrátí 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í volání ConfigurationExtensions.Exists kódu pro ověření, že oddíl existuje:

Vytvoření vazby pole

Podporuje ConfigurationBinder.Bind vazby polí k objektům pomocí maticových indexů v konfiguračních klíčích. Jakýkoli formát pole, který zveřejňuje číselný segment klíče, je schopen maticové vazby na pole třídy POCO .

Zvažte 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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.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 odpovídající "4": "value40", hodnotě value40in MyArray.json. Indexy vázaného pole jsou souvislé a nejsou vázány na index konfiguračního klíče. Vazač konfigurace nemůže vytvořit hodnoty null nebo vytvářet položky null v vázaných objektech.

Vlastní zprostředkovatel konfigurace

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

Poskytovatel má následující charakteristiky:

Databáze EF v paměti se používá pro demonstrační účely. Pokud chcete použít databázi, která vyžaduje připojovací řetězec, implementujte sekundární ConfigurationBuilder řetězec pro zadání připojovacího řetězce od jiného zprostředkovatele konfigurace.
Zprostředkovatel při spuštění načte tabulku databáze do konfigurace. Zprostředkovatel se na databázi dotazuje podle klíče.
Opětovné načtení změny není implementováno, takže aktualizace databáze po spuštění aplikace nemá žádný vliv na konfiguraci aplikace.

Definujte entitu EFConfigurationValue pro ukládání hodnot konfigurace v databázi.

Models/EFConfigurationValue.cs:

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

Přidejte objekt 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ření třídy, 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 zděděním z ConfigurationProvider. Poskytovatel 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 s porovnáním malých a malých písmen (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;
    }
}

Metoda AddEFConfiguration rozšíření umožňuje přidat zdroj 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 kód: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í injektáže závislostí (DI)

Konfiguraci je možné vložit do služeb pomocí injektáže závislostí (DI) překladem IConfiguration služby:

public class Service
{
    private readonly IConfiguration _config;

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

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

        // ...
    }
}

Informace o přístupu k hodnotám pomocí IConfigurationfunkce GetValue a GetSection, GetChildren a Exists v tomto článku.

Konfigurace přístupu na Razor stránkách

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

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

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

V následujícím kódu MyOptions se přidá do kontejneru služby s Configure vazbou na konfiguraci:

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 @injectRazor k vyřešení 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>

Konfigurace přístupu 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"]

Konfigurace možností pomocí delegáta

Možnosti nakonfigurované v delegátu přepíší hodnoty nastavené v zprostředkovatelích konfigurace.

V následujícím kódu IConfigureOptions<TOptions> se služba přidá do kontejneru služby. Používá delegáta ke konfiguraci hodnot 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 jsou zadány a appsettings.json následně přepsány nakonfigurovaným delegátem.

Konfigurace hostitele a aplikace

Před konfigurací a spuštěním aplikace se nakonfiguruje a spustí hostitel. Hostitel zodpovídá za správu spuštění a životnosti aplikace. Aplikace i hostitel jsou nakonfigurované pomocí poskytovatelů konfigurace popsaných v tomto tématu. Do konfigurace aplikace jsou zahrnuty také páry klíč-hodnota konfigurace hostitele. Další informace o tom, jak se zprostředkovatelé konfigurace používají při sestavování hostitele a jaký vliv mají zdroje konfigurace na konfiguraci hostitele, najdete v přehledu ASP.NET Core základů.

Výchozí konfigurace hostitele

Podrobnosti o výchozí konfiguraci při použití webového hostitele najdete v tématu ASP.NET Core verze 2.2.

Konfigurace hostitele je k dispozici z:
- Proměnné prostředí s předponou DOTNET_ (například DOTNET_ENVIRONMENT) pomocí zprostředkovatele konfigurace proměnných prostředí. Předpona (DOTNET_) se odstraní při načtení párů klíč-hodnota konfigurace.
- Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
Vytvoří se výchozí konfigurace webového hostitele (ConfigureWebHostDefaults):
- Kestrel se používá jako webový server a konfiguruje pomocí zprostředkovatelů konfigurace aplikace.
- Přidejte middleware filtrování hostitelů.
- Pokud je proměnná prostředí nastavená na truehodnotu , přidejte middleware Forwarded Headers Middleware ASPNETCORE_FORWARDEDHEADERS_ENABLED .
- Povolte integraci služby IIS.

Jiná konfigurace

Toto téma se týká jenom konfigurace aplikace. Další aspekty spouštění a hostování aplikací ASP.NET Core se konfigurují pomocí konfiguračních souborů, které nejsou popsané v tomto tématu:

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

Proměnné prostředí nastavené v launchSettings.json přepsání těchto nastavení v systémovém prostředí.

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

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

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

Další materiály

Soubory nastavení, například appsettings.json
Proměnné prostředí
Azure Key Vault
Azure App Configuration
Argumenty příkazového řádku
Vlastní poskytovatelé, nainstalované nebo vytvořené
Soubory adresáře
Objekty .NET v paměti

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

Konfigurace aplikací a hostitelů

Konfigurace aplikace je nejvyšší prioritou a je podrobně popsána v další části. Konfigurace hostitele se řídí konfigurací aplikace a je popsána v tomto článku.

Výchozí zdroje konfigurace aplikací

ASP.NET Core webové aplikace vytvořené pomocí nového dotnetu nebo sady Visual Studio vygenerují následující kód:

var builder = WebApplication.CreateBuilder(args);

Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
Proměnné prostředí bez předpony používající poskytovatele konfigurace proměnných prostředí bez předpony.
Uživatelské tajné kódy při spuštění aplikace v Development prostředí.
appsettings.{Environment}.jsonJSpomocí zprostředkovatele konfigurace ON. Příklad: appsettings.Production.json a appsettings.Development.json.
appsettings.json pomocí JSzprostředkovatele konfigurace ON.
Náhradní 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:

ASPNETCORE_-předpona proměnných prostředí pomocí zprostředkovatele konfigurace proměnných prostředí.
Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
DOTNET_-předpona proměnných prostředí pomocí zprostředkovatele konfigurace proměnných prostředí.

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

Proměnné hostitele

Při počáteční inicializaci tvůrce hostitelů jsou uzamčeny následující proměnné a nelze je ovlivnit konfigurací aplikace:

Název aplikace
Název prostředí, například Development, Productiona Staging
Kořen obsahu
Webový kořen
Zda chcete vyhledat hostování spouštěcích sestavení a sestavení, která se mají vyhledat.
Proměnné čtené podle kódu aplikace a knihovny z HostBuilderContext.Configuration v zpětných voláních IHostBuilder.ConfigureAppConfiguration .

Každé jiné nastavení hostitele se čte z konfigurace aplikace místo konfigurace hostitele.

Zbývající části tohoto článku odkazují na konfiguraci aplikace.

Zprostředkovatelé konfigurace aplikací

Následující kód zobrazí povolené zprostředkovatele konfigurace v pořadí, v jakém byly přidány:

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

Další informace najdete v CreateBuildertématu Výchozí nastavení tvůrce.

`appsettings.json`

Zvažte následující appsettings.json soubor:

{
  "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čtení konfigurace v následujícím pořadí:

appsettings.json
appsettings.{Environment}.json : Například soubory appsettings.Production.json a appsettings.Development.json soubory. Verze prostředí souboru se načte na IHostingEnvironment.EnvironmentNamezákladě . Další informace najdete v tématu Použití více prostředí v ASP.NET Core.

appsettings.{Environment}.json hodnoty přepisuje klíče v appsettings.json. Ve výchozím nastavení by například:

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

Pokud musí být zaručená hodnota konfigurace, přečtěte si téma GetValue. Předchozí příklad čte pouze řetězce a nepodporuje výchozí hodnotu.

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í PositionOptions třídu:

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

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

Třída options:

Nesmí být abstraktní s veřejným konstruktorem bez parametrů.
Všechny veřejné vlastnosti čtení a zápisu typu jsou vázané.
Pole nejsou vázána. V předchozím kódu Position není vázán. Toto Position pole se používá, takže řetězec "Position" nemusí být pevně zakódován v aplikaci při vazbě třídy k poskytovateli konfigurace.

Následující kód:

Volá ConfigurationBinder.Bind pro vytvoření vazbyPositionOptions třídy k oddílu Position .
Position Zobrazí konfigurační data.

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

Ve výchozím nastavení se v předchozím kódu změní konfigurační JSsoubor ON po spuštění aplikace.

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

Ve výchozím nastavení se v předchozím kódu změní konfigurační JSsoubor ON po spuštění aplikace.

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 JSsouboru ON po spuštění aplikace nečtou . Pokud chcete číst změny po spuštění aplikace, použijte IOptionsSnapshot.

Informace o přidání dalších JSkonfiguračních souborů ON najdete v tomto dokumentu v části Zprostředkovatel konfigurace ON.JS

Kombinování kolekce služeb

Zvažte následující možnosti, které registrují služby a konfigurují 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í je možné přesunout do metody rozšíření pro registraci služeb. Konfigurační služby se například přidají 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;
        }
    }
}

Zbývající služby jsou zaregistrované v podobné třídě. Následující kód používá nové metody rozšíření 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á services.Add{GROUP_NAME} metoda rozšíření přidává a potenciálně konfiguruje služby. Přidá například AddControllersWithViews služby, které kontrolery MVC se zobrazeními vyžadují, a AddRazorPages přidá stránky služeb Razor . Doporučujeme, aby aplikace dodržovaly zásady vytváření metod rozšíření v Microsoft.Extensions.DependencyInjection oboru názvů. Vytváření metod rozšíření v Microsoft.Extensions.DependencyInjection oboru názvů:

Zapouzdřuje skupiny registrací služeb.
Poskytuje pohodlný přístup intelliSense ke službě.

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

Pokyny pro konfigurační data:

Nikdy neukládá hesla ani jiná citlivá data v kódu zprostředkovatele konfigurace nebo v konfiguračních souborech prostého textu. Nástroj Secret Manager lze použít k ukládání tajných kódů ve vývoji.
Nepoužívejte produkční tajné kódy ve vývojových nebo testovacích prostředích.
Zadejte tajné kódy mimo projekt, aby se nechtěně nedají potvrdit do úložiště zdrojového kódu.

Ve výchozím nastavení se zdroj konfigurace tajných kódů uživatelů zaregistruje za JSzdroji konfigurace ON. Proto mají klíče tajných kódů uživatelů 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í při vývoji v ASP.NET Core: Obsahuje rady k 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 ON v JSmístním systému.

Azure Key Vault bezpečně ukládá tajné kódy aplikací pro ASP.NET Core aplikace. Další informace najdete v tématu o poskytovateli konfigurace Azure Key Vault v ASP.NET Core.

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

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

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

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. __, dvojité podtržítko je:

Podporované všemi platformami. Oddělovač například :Bash nepodporuje, ale __ je.
Automaticky nahrazeno znakem :

set Následující příkazy:

Nastavte klíče prostředí a hodnoty předchozího příkladu ve Windows.
Otestujte nastavení při použití ukázkového stahování. 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í:

Jsou nastaveny pouze v procesech spuštěných z příkazového okna, ve které byly nastaveny.
Prohlížeče spuštěné v sadě Visual Studio nebudou číst.

setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Testování přepsání appsettings.json předchozích příkazů a appsettings.{Environment}.json:

Pomocí sady Visual Studio: Ukončete a restartujte Visual Studio.
Pomocí rozhraní příkazového řádku: Spusťte nové příkazové okno a zadejte dotnet run.

Volání AddEnvironmentVariables pomocí řetězce pro zadání předpony proměnných 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 JSON Configuration Provider.
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.

Předpona je při čtení párů klíč-hodnota konfigurace vypnutá.

Následující příkazy otestují vlastní předponu:

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 Azure App Service na stránce Konfigurace nastavení > vyberte Nové nastavení aplikace. Azure App Service nastavení aplikace jsou:

Zašifrované neaktivní a přenášené přes šifrovaný kanál.
Vystaveno jako proměnné prostředí.

Další informace najdete v tématu Azure Apps: Přepsání konfigurace aplikace pomocí webu Azure Portal.

Informace o připojovacích řetězcích azure database najdete v tématu Předpony připojovacích řetězců připojovacích řetězců připojení k Azure.

Pojmenování proměnných 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 launchSettings.json

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

Konfigurace sad proměnných applicationUrlASPNETCORE_URLS prostředí a přepsání hodnot nastavených v prostředí

Řídicí proměnné prostředí v Linuxu

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

Zobrazení proměnných prostředí

Následující kód zobrazí 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 se načte CommandLineConfigurationProvider konfigurace z párů klíč-hodnota argumentu příkazového řádku za následujícími zdroji konfigurace:

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

Ve výchozím nastavení hodnoty konfigurace nastavené na příkazovém řádku přepíší konfigurační hodnoty nastavené u 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 =nebo klíč musí mít předponu -- nebo / když hodnota následuje za mezerou.
Pokud se používá, nevyžaduje = se. Například, MySetting=.

Ve stejném příkazu nekombinujte páry klíč-hodnota argumentu příkazového řádku, které používají = páry klíč-hodnota, které používají mezeru.

Přepnout mapování

Mapování přepínačů umožňují logiku nahrazení názvů klíčů . Zadejte slovník náhradních přepínačů metody AddCommandLine .

Přepnout pravidla klíče slovníku mapování:

Přepínače musí začínat nebo ---.
Slovník mapování přepínačů nesmí obsahovat duplicitní klíče.

Pokud chcete použít 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 otestujte nahrazení klíče:

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

Následující kód ukazuje hodnoty klíče 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"]}'");
    }
}

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

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

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

Hierarchická konfigurační data

Rozhraní API konfigurace čte hierarchická konfigurační data zploštěním hierarchických dat pomocí oddělovače v konfiguračních klíčích.

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

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

GetSection a GetChildren metody jsou k dispozici k izolaci oddílů a podřízených částí oddílu v konfiguračních datech. Tyto metody jsou popsány dále v GetSection, GetChildren a Exist.

Konfigurační klíče a hodnoty

Konfigurační klíče:

Nerozlišují malá a velká písmena. Jedná se například ConnectionStringconnectionstring o ekvivalentní klíče.
Pokud je klíč a hodnota nastavená ve více než jednom poskytovateli konfigurace, použije se hodnota od posledního přidaného zprostředkovatele. Další informace naleznete v tématu Výchozí konfigurace.
Hierarchické klíče
- V rámci rozhraní CONFIGURATION API funguje oddělovač dvojtečky (:) na všech platformách.
- V proměnných prostředí nemusí oddělovač dvojtečky fungovat na všech platformách. Dvojité podtržítko, __je podporováno všemi platformami a je automaticky převedeno na dvojtečku :.
- V Azure Key Vault se hierarchické klíče používají -- jako oddělovač. Poskytovatel konfigurace Azure Key Vault automaticky nahradí, když se tajné kódy --: načtou do konfigurace aplikace.
Podporuje ConfigurationBinder vazby polí na objekty pomocí maticových indexů v konfiguračních klíčích. Maticová vazba je popsána v části Vytvoření vazby pole k oddílu třídy .

Hodnoty konfigurace:

Jsou řetězce.
Hodnoty null nelze uložit v konfiguraci ani vázané na objekty.

Zprostředkovatelé konfigurace

V následující tabulce jsou uvedeni poskytovatelé konfigurace, kteří jsou k dispozici pro ASP.NET Core aplikace.

Poskytovatel	Poskytuje konfiguraci z
Poskytovatel konfigurace Azure Key Vault	Azure Key Vault
Aplikace Azure zprostředkovatele konfigurace	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áře
Zprostředkovatel konfigurace paměti	Kolekce v paměti
Tajné kódy uživatelů	Soubor v adresáři profilu uživatele

Zdroje konfigurace se čtou v pořadí, v jakém jsou zadaná jejich poskytovatelé konfigurace. V kódu seřadí zprostředkovatele konfigurace tak, aby vyhovovaly prioritám podkladových zdrojů konfigurace, které aplikace vyžaduje.

Typická posloupnost poskytovatelů konfigurace je:

appsettings.json
appsettings.{Environment}.json
Tajné kódy uživatelů
Proměnné prostředí používající zprostředkovatele konfigurace proměnných prostředí
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 bylo možné přepsat konfiguraci nastavenou jinými poskytovateli.

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

Předpony připojovacího řetězce

Rozhraní CONFIGURATION API má speciální pravidla zpracování pro čtyři proměnné prostředí připojovacího řetězce. Tyto připojovací řetězce jsou zapojeny do konfigurace připojovacích řetězců Azure pro prostředí aplikace. Proměnné prostředí s předponami zobrazenými v tabulce se načtou do aplikace s výchozí konfigurací nebo když není zadána AddEnvironmentVariablesžádná předpona .

Předpona připojovacího řetězce	Poskytovatel
`CUSTOMCONNSTR_`	Vlastní zprostředkovatel
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Azure SQL Database
`SQLCONNSTR_`	SQL Server

Při zjištění a načtení proměnné prostředí do konfigurace s některou ze čtyř předpon zobrazených v tabulce:

Konfigurační klíč se vytvoří odebráním předpony proměnné prostředí a přidáním oddílu 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 stavované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 se nevytvořila.
`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 souborů

FileConfigurationProvider je základní třída pro načítání konfigurace ze systému souborů. Následující poskytovatelé konfigurace jsou odvozeni od FileConfigurationProvider:

Zprostředkovatel konfigurace INI
JSZprostředkovatel konfigurace ON
Zprostředkovatel konfigurace XML

Zprostředkovatel konfigurace INI

Načtení IniConfigurationProvider konfigurace z párů klíč-hodnota souboru INI za běhu

Následující kód vymaže všechny zprostředkovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
          .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

V předchozím kódu jsou nastavení v souborech MyIniConfig.iniMyIniConfig.{Environment}.ini přepsána nastavením v:

Zprostředkovatel konfigurace proměnných prostředí
Zprostředkovatel konfigurace příkazového řádku

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

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

JSZprostředkovatel konfigurace ON

Načte JsonConfigurationProvider konfiguraci z JSpárů klíč-hodnota souboru ON.

Přetížení můžou určovat:

Jestli je soubor nepovinný.
Jestli se konfigurace znovu načte, pokud se soubor změní.

Vezměme si následující kód:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyConfig.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Předchozí kód:

Nakonfiguruje JSzprostředkovatele konfigurace ON, aby soubor načetl MyConfig.json s následujícími možnostmi:
- optional: true: Soubor je nepovinný.
- reloadOnChange: true : Při uložení změn se soubor znovu načte.
Před souborem MyConfig.json přečte výchozí zprostředkovatele konfigurace. Nastavení v nastavení přepsání souboru ve MyConfig.json výchozích poskytovatelích konfigurace, včetně zprostředkovatele konfigurace proměnných prostředí a zprostředkovatele konfigurace příkazového řádku.

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

Zprostředkovatel konfigurace XML

Načtení XmlConfigurationProvider konfigurace z párů klíč-hodnota souboru XML za běhu.

Následující kód vymaže všechny zprostředkovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
          .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

V předchozím kódu jsou nastavení v souborech MyXMLFile.xmlMyXMLFile.{Environment}.xml přepsána nastavením v:

Zprostředkovatel konfigurace proměnných prostředí
Zprostředkovatel konfigurace příkazového řádku

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

<?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 prvky, které používají stejný název elementu, fungují, pokud name se atribut používá k rozlišení prvků:

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

Atributy lze použít k zadání hodnot:

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

key:attribute
section:key:attribute

Poskytovatel konfigurace klíče na soubor

Chcete-li aktivovat konfiguraci klíče na soubor, zavolejte metodu AddKeyPerFile rozšíření instance .ConfigurationBuilder K directoryPath souborům musí být absolutní cesta.

Přetížení umožňují zadat:

Delegát Action<KeyPerFileConfigurationSource> , který nakonfiguruje zdroj.
Určuje, jestli je adresář volitelný a cesta k adresáři.

Volání ConfigureAppConfiguration při sestavování hostitele 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 paměti

Používá MemoryConfigurationProvider kolekci v paměti jako páry klíč-hodnota konfigurace.

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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

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

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

Viz Vytvoření vazby pole pro jiný příklad pomocí MemoryConfigurationProvider.

Kestrel konfigurace koncového bodu

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

Zvažte následující appsettings.json soubor 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": "*"
}

Když se v ASP.NET Core webové aplikaci použije předchozí zvýrazněný kód a aplikace se spustí na příkazovém řádku s následující konfigurací koncového bodu mezi servery:

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

Kestrel vytvoří vazbu ke koncovému bodu nakonfigurovaného speciálně pro Kestrel soubor appsettings.json (https://localhost:9999) a ne https://localhost:7777.

Kestrel Zvažte konkrétní koncový bod nakonfigurovaný jako proměnnou prostředí:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

GetValue

ConfigurationBinder.GetValue extrahuje jednu hodnotu z konfigurace se zadaným klíčem a převede ji na zadaný 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 konfiguraci nenajde předchozí kód NumberKey , použije se výchozí hodnota 99 .

GetSection, GetChildren a Existuje

Příklady, které následují, zvažte následující MySubsection.json soubor:

{
  "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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MySubsection.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Getsection

IConfiguration.GetSection vrátí pododdíl konfigurace se zadaný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 se nevrátí null. Pokud se odpovídající oddíl nenajde, vrátí se prázdný IConfigurationSection oddíl.

Když GetSection vrátí odpovídající oddíl, Value nezaplní se. A Key a Path vrátí se, když oddíl existuje.

GetChildren a existuje

Následující volání IConfiguration.GetChildren kódu a vrátí 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í volání ConfigurationExtensions.Exists kódu pro ověření, že oddíl existuje:

Vytvoření vazby pole

Zvažte 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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.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 odpovídající "4": "value40", hodnotě value40in MyArray.json. Indexy vázaného pole jsou souvislé a nejsou vázané na index konfiguračního klíče. Konfigurační pořadač nemůže vytvořit hodnoty null ani vytvářet položky null v vázaných objektech.

Vlastní poskytovatel konfigurace

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

Poskytovatel má následující charakteristiky:

Databáze EF v paměti se používá pro demonstrační účely. Pokud chcete použít databázi, která vyžaduje připojovací řetězec, implementujte sekundární ConfigurationBuilder řetězec pro poskytnutí připojovacího řetězce od jiného zprostředkovatele konfigurace.
Poskytovatel načte tabulku databáze do konfigurace při spuštění. Poskytovatel databázi na základě klíče dotazuje.
Opětovné načtení změny není implementováno, takže aktualizace databáze po spuštění aplikace nemá žádný vliv na konfiguraci aplikace.

Definujte entitu EFConfigurationValue pro ukládání konfiguračních hodnot v databázi.

Models/EFConfigurationValue.cs:

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

Přidejte k EFConfigurationContext ukládání a přístupu ke 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);
}

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

Metoda AddEFConfiguration rozšíření povoluje přidání zdroje konfigurace do ConfigurationBuildersouboru .

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žívat vlastní EFConfigurationProvider kód 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í injektáže závislostí (DI)

Konfiguraci je možné vložit do služeb pomocí injektáže závislostí (DI) překladem IConfiguration služby:

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í IConfigurationfunkce GetValue a GetSection, GetChildren a Existuje v tomto článku.

Konfigurace přístupu na Razor stránkách

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

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

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

V následujícím kódu MyOptions se přidá do kontejneru služby a Configure je vázán na konfiguraci:

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 @injectRazor 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>

Konfigurace přístupu v souboru zobrazení MVC

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

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Konfigurace možností pomocí delegáta

Možnosti nakonfigurované v delegátu přepíší hodnoty nastavené v zprostředkovatelích konfigurace.

V následujícím kódu IConfigureOptions<TOptions> se služba přidá do kontejneru služby. Používá delegáta ke konfiguraci hodnot 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 jsou zadány appsettings.json a Option2 pak přepsány nakonfigurovaným delegátem.

Konfigurace hostitele a aplikace

Před konfigurací a spuštěním aplikace se hostitel nakonfiguruje a spustí. Hostitel zodpovídá za správu spuštění a životnosti aplikace. Aplikace i hostitel jsou nakonfigurované pomocí zprostředkovatelů konfigurace popsaných v tomto tématu. Do konfigurace aplikace se také zahrnou páry klíč-hodnota konfigurace hostitele. Další informace o tom, jak se zprostředkovatelé konfigurace používají při vytváření hostitele a o tom, jak zdroje konfigurace ovlivňují konfiguraci hostitele, najdete v tématu ASP.NET Core základní informace.

Výchozí konfigurace hostitele

Podrobnosti o výchozí konfiguraci při použití webového hostitele najdete v ASP.NET Core verze 2.2 tohoto tématu.

Konfigurace hostitele je poskytována z:
- Proměnné prostředí s předponou DOTNET_ (napříkladDOTNET_ENVIRONMENT) pomocí zprostředkovatele konfigurace proměnných prostředí Předpona (DOTNET_) se při načtení párů klíč-hodnota konfigurace odstraní.
- Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
Vytvoří se výchozí konfigurace webového hostitele (ConfigureWebHostDefaults):
- Kestrel se používá jako webový server a konfiguruje se pomocí poskytovatelů konfigurace aplikace.
- Přidejte middleware filtrování hostitele.
- Pokud je proměnná prostředí nastavená na true, přidejte Middleware forwarded Headers Middleware ASPNETCORE_FORWARDEDHEADERS_ENABLED .
- Povolte integraci služby IIS.

Další konfigurace

Toto téma se týká pouze konfigurace aplikace. Další aspekty spouštění a hostování aplikací ASP.NET Core jsou nakonfigurované pomocí konfiguračních souborů, které nejsou popsané v tomto tématu:

launch.json/launchSettings.json jsou konfigurační soubory nástrojů pro vývojové prostředí popsané:
- Použití více prostředí v ASP.NET Core
- V sadě dokumentace, kde se soubory používají ke konfiguraci ASP.NET Core aplikací 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řepsání sady v systémovém prostředí.

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

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

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

Další materiály

Konfigurace v ASP.NET Core se provádí pomocí jednoho nebo více poskytovatelů konfigurace. Poskytovatelé konfigurace čtou konfigurační data z párů klíč-hodnota pomocí různých zdrojů konfigurace:

Soubory nastavení, například appsettings.json
Proměnné prostředí
Azure Key Vault
Azure App Configuration
Argumenty příkazového řádku
Vlastní poskytovatelé, nainstalované nebo vytvořené
Soubory adresáře
Objekty .NET v paměti

Toto téma obsahuje informace o konfiguraci v ASP.NET Core. Informace o používání konfigurace v konzolových aplikacích najdete v tématu Konfigurace .NET.

Zobrazení nebo stažení ukázkového kódu (jak stáhnout)

Výchozí konfigurace

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

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder poskytuje výchozí konfiguraci aplikace v následujícím pořadí:

ChainedConfigurationProvider : Přidá existující IConfiguration jako zdroj. Ve výchozím případě konfigurace přidá konfiguraci hostitele a nastaví ji jako první zdroj konfigurace aplikace .
appsettings.json pomocí JSzprostředkovatele konfigurace ON.
appsettings.{Environment}.jsonJSpomocí zprostředkovatele konfigurace ON. Příklad: appsettings.Production.json a appsettings.Development.json.
Tajné kódy aplikací při spuštění aplikace v Development prostředí
Proměnné prostředí používající zprostředkovatele konfigurace proměnných prostředí
Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku

Poskytovatelé konfigurace přidaní později přepíší předchozí nastavení klíče. Pokud MyKey je například nastavená v obou appsettings.json prostředích a prostředí, použije se hodnota prostředí. Pomocí výchozích poskytovatelů konfigurace přepíše poskytovatel konfigurace příkazového řádku všechny ostatní poskytovatele.

Další informace najdete v CreateDefaultBuildertématu Výchozí nastavení tvůrce.

Následující kód zobrazí povolené poskytovatele konfigurace v pořadí, v jakém byly přidány:

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

`appsettings.json`

Zvažte následující appsettings.json soubor:

{
  "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čtení konfigurace v následujícím pořadí:

appsettings.json
appsettings.{Environment}.json : Například soubory appsettings.Production.json a appsettings.Development.json soubory. Verze prostředí souboru je načtena na IHostingEnvironment.EnvironmentNamezákladě . Další informace najdete v tématu Použití více prostředí v ASP.NET Core.

appsettings.{Environment}.json hodnoty přepisuje klíče v appsettings.json. Ve výchozím nastavení by například:

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

Pokud je nutné zaručit hodnotu konfigurace, přečtěte si téma GetValue. Předchozí příklad jen čte řetězce a nepodporuje výchozí hodnotu.

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í PositionOptions třídu:

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

    public string Title { get; set; }
    public string Name { get; set; }
}

Třída možností:

Nesmí být abstraktní s veřejným konstruktorem bez parametrů.
Všechny veřejné vlastnosti pro čtení a zápis typu jsou vázané.
Pole nejsou vázána. V předchozím kódu Position není vázán. Vlastnost Position se používá, takže při vazbě třídy k poskytovateli konfigurace nemusí být řetězec "Position" pevně zakódován v aplikaci.

Následující kód:

Volá ConfigurationBinder.Bind pro vytvoření vazby PositionOptions třídy k oddílu Position .
Position Zobrazí konfigurační data.

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

Ve výchozím nastavení se v předchozím kódu změní JSkonfigurační soubor ON po spuštění aplikace.

ConfigurationBinder.Get<T> vytvoří vazbu a vrátí zadaný 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 PositionOptions třídou:

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

Ve výchozím nastavení se v předchozím kódu změní JSkonfigurační soubor ON po spuštění aplikace.

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

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 JSsouboru ON po spuštění aplikace nečtou . Pokud chcete číst změny po spuštění aplikace, použijte IOptionsSnapshot.

Informace o přidání dalších JSkonfiguračních souborů ON najdete v tomto dokumentu v části Zprostředkovatel konfigurace ON.JS

Kombinování kolekce služeb

Zvažte následující ConfigureServices metodu, která registruje služby a konfiguruje možnosti:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

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

    services.AddRazorPages();
}

Související skupiny registrací je možné přesunout do metody rozšíření pro registraci služeb. Konfigurační služby se například přidají 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;
        }
    }
}

Zbývající služby jsou zaregistrované v podobné třídě. Následující ConfigureServices metoda používá nové metody rozšíření k registraci služeb:

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

Poznámka: Každá services.Add{GROUP_NAME} metoda rozšíření přidává a potenciálně konfiguruje služby. Přidá například AddControllersWithViews služby, které kontrolery MVC se zobrazeními vyžadují, a AddRazorPages přidá stránky služeb Razor . Doporučujeme, aby aplikace dodržovaly zásady vytváření metod rozšíření v Microsoft.Extensions.DependencyInjection oboru názvů. Vytváření metod rozšíření v Microsoft.Extensions.DependencyInjection oboru názvů:

Zapouzdřuje skupiny registrací služeb.
Poskytuje pohodlný přístup intelliSense ke službě.

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

Pokyny pro konfigurační data:

Nikdy neukládá hesla ani jiná citlivá data v kódu zprostředkovatele konfigurace nebo v konfiguračních souborech prostého textu. Nástroj Secret Manager lze použít k ukládání tajných kódů ve vývoji.
Nepoužívejte produkční tajné kódy ve vývojových nebo testovacích prostředích.
Zadejte tajné kódy mimo projekt, aby se nechtěně nedají potvrdit do úložiště zdrojového kódu.

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í při vývoji v ASP.NET Core: Obsahuje rady k 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 ON v JSmístním systému.

Azure Key Vault bezpečně ukládá tajné kódy aplikací pro ASP.NET Core aplikace. Další informace najdete v tématu o poskytovateli konfigurace Azure Key Vault v ASP.NET Core.

Proměnné prostředí

Při použití výchozí konfigurace se EnvironmentVariablesConfigurationProvider načte konfigurace z párů klíč-hodnota proměnné prostředí po přečtení appsettings.jsona appsettings.{Environment}.jsontajných kódů uživatele. Proto hodnoty klíče načtené z prostředí přepíší hodnoty přečtené z appsettings.json, appsettings.{Environment}.jsona tajné kódy uživatele.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. __, dvojité podtržítko:

Podporováno všemi platformami. Například : oddělovač Bash nepodporuje, ale __ je.
Automaticky nahrazeno :

Následující set příkazy:

Nastavte klíče prostředí a hodnoty předchozího příkladu ve Windows.
Otestujte nastavení při použití 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í:

Jsou nastaveny pouze v procesech spuštěných z příkazového okna, ve které byly nastaveny.
Prohlížeče spuštěné v sadě Visual Studio nečtou.

Následující příkazy setx lze použít k nastavení klíčů a hodnot prostředí ve Windows. Na rozdíl od setnastavení setx se zachovají. /M nastaví proměnnou v systémovém prostředí. /M Pokud přepínač nepoužíváte, 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

Chcete-li otestovat, že předchozí příkazy přepíší appsettings.json a appsettings.{Environment}.json:

Pomocí sady Visual Studio: Ukončete a restartujte Visual Studio.
Pomocí rozhraní příkazového řádku: Spusťte nové příkazové okno a zadejte dotnet run.

Voláním AddEnvironmentVariables řetězce zadejte předponu pro proměnné prostředí:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

V předchozím kódu:

config.AddEnvironmentVariables(prefix: "MyCustomPrefix_") se přidá za výchozí zprostředkovatele konfigurace. Příklad řazení poskytovatelů konfigurace najdete v tématu JSOn Configuration Provider.
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.

Předpona se při čtení párů klíč-hodnota konfigurace odstraní.

Následující příkazy otestují vlastní předponu:

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_ předpony se používají ASP.NET Core pro konfiguraci hostitele a aplikace, ale ne pro konfiguraci uživatele. Další informace o konfiguraci hostitele a aplikace naleznete v tématu .NET Generic Host.

Na Azure App Service na stránce Konfigurace nastavení > vyberte Nové nastavení aplikace. Azure App Service nastavení aplikace jsou:

Zašifrované neaktivní a přenášené přes šifrovaný kanál
Vystaveno jako proměnné prostředí.

Další informace najdete v tématu Azure Apps: Přepsání konfigurace aplikace pomocí webu Azure Portal.

Informace o připojovacích řetězcích databáze Azure najdete v tématu Předpony připojovacích řetězců připojovacího řetězce připojovacího řetězce.

Pojmenování proměnných 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 launchSettings.json

Proměnné prostředí nastavené v launchSettings.json přepsání těchto nastavení v systémovém prostředí. Například webové šablony ASP.NET Core generují launchSettings.json soubor, který nastaví konfiguraci koncového bodu na:

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

Konfigurace applicationUrl sad proměnných ASPNETCORE_URLS prostředí a přepsání hodnot nastavených v prostředí

Řídicí proměnné prostředí v Linuxu

V Linuxu musí být hodnota proměnných prostředí URL uchycená, aby systemd ji bylo možné analyzovat. Použití linuxového nástroje systemd-escape , který přináší http:--localhost:5001

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

Zobrazení proměnných prostředí

Následující kód zobrazí 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í:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var config = host.Services.GetRequiredService<IConfiguration>();

    foreach (var c in config.AsEnumerable())
    {
        Console.WriteLine(c.Key + " = " + c.Value);
    }
    host.Run();
}

Příkazový řádek

Při použití výchozí konfigurace načte CommandLineConfigurationProvider konfiguraci z párů klíč-hodnota argumentu příkazového řádku za následujícími zdroji konfigurace:

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

Ve výchozím nastavení hodnoty konfigurace nastavené na příkazovém řádku přepíší konfigurační hodnoty nastavené se všemi ostatními poskytovateli 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 =nebo klíč musí mít předponu -- nebo / když hodnota následuje za mezerou.
Pokud se používá, nevyžaduje = se. Například, MySetting=.

Ve stejném příkazu nekombinujte páry klíč-hodnota argumentu příkazového řádku, které se používají = u párů klíč-hodnota, které používají mezeru.

Mapování přepínačů

Mapování přepínačů umožňují logiku nahrazení názvů klíčů . Zadejte slovník náhradních přepínačů metody AddCommandLine .

Při použití slovníku mapování přepínačů se vyhledá klíč, který odpovídá klíči poskytnutému argumentem příkazového řádku. Pokud se klíč příkazového řádku najde ve slovníku, předá se hodnota slovníku zpět, aby se pár klíč-hodnota nastavil do konfigurace aplikace. Mapování přepínače se vyžaduje pro libovolný klíč příkazového řádku s předponou s jednou pomlčkou (-).

Přepnout pravidla klíče slovníku mapování:

Přepínače musí začínat nebo ---.
Slovník mapování přepínačů nesmí obsahovat duplicitní klíče.

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

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Následující kód ukazuje hodnoty klíče 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"]}'");
    }
}

Při testování nahrazení klíče funguje následující příkaz:

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

U aplikací, které používají mapování přepínačů, by volání nemělo předávat CreateDefaultBuilder argumenty. Volání CreateDefaultBuilder metody AddCommandLine neobsahuje mapované přepínače a neexistuje žádný způsob, jak předat slovník mapování přepínačů do CreateDefaultBuilder. Řešení nepředává argumenty CreateDefaultBuilder , ale umožňuje ConfigurationBuilder metodě 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

Následující obrázek ukazuje nastavení prostředí a argumentů příkazového řádku pomocí sady Visual Studio:

Karta Ladění VS

V sadě Visual Studio 2019 verze 16.10 Preview 4 a novější se z uživatelského rozhraní profilů spuštění provádí nastavení prostředí a argumentů příkazového řádku:

uživatelské rozhraní profilů spuštění

Hierarchická konfigurační data

Rozhraní API konfigurace čte hierarchická konfigurační data zploštěním hierarchických dat pomocí oddělovače v konfiguračních klíčích.

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

{
  "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 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 naleznete v tématu Vytvoření vazby hierarchických konfiguračních dat v tomto dokumentu.

GetSection a GetChildren metody jsou k dispozici k izolaci oddílů a podřízených částí v konfiguračních datech. Tyto metody jsou popsány dále v GetSection, GetChildren a Exists.

Konfigurační klíče a hodnoty

Konfigurační klíče:

Nerozlišují malá a velká písmena. Například ConnectionString a connectionstring jsou považovány za ekvivalentní klíče.
Pokud je klíč a hodnota nastavená ve více než jednom poskytovateli konfigurace, použije se hodnota od posledního přidaného zprostředkovatele. Další informace naleznete v tématu Výchozí konfigurace.
Hierarchické klíče
- V rámci rozhraní CONFIGURATION API funguje oddělovač dvojtečky (:) na všech platformách.
- V proměnných prostředí nemusí oddělovač dvojtečky fungovat na všech platformách. Dvojité podtržítko, __je podporováno všemi platformami a je automaticky převedeno na dvojtečku :.
- V Azure Key Vault se hierarchické klíče používají -- jako oddělovač. Poskytovatel konfigurace Azure Key Vault automaticky nahradí, když se tajné kódy --: načtou do konfigurace aplikace.
Podporuje ConfigurationBinder vazby polí na objekty pomocí maticových indexů v konfiguračních klíčích. Maticová vazba je popsána v části Vytvoření vazby pole k oddílu třídy .

Hodnoty konfigurace:

Jsou řetězce.
Hodnoty null nelze uložit v konfiguraci ani vázané na objekty.

Zprostředkovatelé konfigurace

V následující tabulce jsou uvedeni poskytovatelé konfigurace, kteří jsou k dispozici pro ASP.NET Core aplikace.

Poskytovatel	Poskytuje konfiguraci z
Poskytovatel konfigurace Azure Key Vault	Azure Key Vault
Aplikace Azure zprostředkovatele konfigurace	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áře
Zprostředkovatel konfigurace paměti	Kolekce v paměti
Tajné kódy uživatelů	Soubor v adresáři profilu uživatele

Typická posloupnost poskytovatelů konfigurace je:

appsettings.json
appsettings.{Environment}.json
Tajné kódy uživatelů
Proměnné prostředí používající zprostředkovatele konfigurace proměnných prostředí
Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku

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

Předpony připojovacího řetězce

Předpona připojovacího řetězce	Poskytovatel
`CUSTOMCONNSTR_`	Vlastní zprostředkovatel
`MYSQLCONNSTR_`	MySQL
`SQLAZURECONNSTR_`	Azure SQL Database
`SQLCONNSTR_`	SQL Server

Při zjištění a načtení proměnné prostředí do konfigurace s některou ze čtyř předpon zobrazených v tabulce:

Konfigurační klíč se vytvoří odebráním předpony proměnné prostředí a přidáním oddílu 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 stavované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 se nevytvořila.
`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 souborů

FileConfigurationProvider je základní třída pro načítání konfigurace ze systému souborů. Následující poskytovatelé konfigurace pocházejí z FileConfigurationProvider:

Zprostředkovatel konfigurace INI
JSZprostředkovatel konfigurace ON
Zprostředkovatel konfigurace XML

Zprostředkovatel konfigurace INI

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

Následující kód vymaže všechny poskytovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

V předchozím kódu se nastavení v souborech MyIniConfig.ini přepíše MyIniConfig.{Environment}.ini nastavením v následující části:

Zprostředkovatel konfigurace proměnných prostředí
Zprostředkovatel konfigurace příkazového řádku

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

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

JSZprostředkovatel konfigurace ON

Načtení JsonConfigurationProvider konfigurace z JSpárů klíč-hodnota souboru ON.

Přetížení můžou určovat:

Jestli je soubor nepovinný.
Jestli se konfigurace znovu načte, pokud se soubor změní.

Vezměme si následující kód:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Předchozí kód:

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

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

Následující kód vymaže všechny poskytovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                                     optional: true, reloadOnChange: true);

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

V předchozím kódu nastavení v souboru MyConfig.json a MyConfig.Environment. soubory json :

Přepište nastavení v souborech appsettings.json a appsettings.{Environment}.json souborech.
Jsou přepsány nastavením v zprostředkovateli konfigurace proměnných prostředí a poskytovatelem konfigurace příkazového řádku.

Ukázkový soubor ke stažení obsahuje následující MyConfig.json soubor:

{
  "Position": {
    "Title": "My Config title",
    "Name": "My Config Smith"
  },
  "MyKey":  "MyConfig.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}");
    }
}

Zprostředkovatel konfigurace XML

Načtení XmlConfigurationProvider konfigurace z párů klíč-hodnota souboru XML za běhu.

Následující kód vymaže všechny poskytovatele konfigurace a přidá několik zprostředkovatelů konfigurace:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

V předchozím kódu se nastavení v souborech MyXMLFile.xml přepíše MyXMLFile.{Environment}.xml nastavením v následující části:

Zprostředkovatel konfigurace proměnných prostředí
Zprostředkovatel konfigurace příkazového řádku

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

<?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 prvky, které používají stejný název elementu, fungují, pokud name se atribut používá k rozlišení prvků:

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

Atributy lze použít k zadání hodnot:

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

key:attribute
section:key:attribute

Poskytovatel konfigurace klíče na soubor

Chcete-li aktivovat konfiguraci klíče na soubor, zavolejte metodu AddKeyPerFile rozšíření instance .ConfigurationBuilder K directoryPath souborům musí být absolutní cesta.

Přetížení umožňují zadat:

Delegát Action<KeyPerFileConfigurationSource> , který nakonfiguruje zdroj.
Určuje, jestli je adresář volitelný a cesta k adresáři.

Volání ConfigureAppConfiguration při sestavování hostitele 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 paměti

Používá MemoryConfigurationProvider kolekci v paměti jako páry klíč-hodnota konfigurace.

Následující kód přidá kolekci paměti do konfiguračního systému:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

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

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

Viz Vytvoření vazby pole pro jiný příklad pomocí MemoryConfigurationProvider.

Kestrel konfigurace koncového bodu

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

Zvažte následující appsettings.json soubor 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": "*"
}

Když se v ASP.NET Core webové aplikaci použije předchozí zvýrazněný kód a aplikace se spustí na příkazovém řádku s následující konfigurací koncového bodu mezi servery:

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

Kestrel vytvoří vazbu ke koncovému bodu nakonfigurovaného speciálně pro Kestrel soubor appsettings.json (https://localhost:9999) a ne https://localhost:7777.

Kestrel Zvažte konkrétní koncový bod nakonfigurovaný jako proměnnou prostředí:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

GetValue

ConfigurationBinder.GetValue extrahuje jednu hodnotu z konfigurace se zadaným klíčem a převede ji na zadaný typ. Tato metoda je metoda rozšíření pro IConfiguration:

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 konfiguraci nenajde předchozí kód NumberKey , použije se výchozí hodnota 99 .

GetSection, GetChildren a Existuje

Příklady, které následují, zvažte následující MySubsection.json soubor:

{
  "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:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MySubsection.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Getsection

IConfiguration.GetSection vrátí pododdíl konfigurace se zadaný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 se nevrátí null. Pokud se odpovídající oddíl nenajde, vrátí se prázdný IConfigurationSection oddíl.

Když GetSection vrátí odpovídající oddíl, Value nezaplní se. A Key a Path vrátí se, když oddíl existuje.

GetChildren a existuje

Následující volání IConfiguration.GetChildren kódu a vrátí hodnoty pro section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

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

    public ContentResult OnGet()
    {
        string s = null;
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new System.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í volání ConfigurationExtensions.Exists kódu pro ověření, že oddíl existuje:

Vytvoření vazby pole

Zvažte 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:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyArray.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Následující kód nač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>();
        string s = null;

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

        return Content(s);
    }
}

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 value40odpovídající "4": "value40", hodnotě v MyArray.json. Indexy vázaného pole jsou souvislé a nejsou vázány na index konfiguračního klíče. Vazač konfigurace nemůže vytvořit hodnoty null nebo vytvářet položky null v vázaných objektech.

Následující kód načte array:entries konfiguraci pomocí AddInMemoryCollection metody rozšíření:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Následující kód načte konfiguraci a arrayDictDictionary 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>();
        string s = null;

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

        return Content(s);
    }
}

Předchozí kód vrátí následující výstup:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value4
Index: 4  Value: value5

Index č. 3 v vázaném objektu obsahuje konfigurační data pro array:4 konfigurační klíč a jeho hodnotu value4. Při vazbě konfiguračních dat obsahujících pole se indexy polí v konfiguračních klíčích používají k iteraci konfiguračních dat při vytváření objektu. Hodnotu null nelze zachovat v konfiguračních datech a položka s hodnotou null není vytvořena v vázaném objektu, když pole v klíčích konfigurace vynechá jeden nebo více indexů.

Chybějící položku konfigurace pro index č. 3 je možné zadat před vazbou na ArrayExample instanci libovolným poskytovatelem konfigurace, který čte dvojici klíč/hodnota indexu #3. Podívejte se na následující Value3.json soubor z ukázkového stažení:

{
  "array:entries:3": "value3"
}

Následující kód obsahuje konfiguraci proValue3.json:arrayDictDictionary

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile("Value3.json",
                                    optional: false, reloadOnChange: false);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Následující kód přečte předchozí 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>();
        string s = null;

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

        return Content(s);
    }
}

Předchozí kód vrátí následující výstup:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value3
Index: 4  Value: value4
Index: 5  Value: value5

Vlastní poskytovatelé konfigurace nejsou potřeba k implementaci vazby pole.

Vlastní zprostředkovatel konfigurace

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

Poskytovatel má následující charakteristiky:

Databáze EF v paměti se používá pro demonstrační účely. Pokud chcete použít databázi, která vyžaduje připojovací řetězec, implementujte sekundární ConfigurationBuilder řetězec pro zadání připojovacího řetězce od jiného zprostředkovatele konfigurace.
Zprostředkovatel při spuštění načte tabulku databáze do konfigurace. Zprostředkovatel se na databázi dotazuje podle klíče.
Opětovné načtení změny není implementováno, takže aktualizace databáze po spuštění aplikace nemá žádný vliv na konfiguraci aplikace.

Definujte entitu EFConfigurationValue pro ukládání hodnot konfigurace v databázi.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

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

EFConfigurationProvider/EFConfigurationContext.cs:

// using Microsoft.EntityFrameworkCore;

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

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Vytvoření třídy, která implementuje IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

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

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

EFConfigurationProvider/EFConfigurationProvider.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Metoda AddEFConfiguration rozšíření umožňuje přidat zdroj konfigurace do .ConfigurationBuilder

Extensions/EntityFrameworkExtensions.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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 kód:Program.cs

// using Microsoft.EntityFrameworkCore;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddEFConfiguration(
                options => options.UseInMemoryDatabase("InMemoryDb"));
        })

Konfigurace přístupu při spuštění

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

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Příklad přístupu ke konfiguraci pomocí metod usnadnění spouštění najdete v tématu Spuštění aplikace: Metody pohodlí.

Konfigurace přístupu na Razor stránkách

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

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

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

V následujícím kódu MyOptions se přidá do kontejneru služby s Configure vazbou na konfiguraci:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));

    services.AddRazorPages();
}

Následující kód používá direktivu @injectRazor k vyřešení a zobrazení hodnot možností:

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


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

Konfigurace přístupu 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"]

Konfigurace možností pomocí delegáta

Možnosti nakonfigurované v delegátu přepíší hodnoty nastavené v zprostředkovatelích konfigurace.

Konfigurace možností pomocí delegáta se demonstruje jako příklad 2 v ukázkové aplikaci.

V následujícím kódu IConfigureOptions<TOptions> se služba přidá do kontejneru služby. Používá delegáta ke konfiguraci hodnot pro MyOptions:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "Value configured in delegate";
        myOptions.Option2 = 500;
    });

    services.AddRazorPages();
}

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 jsou zadány a appsettings.json následně přepsány nakonfigurovaným delegátem.

Konfigurace hostitele a aplikace

Výchozí konfigurace hostitele

Podrobnosti o výchozí konfiguraci při použití webového hostitele najdete v tématu ASP.NET Core verze 2.2.

Konfigurace hostitele je k dispozici z:
- Proměnné prostředí s předponou DOTNET_ (například DOTNET_ENVIRONMENT) pomocí zprostředkovatele konfigurace proměnných prostředí. Předpona (DOTNET_) se odstraní při načtení párů klíč-hodnota konfigurace.
- Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku
Vytvoří se výchozí konfigurace webového hostitele (ConfigureWebHostDefaults):
- Kestrel se používá jako webový server a konfiguruje pomocí zprostředkovatelů konfigurace aplikace.
- Přidejte middleware filtrování hostitelů.
- Pokud je proměnná prostředí nastavená na truehodnotu , přidejte middleware Forwarded Headers Middleware ASPNETCORE_FORWARDEDHEADERS_ENABLED .
- Povolte integraci služby IIS.

Jiná konfigurace

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

Proměnné prostředí nastavené v launchSettings.json přepsání těchto nastavení v systémovém prostředí.

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