Konfigurace v ASP.NET Core

Od Rick Anderson a Kirka Larkin

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

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

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

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Výchozí konfigurace

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

var builder = WebApplication.CreateBuilder(args);

WebApplication. CreateBuilder Inicializuje novou instanci WebApplicationBuilder třídy s předem konfigurovanými výchozími hodnotami. Inicializovaná WebApplicationBuilder ( builder ) poskytuje výchozí konfiguraci pro aplikaci v následujícím pořadí:

  1. ChainedConfigurationProvider : Přidá existující IConfiguration jako zdroj. Ve výchozím případu konfigurace přidá konfiguraci hostitele a nastaví ji jako první zdroj konfigurace aplikace .
  2. appsettings.json pomocí zprostředkovatele konfigurace JSON.
  3. appSettings. Environment . JSON s použitím poskytovatele konfigurace JSON. Například appSettings. Výroba * * _._json a appSettings. * * * vývoj _._json *.
  4. Tajné kódy aplikace v případě, že aplikace běží v Development prostředí
  5. Proměnné prostředí pomocí poskytovatele konfigurace proměnných prostředí.
  6. Argumenty příkazového řádku, které používají poskytovatele konfigurace příkazového řádku.

Poskytovatelé konfigurace, kteří jsou přidáni později, přepíší předchozí nastavení klíče. Pokud MyKey je například nastaveno v obou appsettings.json 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í poskytovatele.

Další informace o najdete v CreateBuilder tématu výchozí nastavení tvůrce.

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

Vezměte v úvahu 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 v ukázkovém souboru ke stažení zobrazuje 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í:

  1. appsettings.json
  2. appSettings. Environment . JSON : například appSettings. Produkční * * _._json a appSettings. * * * vývojové _._json * souborů. Verze prostředí souboru se načte na základě IHostingEnvironment. Environment. Další informace naleznete v tématu Používání více prostředí v ASP.NET Core.

appSettings. Environment .. hodnoty JSON přepisují klíče v appsettings.json . Ve výchozím nastavení by například:

  • Ve vývoji, appSettings. *Development _._json * konfigurace Přepisuje hodnoty, které byly nalezeny v appsettings.json .
  • V produkčním prostředí appSettings. *produkční _._json * konfigurace Přepisuje hodnoty nalezené v appsettings.json . Například při nasazení aplikace do Azure.

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

Pomocí výchozí konfigurace, appsettings.json a appSettings. Environment soubory . JSON jsou povolené pomocí reloadOnChange: true. Změny provedené v rozhraních appsettings.json appSettings a. Environment soubor . JSON po spuštění aplikace si přečte Poskytovatel konfigurace JSON.

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

Upřednostňovaným způsobem, jak číst související konfigurační hodnoty, je použít vzor možností. Například pro čtení následujících konfiguračních hodnot:

  "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 možností:

  • Musí být neabstraktní s veřejným konstruktorem bez parametrů.
  • Všechny veřejné vlastnosti pro čtení i zápis typu jsou vázané.
  • Pole nejsou svázána . V předchozím kódu Position není svázána. Tato Position vlastnost se používá, takže řetězec "Position" nemusí být v aplikaci pevně kódovaný při vytváření vazby třídy ke zprostředkovateli konfigurace.

Následující kód:

  • Volá ConfigurationBinder. Bind pro svázání PositionOptions třídy s Position oddílem.
  • Zobrazí Position 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}");
    }
}

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

ConfigurationBinder.Get<T> vytvoří vazby 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žít 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}");
    }
}

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

Alternativním přístupem při použití vzoru * Options _ je svázání Position oddílu a jeho přidání do kontejneru služby pro vkládání závislostí. V následujícím kódu PositionOptions je přidán do kontejneru služby s <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> konfigurací a vázaný 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 souboru JSON po zahájení aplikace nečtou. Pokud chcete po spuštění aplikace přečíst změny, použijte IOptionsSnapshot.

Pomocí výchozí konfigurace, appsettings.json a appSettings. Environment soubory . JSON jsou povolené pomocí reloadOnChange: true. Změny provedené v rozhraních appsettings.json appSettings a. Environment soubor . JSON po spuštění aplikace si přečte Poskytovatel konfigurace JSON.

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

Kombinování kolekce služeb

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

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

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

var app = builder.Build();

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

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

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

            return services;
        }
    }
}

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. Například přidá řadiče MVC služeb s vyžadováním zobrazení a přidá AddControllersWithViews AddRazorPages služby, které Razor stránky vyžadují. Doporučujeme, aby aplikace postupují podle konvence vytváření názvů metod rozšíření v oboru Microsoft.Extensions.DependencyInjection názvů . Vytváření rozšiřujících metod v oboru Microsoft.Extensions.DependencyInjection názvů :

Zabezpečení a tajné klíče uživatele

Pokyny pro konfigurační data:

  • Nikdy neukládejte hesla nebo další citlivá data v kódu poskytovatele konfigurace nebo v konfiguračních souborech s prostým textem. Nástroj správce tajných klíčů je možné použít k ukládání tajných kódů do vývoje.
  • Nepoužívejte provozní tajemství ve vývojových nebo testovacích prostředích.
  • Zadejte tajné klíče mimo projekt, aby se nemohly omylem potvrdit do úložiště zdrojového kódu.

Ve výchozím nastaveníje zdroj konfigurace tajných kódů uživatelů zaregistrován po zdrojích konfigurace JSON. Proto klíče uživatelských tajných klíčů mají přednost před klíči v appsettings.json a appSettings. Environment . JSON.

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

Azure Key Vault bezpečně ukládá tajné klíče aplikace pro ASP.NET Core aplikace. Další informace naleznete v tématu Poskytovatel konfigurace Azure Key Vault v ASP.NET Core.

Proměnné prostředí

Při použití výchozí konfigurace EnvironmentVariablesConfigurationProvider načte konfigurace z proměnných prostředí páry klíč-hodnota po čtení appsettings.json , appSettings. Environment . JSON a tajné klíče uživatele. Proto hodnoty klíčů načtené z prostředí přepisují hodnoty načtené z appsettings.json , appSettings. Environment . JSON a tajné klíče uživatele.

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

  • Podporováno všemi platformami. Například : oddělovač není podporován bash, ale __ je.
  • Automaticky nahrazeno :

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

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ém byly nastaveny.
  • Nebude číst prohlížečem spuštěným s Visual Studio.

Následující příkazy setx lze použít k nastavení klíčů a hodnot prostředí pro Windows. Na rozdíl set od setx platí, že nastavení jsou trvalá. /M nastaví proměnnou v prostředí systému. Pokud se /M přepínač nepoužívá, je nastavena proměnná prostředí uživatele.

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

Chcete-li otestovat předchozí příkazy přepsání appsettings.json a appSettings. Environment . JSON:

  • pomocí Visual Studio: ukončete a znovu spusťte Visual Studio.
  • Pomocí rozhraní příkazového řádku: spusťte nové příkazové okno a zadejte dotnet run .

Volání AddEnvironmentVariables s řetězcem pro určení předpony pro proměnné prostředí:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

V předchozím kódu:

Pokud jsou načteny páry klíč-hodnota konfigurace, je předpona odstraněna.

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

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

Výchozí konfigurace načte proměnné prostředí a argumenty příkazového řádku s předponou DOTNET_ a ASPNETCORE_ . DOTNET_ ASPNETCORE_ předpony a jsou používány ASP.NET Core pro konfiguraci hostitele a aplikace, ale ne pro konfiguraci uživatele. Další informace o konfiguraci hostitele a aplikace najdete v tématu obecný hostitel .NET.

v Azure App Servicena stránce konfigurace > Nastavení vyberte nové nastavení aplikace . Azure App Service nastavení aplikace:

  • Šifrované v klidovém stavu a přenášené přes zašifrovaný kanál.
  • Vystaveno jako proměnné prostředí.

Další informace najdete v tématu aplikace Azure: přepište konfiguraci aplikace pomocí webu Azure Portal.

Informace o připojovacích řetězcích Azure Database najdete v tématu předpony připojovacího řetězce .

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

Názvy proměnných prostředí odrážejí strukturu appsettings.json souboru. Každý prvek v hierarchii je oddělen dvojitým podtržítkem (vhodnějším) nebo dvojtečkou. Pokud struktura prvku obsahuje pole, index pole by měl být v této cestě zpracován jako další název elementu. Vezměte v úvahu 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é v generovaném souboru launchSettings. JSON

Proměnné prostředí nastavené v launchSettings. JSON přepíší ty nastavené v prostředí systému. například ASP.NET Core webové šablony generují soubor launchSettings. json , který nastaví konfiguraci koncového bodu na:

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

Konfigurace applicationUrl nastavuje ASPNETCORE_URLS proměnnou prostředí a Přepisuje hodnoty nastavené v prostředí.

Proměnné ukončovacího prostředí v systému Linux

V systému Linux musí být hodnota proměnných prostředí URL uvozena řídicím znakem, aby systemd ji bylo možné analyzovat. Použijte nástroj pro Linux, systemd-escape který poskytuje http:--localhost:5001

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

Zobrazit proměnné prostředí

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

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

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

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

Příkazový řádek

Použijete-li výchozí konfiguraci, CommandLineConfigurationProvider načte konfiguraci z dvojice klíč-hodnota argumentu klíč-hodnota po následujících zdrojích konfigurace:

  • appsettings.json a appSettings. Environment .. soubory JSON .
  • Tajné klíče aplikace ve vývojovém prostředí
  • Proměnné prostředí.

Ve výchozím nastaveníjsou konfigurační hodnoty nastavené pro přepisy hodnot konfigurace na příkazovém řádku nastavené se všemi ostatními zprostředkovateli konfigurace.

Argumenty příkazového řádku

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

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

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

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

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

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

Hodnota klíče:

  • Musí následovat po = , nebo klíč musí mít předponu -- nebo, / Pokud se hodnota řídí mezerou.
  • Není vyžadováno = , pokud je použit. Například, MySetting=.

V rámci stejného příkazu Nekombinujte páry klíč-hodnota argumentu příkazového řádku, které = se používají s páry klíč-hodnota, které používají mezeru.

Mapování přepínačů

Mapování přepínačů povolují logiku nahrazení názvu klíče . Poskytněte slovník pro nahrazení přepínačů v AddCommandLine metodě.

Při použití slovníku mapování přepínačů je slovník zaškrtnut pro klíč, který odpovídá klíči poskytnutému argumentem příkazového řádku. Pokud se klíč příkazového řádku nachází ve slovníku, vrátí se hodnota Dictionary zpátky, aby se v konfiguraci aplikace nastavil pár klíč-hodnota. Mapování přepínačů je vyžadováno pro jakýkoliv klíč příkazového řádku s jednou pomlčkou ( - ).

Pravidla klíče slovníku mapování přepínačů:

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

Chcete-li použít slovník mapování přepínačů, předejte jej 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();

Spusťte následující příkaz, který vám umožní otestovat nahrazení klíče:

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

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

Pro aplikace, které používají mapování přepínačů, by volání CreateDefaultBuilder nemělo předávat argumenty. CreateDefaultBuilder AddCommandLine Volání metody nezahrnuje mapované přepínače a neexistuje způsob, jak předat slovníku mapování přepínačů na CreateDefaultBuilder . Řešení nebude předávat argumenty, CreateDefaultBuilder ale místo toho, aby ConfigurationBuilder Metoda metody mohla AddCommandLine zpracovat argumenty i slovník mapování přepínačů.

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

argumenty prostředí a příkazového řádku je možné nastavit v Visual Studio dialogového okna spouštěcí profily:

  • V Průzkumník řešení vpravo klikněte projekt a vyberte vlastnosti.
  • Vyberte kartu ladit > obecné a vyberte otevřít a spustit ladicí uživatelské rozhraní profily.

Hierarchická konfigurační data

Rozhraní API pro konfiguraci čte hierarchická konfigurační data sloučením hierarchických dat s použitím oddělovače v konfiguračních klíčích.

Ukázka 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 v ukázkovém souboru ke stažení zobrazuje několik nastavení konfigurace:

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

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

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


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

Upřednostňovaným způsobem, jak číst hierarchická konfigurační data, je použít vzor možností. Další informace najdete v tématu vázání hierarchických konfiguračních dat v tomto dokumentu.

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

Konfigurační klíče a hodnoty

Konfigurační klíče:

  • Rozlišují se 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 poskytovatelích konfigurace, použije se hodnota z posledního přidaného zprostředkovatele. Další informace najdete v tématu výchozí konfigurace.
  • Hierarchické klíče
    • V rozhraní API pro konfiguraci 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 hierarchické klíče používají -- jako oddělovač. Poskytovatel konfigurace Azure Key Vault se -- : při načtení tajných klíčů do konfigurace aplikace automaticky nahradí.
  • ConfigurationBinderPodporuje vazby polí na objekty pomocí indexů pole v konfiguračních klíčích. Vazba pole je popsána v tématu vazba pole na oddíl třídy .

Konfigurační hodnoty:

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

Zprostředkovatelé konfigurace

v následující tabulce jsou uvedeny poskytovatelé konfigurace dostupné pro ASP.NET Core aplikace.

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

Zdroje konfigurace jsou čteny v pořadí, ve kterém jsou zadáni poskytovatelé konfigurace. Seřazení zprostředkovatelů konfigurace v kódu, aby odpovídal prioritám pro základní zdroje konfigurace vyžadované aplikací.

Typická posloupnost zprostředkovatelů konfigurace je:

  1. appsettings.json
  2. appSettings. Environment .. formát JSON
  3. Tajné klíče uživatele
  4. Proměnné prostředí pomocí poskytovatele konfigurace proměnných prostředí.
  5. Argumenty příkazového řádku, které používají poskytovatele konfigurace příkazového řádku.

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

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

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

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

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

Když je proměnná prostředí zjištěna a načtena do konfigurace se všemi čtyřmi předponami, které jsou uvedeny v tabulce:

  • Konfigurační klíč se vytvoří odebráním předpony proměnné prostředí a přidáním konfiguračního klíče ( ConnectionStrings ).
  • Vytvoří se nová dvojice klíč-hodnota konfigurace, která představuje poskytovatele připojení databáze (s výjimkou CUSTOMCONNSTR_ , který nemá zadaného poskytovatele).
Klíč proměnné prostředí Konfigurační klíč převedený na převod Položka konfigurace zprostředkovatele
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Položka konfigurace není vytvořená.
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 souboru

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

Poskytovatel konfigurace INI

IniConfigurationProviderNačítá 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 poskytovatelů konfigurace: [!code-csharp]

V předchozím kódu nastavení MyIniConfig.ini a MyIniConfig. Environment . soubory ini jsou přepsány nastavením v:

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

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Následující kód v ukázkovém souboru ke stažení zobrazuje několik předchozích nastavení konfigurace:

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

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

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


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

Zprostředkovatel konfigurace JSON

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

Přetížení můžou specifikovat:

  • Zda je soubor nepovinný.
  • Určuje, zda je konfigurace znovu načtena v případě, že dojde ke změně souboru.

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:

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

Poskytovatel konfigurace XML

XmlConfigurationProviderNačítá konfiguraci 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 poskytovatelů 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 nastavení MyXMLFile.xml a MyXMLFile. Environment . soubory XML jsou přepsány nastavením v:

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

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

Následující kód v ukázkovém souboru ke stažení zobrazuje 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 je atribut použit 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ává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 pomocí value :

  • Key: – atribut
  • oddíl: klíč: atribut

Poskytovatel konfigurace klíče na soubor

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

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

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

  • Action<KeyPerFileConfigurationSource>Delegát, který konfiguruje zdroj.
  • Zda je adresář nepovinný a cesta k adresáři.

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

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

Poskytovatel konfigurace paměti

MemoryConfigurationProviderPoužívá kolekci v paměti jako konfigurační páry klíč-hodnota.

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

var builder = WebApplication.CreateBuilder(args);

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

builder.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 v ukázkovém souboru ke stažení zobrazuje předchozí nastavení konfigurace:

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

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

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


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

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

Viz vazba pole pro jiný příklad pomocí MemoryConfigurationProvider .

Kestrel konfigurace koncového bodu

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

vezměte v úvahu následující soubor, který se appsettings.json používá ve ASP.NET Core webové aplikaci:

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

když se předchozí zvýrazněný kód používá ve ASP.NET Core webové aplikaci 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ří vazby ke koncovému bodu nakonfigurovanému konkrétně pro Kestrel v appsettings.json souboru ( https://localhost:9999 ) a ne https://localhost:7777 .

Vezměte v úvahu Kestrel konkrétní koncový bod nakonfigurovaný jako proměnnou prostředí:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

V předchozí proměnné prostředí Https je název Kestrel konkrétního koncového bodu. Předchozí appsettings.json soubor také definuje Kestrel konkrétní koncový bod s názvem Https . Ve výchozím nastaveníjsou proměnné prostředí s použitím poskytovatele konfigurace proměnných prostředí čteny po appSettings. Environment . JSON, pro koncový bod se proto používá předchozí proměnná prostředí Https .

GetValue

ConfigurationBinder.GetValue<T> 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 v předchozím kódu NumberKey není v konfiguraci nalezeno, 99 je použita výchozí hodnota.

GetSection, GetChildren a Exists

V následujících příkladech zvažte následující soubor MySubsection. JSON :

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

Následující kód přidá MySubsection. JSON ke zprostředkovatelům 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í dílčí část konfigurace se zadaným klíčem dílčího oddí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 nevrátí null . Pokud se nenalezne shodný oddíl, IConfigurationSection vrátí se prázdný řetězec.

Při GetSection vrácení odpovídajícího oddílu Value není naplněna hodnota. KeyA Path se vrátí, když oddíl existuje.

GetChildren a existuje

Následující kód volá IConfiguration. GetChildren 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í kód volá ConfigurationExtensions. existuje pro ověření, zda existuje oddíl:

Vazba pole

ConfigurationBinder. Bind podporuje vazby polí na objekty pomocí indexů pole v konfiguračních klíčích. Libovolný formát pole, který zveřejňuje numerický klíčový segment, je schopný vytvořit vazbu pole k poli třídy POCO .

V ukázkovém staženízvažte myArray. JSON :

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

Následující kód přidá myArray. JSON ke zprostředkovatelům 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()
    {
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }

        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = String.Empty;

        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 odpovídající hodnotě value40 "4": "value40", v myArray. JSON. Vazby vázaného pole jsou souvislé a nejsou vázané na index konfiguračního klíče. Pořadač konfigurace nemůže svázat hodnoty null ani vytvářet položky null v svázaných objektech.

Vlastní poskytovatel konfigurace

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

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

  • Pro demonstrační účely se používá databáze EF v paměti. Chcete-li použít databázi, která vyžaduje připojovací řetězec, implementujte sekundární ConfigurationBuilder pro zadání připojovacího řetězce od jiného poskytovatele konfigurace.
  • Poskytovatel čte databázovou tabulku do konfigurace při spuštění. Zprostředkovatel nedotazuje databázi na bázi jednotlivých klíčů.
  • Opětovné načtení není implementováno, takže aktualizace databáze po spuštění aplikace nemá žádný vliv na konfiguraci aplikace.

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

Modely/EFConfigurationValue. cs:

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

Přidejte EFConfigurationContext do úložiště a získejte přístup k nakonfigurovaným hodnotám.

EFConfigurationProvider/EFConfigurationContext. cs:

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

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

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

EFConfigurationProvider/EFConfigurationSource. cs:

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

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

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

Vytvořte vlastního poskytovatele konfigurace děděním z ConfigurationProvider . Poskytovatel konfigurace inicializuje databázi, pokud je prázdná. Vzhledem k tomu, že v konfiguračních klíčích nejsou rozlišována velká a malá písmena, je vytvořen slovník použitý k inicializaci databáze s porovnáváním bez rozlišení velký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
        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;
    }
}

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

Rozšíření/EntityFrameworkExtensions. cs:

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

Následující kód ukazuje, jak použít vlastní EFConfigurationProvider v programu. cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Přístup ke konfiguraci na Razor stránkách

Následující kód zobrazuje 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 je přidán do kontejneru služby s Configure konfigurací a vázaný 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á @inject Razor direktivu 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>

Přístup ke konfiguraci 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í s delegátem

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

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

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

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

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

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

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

V předchozím příkladu Option1 jsou hodnoty a Option2 zadány v appsettings.json a poté přepsány nakonfigurovaným delegátem.

Konfigurace versus konfigurace aplikace

Před konfigurací a spuštěním aplikace je hostitel nakonfigurovaný a spuštěný. Hostitel zodpovídá za spuštění aplikace a správu životního cyklu. Aplikace i hostitel se konfigurují pomocí zprostředkovatelů konfigurace popsaných v tomto tématu. V konfiguraci aplikace jsou také zahrnuty páry klíč-hodnota konfigurace hostitele. Další informace o tom, jak se používají poskytovatelé konfigurace, když je hostitel sestavený a jak zdroje konfigurace ovlivňují konfiguraci hostitele, najdete v tématu Základy ASP.NET Core .

Výchozí konfigurace hostitele

podrobnosti o výchozí konfiguraci při použití webového hostitelenaleznete v ASP.NET Core 2,2 verzi tohoto tématu.

  • Konfigurace hostitele se poskytuje:
  • Je navázána výchozí konfigurace webového hostitele ( ConfigureWebHostDefaults ):
    • Kestrel se používá jako webový server a je nakonfigurovaný pomocí poskytovatelů konfigurace aplikace.
    • Přidejte middleware pro filtrování hostitele.
    • Přidejte middleware předávaných hlaviček, pokud ASPNETCORE_FORWARDEDHEADERS_ENABLED je proměnná prostředí nastavena na true .
    • Povolte integraci služby IIS.

Další konfigurace

Toto téma se týká pouze Konfigurace aplikace. další aspekty používání a hostování ASP.NET Corech aplikací jsou nakonfigurované pomocí konfiguračních souborů, které nejsou popsané v tomto tématu:

Proměnné prostředí nastavené v launchSettings. JSON přepíší ty nastavené v prostředí systému.

další informace o migraci konfigurace aplikace z dřívějších verzí ASP.NET najdete v tématu Migrace z ASP.NET na ASP.NET Core .

Přidat konfiguraci z externího sestavení

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

Další zdroje informací

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

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

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

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Výchozí konfigurace

ASP.NET Core webové aplikace vytvořené pomocí příkazu dotnet new nebo Visual Studio vygenerujte 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 pro aplikaci v následujícím pořadí:

  1. ChainedConfigurationProvider : Přidá existující IConfiguration jako zdroj. Ve výchozím případu konfigurace přidá konfiguraci hostitele a nastaví ji jako první zdroj konfigurace aplikace .
  2. appsettings.json pomocí zprostředkovatele konfigurace JSON.
  3. appSettings. Environment . JSON s použitím poskytovatele konfigurace JSON. Například appSettings. Výroba * * _._json a appSettings. * * * vývoj _._json *.
  4. Tajné kódy aplikace v případě, že aplikace běží v Development prostředí
  5. Proměnné prostředí pomocí poskytovatele konfigurace proměnných prostředí.
  6. Argumenty příkazového řádku, které používají poskytovatele konfigurace příkazového řádku.

Poskytovatelé konfigurace, kteří jsou přidáni později, přepíší předchozí nastavení klíče. Pokud MyKey je například nastaveno v obou appsettings.json 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í poskytovatele.

Další informace o najdete v CreateDefaultBuilder tématu výchozí nastavení tvůrce.

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

Vezměte v úvahu 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 v ukázkovém souboru ke stažení zobrazuje 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í:

  1. appsettings.json
  2. appSettings. Environment . JSON : například appSettings. Produkční * * _._json a appSettings. * * * vývojové _._json * souborů. Verze prostředí souboru se načte na základě IHostingEnvironment. Environment. Další informace naleznete v tématu Používání více prostředí v ASP.NET Core.

appSettings. Environment .. hodnoty JSON přepisují klíče v appsettings.json . Ve výchozím nastavení by například:

  • Ve vývoji, appSettings. *Development _._json * konfigurace Přepisuje hodnoty, které byly nalezeny v appsettings.json .
  • V produkčním prostředí appSettings. *produkční _._json * konfigurace Přepisuje hodnoty nalezené v appsettings.json . Například při nasazení aplikace do Azure.

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

Pomocí výchozí konfigurace, appsettings.json a appSettings. Environment soubory . JSON jsou povolené pomocí reloadOnChange: true. Změny provedené v rozhraních appsettings.json appSettings a. Environment soubor . JSON po spuštění aplikace si přečte Poskytovatel konfigurace JSON.

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

Preferovaným způsobem čtení souvisejících hodnot konfigurace je použití vzoru možností. Pokud například chcete načí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 options:

  • Musí být ne abstrakt s veřejným konstruktorem bez parametrů.
  • Všechny veřejné vlastnosti typu pro čtení i zápis jsou svázány.
  • Pole nejsou svázaná. V předchozím kódu není Position vázaný. Vlastnost se používá, takže při vytváření vazby třídy ke zprostředkovateli konfigurace nemusí být řetězec v aplikaci Position "Position" pevný.

Následující kód:

  • Zavolá ConfigurationBinder.Bind pro PositionOptions vazbu třídy k Position oddílu.
  • Zobrazí Position 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 po spuštění aplikace čtou změny konfiguračního souboru JSON.

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žít 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 po spuštění aplikace čtou změny konfiguračního souboru JSON.

Alternativním přístupem při použití vzoru *možností _ je vytvořit vazbu oddílu a přidat ho do kontejneru služby Position injektáže závislostí. V následujícím kódu se do kontejneru služby přidá a PositionOptions <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> sváže s konfigurací :

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

Pomocí výchozí konfigurace, appsettings.json a appSettings. Environment soubory . JSON jsou povolené pomocí reloadOnChange: true. Změny provedené v rozhraních appsettings.json appSettings a. Environment soubor . JSON po spuštění aplikace si přečte Poskytovatel konfigurace JSON.

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

Kombinování kolekce služeb

Vezměte v úvahu následující ConfigureServices metodu, která registruje služby a nakonfiguruje 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í lze přesunout do metody rozšíření pro registraci služeb. Například konfigurační služby jsou přidány do následující třídy:

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

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

            return services;
        }
    }
}

Zbývající služby jsou registrovány 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á a případně nakonfiguruje služby. Například AddControllersWithViews přidá řadiče služby MVC s zobrazeními vyžaduje a AddRazorPages přidá Razor stránky služeb. Doporučujeme, aby aplikace dodržovaly zásady vytváření názvů pro vytváření rozšiřujících metod v Microsoft.Extensions.DependencyInjection oboru názvů. Vytváření rozšiřujících metod v Microsoft.Extensions.DependencyInjection oboru názvů:

  • Zapouzdřuje skupiny registrací služby.
  • Poskytuje pohodlný přístup k službě IntelliSense .

Zabezpečení a tajné klíče uživatele

Pokyny pro konfigurační data:

  • Nikdy neukládejte hesla nebo další citlivá data v kódu poskytovatele konfigurace nebo v konfiguračních souborech s prostým textem. Nástroj správce tajných klíčů je možné použít k ukládání tajných kódů do vývoje.
  • Nepoužívejte provozní tajemství ve vývojových nebo testovacích prostředích.
  • Zadejte tajné klíče mimo projekt, aby se nemohly omylem potvrdit do úložiště zdrojového kódu.

Ve výchozím nastaveníje zdroj konfigurace tajných kódů uživatelů zaregistrován po zdrojích konfigurace JSON. Proto klíče uživatelských tajných klíčů mají přednost před klíči v appsettings.json a appSettings. Environment . JSON.

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

Azure Key Vault bezpečně ukládá tajné klíče aplikace pro ASP.NET Core aplikace. Další informace naleznete v tématu Poskytovatel konfigurace Azure Key Vault v ASP.NET Core.

Proměnné prostředí

Při použití výchozí konfigurace EnvironmentVariablesConfigurationProvider načte konfigurace z proměnných prostředí páry klíč-hodnota po čtení appsettings.json , appSettings. Environment . JSON a tajné klíče uživatele. Proto hodnoty klíčů načtené z prostředí přepisují hodnoty načtené z appsettings.json , appSettings. Environment . JSON a tajné klíče uživatele.

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

  • Podporováno všemi platformami. Například : oddělovač není podporován bash, ale __ je.
  • Automaticky nahrazeno :

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

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ém byly nastaveny.
  • Nebude číst prohlížečem spuštěným s Visual Studio.

Následující příkazy setx lze použít k nastavení klíčů a hodnot prostředí pro Windows. Na rozdíl set od setx platí, že nastavení jsou trvalá. /M nastaví proměnnou v prostředí systému. Pokud se /M přepínač nepoužívá, je nastavena proměnná prostředí uživatele.

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

Chcete-li otestovat předchozí příkazy přepsání appsettings.json a appSettings. Environment . JSON:

  • pomocí Visual Studio: ukončete a znovu spusťte Visual Studio.
  • Pomocí rozhraní příkazového řádku: spusťte nové příkazové okno a zadejte dotnet run .

Volání AddEnvironmentVariables s řetězcem pro určení předpony 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:

Pokud jsou načteny páry klíč-hodnota konfigurace, je předpona odstraněna.

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

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

Výchozí konfigurace načte proměnné prostředí a argumenty příkazového řádku s předponou DOTNET_ a ASPNETCORE_ . DOTNET_ ASPNETCORE_ předpony a jsou používány ASP.NET Core pro konfiguraci hostitele a aplikace, ale ne pro konfiguraci uživatele. Další informace o konfiguraci hostitele a aplikace najdete v tématu obecný hostitel .NET.

v Azure App Servicena stránce konfigurace > Nastavení vyberte nové nastavení aplikace . Azure App Service nastavení aplikace:

  • Šifrované v klidovém stavu a přenášené přes zašifrovaný kanál.
  • Vystaveno jako proměnné prostředí.

Další informace najdete v tématu aplikace Azure: přepište konfiguraci aplikace pomocí webu Azure Portal.

Informace o připojovacích řetězcích Azure Database najdete v tématu předpony připojovacího řetězce .

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

Názvy proměnných prostředí odrážejí strukturu appsettings.json souboru. Každý prvek v hierarchii je oddělen dvojitým podtržítkem (vhodnějším) nebo dvojtečkou. Pokud struktura prvku obsahuje pole, index pole by měl být v této cestě zpracován jako další název elementu. Vezměte v úvahu 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é v generovaném souboru launchSettings. JSON

Proměnné prostředí nastavené v launchSettings. JSON přepíší ty nastavené v prostředí systému. například ASP.NET Core webové šablony generují soubor launchSettings. json , který nastaví konfiguraci koncového bodu na:

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

Konfigurace applicationUrl nastavuje ASPNETCORE_URLS proměnnou prostředí a Přepisuje hodnoty nastavené v prostředí.

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

V Linuxu musí být hodnota proměnných prostředí adresy URL uvozena, systemd aby ji bylo možné parsovat. Použití linuxového systemd-escape nástroje, 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 konfigurace z párů klíč-hodnota argumentu příkazového řádku CommandLineConfigurationProvider po následujících zdrojích konfigurace:

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

Ve výchozímnastavení přepíší konfigurační hodnoty nastavené na příkazovém řádku 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="My key from command line" 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 musí mít klíč předponu nebo , pokud hodnota následuje -- / mezeru.
  • Při použití se = nevyžaduje. Například, MySetting=.

V rámci stejného příkazu nekombinaci párů klíč-hodnota argumentu příkazového řádku, které se používají s páry = klíč-hodnota, které používají mezeru.

Mapování přepínačů

Mapování přepínačů umožňují logiku pro nahrazení názvu klíče. Uveďte slovník nahrazení přepínače pro AddCommandLine metodu .

Při použití slovníku mapování přepínačů se ve slovníku kontroluje klíč, který odpovídá klíči poskytnutému argumentem příkazového řádku. Pokud se klíč příkazového řádku nachází 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 každý klíč příkazového řádku s předponou jedné pomlčky ( - ).

Pravidla klíčů slovníku mapování přepínačů:

  • Přepínače musí začínát s - 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 metody :

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

Následující příkaz funguje k otestování nahrazení klíče:

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 CreateDefaultBuilder předávat argumenty. Volání metody neobsahuje mapované přepínače a neexistuje žádný způsob, jak předat slovník CreateDefaultBuilder AddCommandLine mapování přepínačů do CreateDefaultBuilder . Řešením není předat argumenty do , ale místo toho umožnit metodě metody zpracovat argumenty i slovník CreateDefaultBuilder ConfigurationBuilder mapování AddCommandLine přepínačů.

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

Následující obrázek znázorňuje nastavení prostředí a argumentů příkazového řádku pomocí Visual Studio:

Karta Ladění VS

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

Uživatelské rozhraní spouštěcích profilů

Hierarchická konfigurační data

Rozhraní CONFIGURATION API čte hierarchická konfigurační data tím, že zploštěl hierarchická data 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}");
    }
}

Preferovaným způsobem čtení hierarchických konfiguračních dat je použití vzoru možností. Další informace najdete v části Vytvoření vazby hierarchických konfiguračních dat v tomto dokumentu.

GetSection Metody GetChildren a jsou k dispozici pro izolaci oddílů a dětí oddílu v konfiguračních datech. Tyto metody jsou popsány dále v metodách GetSection, Get Začátečníka Existuje .

Konfigurační klíče a hodnoty

Konfigurační klíče:

  • Bez rozlišení velkých a malých písmen. Například a se ConnectionString connectionstring zachází jako s ekvivalentními klíči.
  • Pokud je klíč a hodnota nastavená ve více než jednom poskytovateli konfigurace, použije se hodnota z posledního přidaného zprostředkovatele. Další informace najdete v tématu Výchozí konfigurace.
  • Hierarchické klíče
    • V rozhraní API pro konfiguraci funguje na všech platformách oddělovač dvojtečky ( : ).
    • V proměnných prostředí nemusí na všech platformách fungovat oddělovač dvojtečky. Dvojité podtržítko __ je podporováno všemi platformami a je automaticky převedeno na dvojtečku : .
    • V Azure Key Vault hierarchické klíče používají -- jako oddělovač. Poskytovatel Azure Key Vault automaticky nahradí za , když se tajné kódy načítají do konfigurace -- : aplikace.
  • Podporuje ConfigurationBinder vazby polí na objekty pomocí indexů pole v klíčích konfigurace. Vazba pole je popsaná v části Vytvoření vazby pole k třídě.

Hodnoty konfigurace:

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

Zprostředkovatelé konfigurace

Následující tabulka uvádí poskytovatele konfigurace, kteří jsou k dispozici ASP.NET Core aplikacím.

Poskytovatel Poskytuje konfiguraci z
Azure Key Vault konfigurace Azure Key Vault
Poskytovatel konfigurace aplikací Azure Azure App Configuration
Poskytovatel konfigurace příkazového řádku Parametry příkazového řádku
Poskytovatel vlastní 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
Poskytovatel konfigurace paměti Kolekce v paměti
Tajné kódy uživatelů Soubor v adresáři profilu uživatele

Zdroje konfigurace se načítá v pořadí, v pořadí, v v pořadí, ve které jsou specifikované jejich zprostředkovatelé konfigurace. Seřídit poskytovatele konfigurace v kódu tak, aby vyhovovaly prioritám podkladových zdrojů konfigurace, které aplikace vyžaduje.

Typická posloupnost poskytovatelů konfigurace je:

  1. appsettings.json
  2. appsettings Environment . json (json)
  3. Tajné kódy uživatelů
  4. Proměnné prostředí využívající zprostředkovatele konfigurace Proměnných prostředí.
  5. Argumenty příkazového řádku pomocí zprostředkovatele konfigurace příkazového řádku.

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

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

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

Rozhraní API pro konfiguraci má zvláštní pravidla zpracování pro čtyři proměnné prostředí připojovacího řetězce. Tyto připojovací řetězce se podílejí na konfiguraci připojovacích řetězců Azure pro prostředí aplikace. Proměnné prostředí s předponami zobrazenými v tabulce se načítá do aplikace s výchozí konfigurací nebo pokud není předpona zadána pro AddEnvironmentVariables .

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

Když je proměnná prostředí zjištěna a načtena do konfigurace se všemi čtyřmi předponami, které jsou uvedeny v tabulce:

  • Konfigurační klíč se vytvoří odebráním předpony proměnné prostředí a přidáním konfiguračního klíče ( ConnectionStrings ).
  • Vytvoří se nová dvojice klíč-hodnota konfigurace, která představuje poskytovatele připojení databáze (s výjimkou CUSTOMCONNSTR_ , který nemá zadaného poskytovatele).
Klíč proměnné prostředí Konfigurační klíč převedený na převod Položka konfigurace zprostředkovatele
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Položka konfigurace není vytvořená.
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 souboru

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

Poskytovatel konfigurace INI

IniConfigurationProviderNačítá 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 poskytovatelů 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 nastavení MyIniConfig.ini a MyIniConfig. Environment . soubory ini jsou přepsány nastavením v:

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

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Následující kód v ukázkovém souboru ke stažení zobrazuje několik předchozích nastavení konfigurace:

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

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

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


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

Zprostředkovatel konfigurace JSON

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

Přetížení můžou specifikovat:

  • Zda je soubor nepovinný.
  • Určuje, zda je konfigurace znovu načtena v případě, že dojde ke změně souboru.

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:

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

Následující kód vymaže všechny poskytovatele konfigurace a přidá několik poskytovatelů 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 se jedná o nastavení v MyConfig. JSON a MyConfig. Environment . soubory JSON :

Ukázka ke stažení obsahuje následující soubor MyConfig. JSON :

{
    "Position": {
        "Title": "Můj název konfigurace",
        "Name": "My Config Smith"
    },
    "MyKey": "MyConfig.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Následující kód v ukázkovém souboru ke stažení zobrazuje 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}");
    }
}

Poskytovatel konfigurace XML

XmlConfigurationProviderNačítá konfiguraci 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 poskytovatelů 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 nastavení MyXMLFile.xml a MyXMLFile. Environment . soubory XML jsou přepsány nastavením v:

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

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

Následující kód v ukázkovém souboru ke stažení zobrazuje 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 je atribut použit 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ává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 pomocí value :

  • Key: – atribut
  • oddíl: klíč: atribut

Poskytovatel konfigurace klíče na soubor

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

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

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

  • Action<KeyPerFileConfigurationSource>Delegát, který konfiguruje zdroj.
  • Zda je adresář nepovinný a cesta k adresáři.

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

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

Poskytovatel konfigurace paměti

MemoryConfigurationProviderPoužívá kolekci v paměti jako konfigurační páry klíč-hodnota.

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

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 v ukázkovém souboru ke stažení zobrazuje předchozí nastavení konfigurace:

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

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

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


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

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

Viz vazba pole pro jiný příklad pomocí MemoryConfigurationProvider .

Kestrel konfigurace koncového bodu

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

vezměte v úvahu následující soubor, který se appsettings.json používá ve ASP.NET Core webové aplikaci:

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

když se předchozí zvýrazněný kód používá ve ASP.NET Core webové aplikaci 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ří vazby ke koncovému bodu nakonfigurovanému konkrétně pro Kestrel v appsettings.json souboru ( https://localhost:9999 ) a ne https://localhost:7777 .

Vezměte v úvahu Kestrel konkrétní koncový bod nakonfigurovaný jako proměnnou prostředí:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

V předchozí proměnné prostředí Https je název Kestrel konkrétního koncového bodu. Předchozí appsettings.json soubor také definuje Kestrel konkrétní koncový bod s názvem Https . Ve výchozím nastaveníjsou proměnné prostředí s použitím poskytovatele konfigurace proměnných prostředí čteny po appSettings. Environment . JSON, pro koncový bod se proto používá předchozí proměnná prostředí Https .

GetValue

ConfigurationBinder.GetValue<T> 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 v předchozím kódu NumberKey není v konfiguraci nalezeno, 99 je použita výchozí hodnota.

GetSection, GetChildren a Exists

V následujících příkladech zvažte následující soubor MySubsection. JSON :

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

Následující kód přidá MySubsection. JSON ke zprostředkovatelům 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í dílčí část konfigurace se zadaným klíčem dílčího oddí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 nevrátí null . Pokud se nenalezne shodný oddíl, IConfigurationSection vrátí se prázdný řetězec.

Při GetSection vrácení odpovídajícího oddílu Value není naplněna hodnota. KeyA Path se vrátí, když oddíl existuje.

GetChildren a existuje

Následující kód volá IConfiguration. GetChildren 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í kód volá ConfigurationExtensions. existuje pro ověření, zda existuje oddíl:

Vazba pole

ConfigurationBinder. Bind podporuje vazby polí na objekty pomocí indexů pole v konfiguračních klíčích. Libovolný formát pole, který zveřejňuje numerický klíčový segment, je schopný vytvořit vazbu pole k poli třídy POCO .

V ukázkovém staženízvažte myArray. JSON :

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

Následující kód přidá myArray. JSON ke zprostředkovatelům 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 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>();
        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 odpovídající hodnotě value40 "4": "value40", v myArray. JSON. Vazby vázaného pole jsou souvislé a nejsou vázané na index konfiguračního klíče. Pořadač konfigurace nemůže svázat hodnoty null ani vytvářet položky null ve 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 přečte konfiguraci v arrayDict Dictionary 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: value4
Index: 4  Value: value5

Index # 3 ve vázaném objektu obsahuje konfigurační data pro array:4 konfigurační klíč a jeho hodnotu value4 . Když jsou data konfigurace obsahující pole svázané, používají se k iteraci konfiguračních dat při vytváření objektu pole indexy v konfiguračních klíčích. Hodnotu null nelze uchovat v konfiguračních datech a v vázaném objektu není vytvořena položka s hodnotou null, pokud pole v konfiguračních klíčích přeskočí jeden nebo více indexů.

Chybějící položka konfigurace pro index # 3 se dá zadat předtím, než se vazba na instanci doplní ArrayExample jakýmkoli poskytovatelem konfigurace, který načte # dvojici klíč/hodnota indexu 3. V ukázkovém stažení zvažte následující soubor hodnota3. JSON :

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

Následující kód obsahuje konfiguraci pro hodnota3. JSON a arrayDict Dictionary :

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 k implementaci vazby pole potřeba.

Vlastní poskytovatel konfigurace

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

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

  • Pro demonstrační účely se používá databáze EF v paměti. Chcete-li použít databázi, která vyžaduje připojovací řetězec, implementujte sekundární ConfigurationBuilder pro zadání připojovacího řetězce od jiného poskytovatele konfigurace.
  • Poskytovatel čte databázovou tabulku do konfigurace při spuštění. Zprostředkovatel nedotazuje databázi na bázi jednotlivých klíčů.
  • Opětovné načtení není implementováno, takže aktualizace databáze po spuštění aplikace nemá žádný vliv na konfiguraci aplikace.

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

Modely/EFConfigurationValue. cs:

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

Přidejte EFConfigurationContext do úložiště a získejte 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řte třídu, 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);
    }
}

Vytvořte vlastního poskytovatele konfigurace děděním z ConfigurationProvider . Poskytovatel konfigurace inicializuje databázi, pokud je prázdná. Vzhledem k tomu, že v konfiguračních klíčích nejsou rozlišována velká a malá písmena, je vytvořen slovník použitý k inicializaci databáze s porovnáváním bez rozlišení velkých a malých písmen (StringComparer. OrdinalIgnoreCase).

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

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

Rozšíření/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 v programu. 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 zobrazuje 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í snadno ovladatelného způsobu spuštění aplikace najdete v tématu metody spuštění aplikace: pohodlí.

Přístup ke konfiguraci na Razor stránkách

Následující kód zobrazuje 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 je přidán do kontejneru služby s Configure konfigurací a vázaný na konfiguraci:

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

    services.AddRazorPages();
}

Následující kód používá @inject Razor direktivu 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>

Přístup ke konfiguraci 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í s delegátem

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

Konfigurace možností s delegátem je znázorněna jako příklad 2 v ukázkové aplikaci.

V následujícím kódu IConfigureOptions<TOptions> je služba přidána do kontejneru služby. Pomocí delegáta konfiguruje hodnoty 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 Option1 jsou hodnoty a Option2 zadány v appsettings.json a poté přepsány nakonfigurovaným delegátem.

Konfigurace versus konfigurace aplikace

Před konfigurací a spuštěním aplikace je hostitel nakonfigurovaný a spuštěný. Hostitel zodpovídá za spuštění aplikace a správu životního cyklu. Aplikace i hostitel se konfigurují pomocí zprostředkovatelů konfigurace popsaných v tomto tématu. V konfiguraci aplikace jsou také zahrnuty páry klíč-hodnota konfigurace hostitele. Další informace o tom, jak se používají poskytovatelé konfigurace, když je hostitel sestavený a jak zdroje konfigurace ovlivňují konfiguraci hostitele, najdete v tématu Základy ASP.NET Core .

Výchozí konfigurace hostitele

podrobnosti o výchozí konfiguraci při použití webového hostitelenaleznete v ASP.NET Core 2,2 verzi tohoto tématu.

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

Další konfigurace

Toto téma se týká pouze Konfigurace aplikace. další aspekty používání a hostování ASP.NET Corech aplikací jsou nakonfigurované pomocí konfiguračních souborů, které nejsou popsané v tomto tématu:

Proměnné prostředí nastavené v launchSettings. JSON přepíší ty nastavené v prostředí systému.

Další informace o migraci konfigurace aplikací 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 Startup aplikace. Další informace naleznete v tématu Použití hostování spouštěcích sestavení v ASP.NET Core.

Další zdroje informací