Konfiguration i ASP.NET Core

Av Rick Anderson och Kirk Larkin

Programkonfiguration i ASP.NET Core utförs med hjälp av en eller flera konfigurationsprovidrar. Konfigurationsprovidrar läser konfigurationsdata från nyckel/värde-par med hjälp av en mängd olika konfigurationskällor:

• Inställningsfiler, till exempel appsettings.json
• Miljövariabler
• Azure 密钥保管库
• Azure App Configuration (programkonfiguration för appar)
• Kommandoradsargument
• Anpassade leverantörer, installerade eller skapade
• Katalogfiler
• Minnesinterna .NET-objekt

Den här artikeln innehåller information om konfiguration i ASP.NET Core. Information om hur du använder konfiguration i non-ASP.NET Core-appar finns i .NET-konfiguration.

KonfigurationsvägledningBlazor, som lägger till eller ersätter vägledningen i den här noden, finns i ASP.NET Core-konfigurationBlazor.

Program- och värdkonfiguration

ASP.NET Core-appar konfigurerar och startar en värd. Värden ansvarar för appstart och livslängdshantering. ASP.NET Core-mallarna skapar en WebApplicationBuilder som innehåller värden. Vissa konfigurationer kan göras i både hosten och applikationskonfigurationsleverantörer, men i allmänhet bör endast konfigurationer som krävs för hosten utföras via värdkonfigurationen.

Programkonfigurationen har högsta prioritet och beskrivs i nästa avsnitt. Värdkonfigurationen följer programkonfigurationen och beskrivs i den här artikeln.

Standardprogramkonfigurationskällor

ASP.NET Core-webbappar som skapats med dotnet new eller Visual Studio genererar följande kod:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden. Den initierade WebApplicationBuilder (builder) tillhandahåller standardkonfiguration för appen i följande ordning, från högsta till lägsta prioritet:

1. Kommandoradsargument med hjälp av kommandoradskonfigurationsprovider.
2. Miljövariabler utan prefix med konfigurationsprovider för icke-prefixerade miljövariabler.
3. Användarhemligheter när appen körs i den Development miljön.
4. appsettings.{Environment}.json med hjälp av JSON-konfigurationsprovidern. Till exempel appsettings.Production.json och appsettings.Development.json.
5. appsettings.json med hjälp av JSON-konfigurationsprovidern.
6. En återställning till värdkonfigurationen som beskrivs i nästa avsnitt.

WebApplication.CreateBuilder(args) Obs! Ska bara anropas en gång i appar som förlitar sig på IIS-värdtjänster.

Standardvärdens konfigurationskällor

Följande lista innehåller standardvärde värdkonfigurationskällor från högsta till lägsta prioritet för WebApplicationBuilder:

1. Kommandoradsargument med hjälp av kommandoradskonfigurationsprovidern
2. DOTNET_-prefixade miljövariabler med hjälp av konfigurationsprovidern Miljövariabler.
3. ASPNETCORE_-prefixade miljövariabler med hjälp av konfigurationsprovidern Miljövariabler.

För .NET Generic Host och Web Host är standardvärdens konfigurationskällor från högsta till lägsta prioritet:

1. ASPNETCORE_-prefixade miljövariabler med hjälp av konfigurationsprovidern Miljövariabler.
2. Kommandoradsargument med hjälp av kommandoradskonfigurationsprovidern
3. DOTNET_-prefixade miljövariabler med miljövariablernas konfigurationsprovider.

När ett konfigurationsvärde anges i värd- och programkonfigurationen används programkonfigurationen.

Värdvariabler

Följande variabler är låsta tidigt när värdbyggarna initieras och kan inte påverkas av programkonfigurationen:

• Programnamn
• Miljönamn, till exempel Development, Productionoch Staging
• Innehållsrot
• Webbrot
• Om att söka efter hosting/startvärdsamlingar och vilka sammansättningar som ska skannas.
• Variabler som läses av app- och bibliotekskod från HostBuilderContext.Configuration i IHostBuilder.ConfigureAppConfiguration callbacks.

Alla andra värdinställningar läss från programkonfiguration i stället för värdkonfiguration.

URLS är en av de många vanliga värdinställningarna som inte är en bootstrap-inställning. Precis som alla andra värdinställningar som inte finns i föregående lista URLS läss senare från programkonfigurationen. Värdkonfiguration är en återställning för programkonfiguration, så värdkonfiguration kan användas för att ange URLS, men den kommer att åsidosättas av alla konfigurationskällor i programkonfigurationen som appsettings.json.

Mer information finns i Ändra innehållsrot, appnamn och miljö och Ändra innehållsrot, appnamn och miljö efter miljövariabler eller kommandorad

De återstående avsnitten i den här artikeln refererar till programkonfiguration.

Programkonfigurationsleverantörer

Följande kod visar de aktiverade konfigurationsprovidrar i den ordning de lades till:

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

I föregående lista över standardkonfigurationskällor med högst till lägsta prioritet visas leverantörerna i motsatt ordning som de läggs till i mallgenererade program. Till exempel läggs JSON-konfigurationsprovidern till före kommandoradskonfigurationsprovidern.

Konfigurationsprovidrar som läggs till senare har högre prioritet och åsidosätter tidigare nyckelinställningar. Om MyKey till exempel anges i både appsettings.json och miljön används miljövärdet. Med standardkonfigurationsprovidrar åsidosätter kommandoradskonfigurationsprovidern alla andra leverantörer.

Mer information om CreateBuilderfinns i Standardinställningar för byggare.

appsettings.json

Överväg följande appsettings.json fil:

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

Följande kod från exempelnedladdningen visar flera av de föregående konfigurationsinställningarna:

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

Standardinställningen JsonConfigurationProvider läser in konfigurationen i följande ordning:

1. appsettings.json
2. appsettings.{Environment}.json : Till exempel filerna appsettings.Production.json och appsettings.Development.json. Miljöversionen av filen läses in baserat på IHostingEnvironment.EnvironmentName. Mer information finns i Använda flera miljöer i ASP.NET Core.

appsettings.{Environment}.json värden åsidosätter nycklar i appsettings.json. Som standard kan du till exempel:

• Under utveckling skriver appsettings.Development.json konfigurationen över värden som finns i appsettings.json.
• I produktion appsettings.Production.json skriver konfigurationen över värden som finns i appsettings.json. Till exempel när du distribuerar appen till Azure.

Om ett konfigurationsvärde måste garanteras, se GetValue. Föregående exempel läser bara strängar och stöder inte ett standardvärde.

Med standardkonfigurationen aktiveras appsettings.json filerna och appsettings.{Environment}.json med reloadOnChange: true. Ändringar som görs i appsettings.json filen och appsettings.{Environment}.jsonefter att appen har startat läss av JSON-konfigurationsprovidern.

Kommentarer i appsettings.json

Kommentarer i appsettings.json och appsettings.{Environment}.json filer stöds med javascript- eller C#-formatkommentarer.

Vissa integrerade utvecklingsmiljöer (IDE) visar fel när du redigerar en JSON-fil som innehåller kommentarer. Du kan vanligtvis ignorera kommentarsfel och varningar, men du kan också inaktivera dem med en inställning i IDE. I Visual Studio Code lägger du till exempel till följande settings.json i filen för att inaktivera felen:

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

För andra IDE:er kontrollerar du verktygets dokumentation och andra produktsupportkanaler för att avgöra hur felen ska tystas.

Binda hierarkiska konfigurationsdata med hjälp av alternativmönstret

Det bästa sättet att läsa relaterade konfigurationsvärden är att använda mönstret alternativ. Om du till exempel vill läsa följande konfigurationsvärden:

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

Skapa följande PositionOptions klass:

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

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

En options-klass:

• Måste vara icke-abstrakt med en offentlig parameterlös konstruktor.
• Alla offentliga läs- och skrivegenskaper av typen är bundna.
• Fält är inte bundna. I föregående kod är inte Position bunden. Fältet Position används så att strängen "Position" inte behöver hårdkodas i appen när klassen binds till en konfigurationsprovider.

Följande kod:

• Anropar ConfigurationBinder.Bind för att binda PositionOptions klassen till avsnittet Position .
• Visar konfigurationsdata Position .

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

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

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

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

I föregående kod läses som standard ändringar i JSON-konfigurationsfilen när appen har startats.

ConfigurationBinder.Get<T> binder och returnerar den angivna typen. ConfigurationBinder.Get<T> kan vara bekvämare än att använda ConfigurationBinder.Bind. Följande kod visar hur du använder ConfigurationBinder.Get<T> med PositionOptions klassen:

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

I föregående kod läses som standard ändringar i JSON-konfigurationsfilen när appen har startats.

En alternativ metod när du använder alternativmönstret är att binda Position avsnittet och lägga till det i containern för beroendeinmatningstjänsten. I följande kod PositionOptions läggs till i tjänstcontainern med Configure och är bunden till konfigurationen:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Med hjälp av föregående kod läser följande kod positionsalternativen:

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

I föregående kod läss inte ändringar i JSON-konfigurationsfilen när appen har startats. Om du vill läsa ändringar när appen har startats använder du IOptionsSnapshot.

Med standardkonfigurationen aktiveras appsettings.json filerna och appsettings.{Environment}.json med reloadOnChange: true. Ändringar som görs i appsettings.json filen och appsettings.{Environment}.jsonefter att appen har startat läss av JSON-konfigurationsprovidern.

Mer information om hur du lägger till ytterligare JSON-konfigurationsfiler finns i JSON-konfigurationsprovidern i det här dokumentet.

Kombinera tjänstesamling

Överväg följande som registrerar tjänster och konfigurerar alternativ:

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

Relaterade grupper av registreringar kan flyttas till en tilläggsmetod för att registrera tjänster. Till exempel läggs konfigurationstjänsterna till i följande klass:

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

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

            return services;
        }

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

            return services;
        }
    }
}

De återstående tjänsterna registreras i en liknande klass. Följande kod använder de nya tilläggsmetoderna för att registrera tjänsterna:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Obs! Varje services.Add{GROUP_NAME} tilläggsmetod lägger till och kan konfigurera tjänster. Till exempel lägger AddControllersWithViews till de tjänster som MVC-styrenheter med vyer kräver och AddRazorPages lägger till de tjänster som Razor Pages kräver.

Säkerhets- och användarhemligheter

Riktlinjer för konfigurationsdata:

• Lagra aldrig lösenord eller andra känsliga data i konfigurationsproviderns kod eller i konfigurationsfiler för oformaterad text. Verktyget Secret Manager kan användas för att lagra hemligheter under utveckling.
• Använd inte produktionshemligheter i utvecklings- eller testmiljöer.
• Ange hemligheter utanför projektet så att de inte av misstag kan checkas in på en källkodslagringsplats.
• Produktionsappar bör använda det säkraste tillgängliga autentiseringsflödet. Mer information finns i Skydda autentiseringsflöden.

Som standard registreras konfigurationskällan för användarhemligheter efter JSON-konfigurationskällorna. Därför har nycklar för användarhemligheter företräde framför nycklar i appsettings.json och appsettings.{Environment}.json.

Mer information om hur du lagrar lösenord eller andra känsliga data:

• Använda flera miljöer i ASP.NET Core
• Säker lagring av apphemligheter under utveckling i ASP.NET Core: Innehåller råd om hur du använder miljövariabler för att lagra känsliga data. Verktyget Secret Manager använder filkonfigurationsprovidern för att lagra användarhemligheter i en JSON-fil i det lokala systemet.
• Azure Key Vault lagrar på ett säkert sätt apphemligheter för ASP.NET Core-appar. Mer information finns i Konfigurationsprovidern för Azure Key Vault i ASP.NET Core.

Miljövariabler utan prefix

Icke-prefixade miljövariabler är miljövariabler som inte har prefixet ASPNETCORE_ eller DOTNET_. Till exempel ställer ASP.NET Core-webbprogrammallar in "ASPNETCORE_ENVIRONMENT": "Development" i launchSettings.json. Mer information om ASPNETCORE_ och DOTNET_ miljövariabler finns i:

• Lista över standardkonfigurationskällor med högst till lägsta prioritet , inklusive icke-prefix, ASPNETCORE_-prefix och DOTNETCORE_-prefixerade miljövariabler.
• DOTNET_ miljövariabler som används utanför Microsoft.Extensions.Hosting.

Med standardkonfigurationen läser konfigurationen EnvironmentVariablesConfigurationProvider in från nyckel/värde-par för miljövariabeln efter att ha läst appsettings.json, appsettings.{Environment}.jsonoch användarhemligheter. Nyckelvärden som läss från miljön åsidosätter därför värden som lästs från appsettings.json, appsettings.{Environment}.jsonoch användarhemligheter.

Den : avgränsaren fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Till exempel stöds inte :-avgränsaren av Bash. Det dubbla understrecket, __, är:

• Stöds av alla plattformar.
• Ersätts automatiskt av ett kolon, :.

Följande kommandon:

• Ange miljönycklarna och värdena i föregående exempel i Windows.
• Testa inställningarna när du använder exempelnedladdningen. Kommandot dotnet run måste köras i projektkatalogen.

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

Föregående miljöinställningar:

• Anges endast i processer som startas från kommandofönstret som de angavs i.
• Läses inte av webbläsare som startas med Visual Studio.

Följande setx-kommandon kan användas för att ange miljönycklar och värden i Windows. set Till skillnad från setxsparas inställningarna. /M anger variabeln i systemmiljön. Om växeln /M inte används anges en användarmiljövariabel.

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

Testa att de föregående kommandona åsidosätter appsettings.json och appsettings.{Environment}.json:

• Med Visual Studio: Avsluta och starta om Visual Studio.
• Med CLI: Starta ett nytt kommandofönster och ange dotnet run.

Anropa AddEnvironmentVariables med en sträng för att ange ett prefix för miljövariabler:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

I koden ovan:

• builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_") läggs till efter standardkonfigurationsprovidrar. Ett exempel på hur du beställer konfigurationsprovidrar finns i JSON-konfigurationsprovidern.
• Miljövariabler som anges med prefixet MyCustomPrefix_ åsidosätter standardkonfigurationsprovidrar. Detta inkluderar miljövariabler utan prefixet.

Prefixet tas bort när nyckel/värde-paren för konfigurationen läss.

Följande kommandon testar det anpassade prefixet:

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

Standardkonfigurationen läser in miljövariabler och kommandoradsargument som prefixats med DOTNET_ och ASPNETCORE_. Prefixen DOTNET_ och ASPNETCORE_ används av ASP.NET Core för värd- och appkonfiguration, men inte för användarkonfiguration. Mer information om värd- och appkonfiguration finns i .NET Generic Host.

I Azure App Service väljer du Ny programinställning på sidan Konfiguration>inställningar. Azure App Service-programinställningar är:

• Krypterad i vila och överförs via en krypterad kanal.
• Exponeras som miljövariabler.

Mer information finns i Azure Apps: Åsidosätt appkonfiguration med hjälp av Azure-portalen.

Se Anslutningssträngsprefix för information om Azure-databasanslutningssträngar.

Namngivning av miljövariabler

Miljövariabelnamn återspeglar strukturen för en appsettings.json fil. Varje element i hierarkin avgränsas med ett dubbelt understreck (helst) eller ett kolon. När elementstrukturen innehåller en matris bör matrisindexet behandlas som ytterligare ett elementnamn i den här sökvägen. Överväg följande appsettings.json fil och dess motsvarande värden som representeras som miljövariabler.

appsettings.json

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

Miljövariabler

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

Miljövariabler anges i genererade launchSettings.json

Miljövariabler som anges i launchSettings.json åsidosätter de som anges i systemmiljön. Till exempel genererar ASP.NET Core-webbmallarna en launchSettings.json fil som anger slutpunktskonfigurationen till:

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

Att konfigurera applicationUrl ställer in ASPNETCORE_URLS miljövariabeln och åsidosätter värden som angetts i miljön.

Escape-miljövariabler i Linux

I Linux måste värdet för URL-miljövariabler kodas för att systemd ska kunna parsa det. Använd linux-verktyget systemd-escape som ger http:--localhost:5001

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

Visa miljövariabler

Följande kod visar miljövariabler och värden vid programstart, vilket kan vara användbart när du felsöker miljöinställningar:

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

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

Kommandorad

Med standardkonfigurationen läser CommandLineConfigurationProvider in konfigurationen från nyckel/värde-par för kommandoradsargument efter följande konfigurationskällor:

• appsettings.json och appsettings.{Environment}.json filer.
• Apphemligheter i utvecklingsmiljön.
• Miljövariabler.

Som standard åsidosätter konfigurationsvärden som anges på kommandoraden konfigurationsvärden som anges med alla andra konfigurationsleverantörer.

Kommandoradsargument

Följande kommando anger nycklar och värden med hjälp av =:

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

Följande kommando anger nycklar och värden med hjälp av /:

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

Följande kommando anger nycklar och värden med hjälp av --:

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

Nyckelvärdet:

• Måste följa =, eller så måste nyckeln ha prefixet -- eller / när värdet följer ett blanksteg.
• Krävs inte om = används. Till exempel MySetting=.

I samma kommando ska du inte blanda nyckel/värde-par för kommandoradsargument som använder = med nyckel/värde-par som använder ett blanksteg.

Växla mappningar

Växla mappningar tillåter ersättningslogik för nyckelnamn . Ange en ordlista med switchersättningar till metoden AddCommandLine.

När ordlistan för växelmappningar används kontrolleras ordlistan efter en nyckel som matchar nyckeln som tillhandahålls av ett kommandoradsargument. Om kommandoradsnyckeln finns i ordlistan skickas ordlistevärdet tillbaka för att ange nyckel/värde-paret i appens konfiguration. En växelmappning krävs för alla kommandoradsargument som är prefixad med ett enda bindestreck (-).

Växla mappningsordlistenyckelregler:

• Växlar måste börja med - eller --.
• Ordlistan för växelmappningar får inte innehålla dubblettnycklar.

Om du vill använda en switchmappningsordlista skickar du den till anropet till 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();

Kör följande kommando för att testa nyckelbyte:

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

Följande kod visar nyckelvärdena för de ersatta nycklarna:

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

För appar som använder switchmappningar bör anropet till CreateDefaultBuilder inte skicka argument. Metodens CreateDefaultBuilderAddCommandLine anrop innehåller inte mappade växlar och det går inte att skicka ordlistan för switchmappning till CreateDefaultBuilder. Lösningen är inte att skicka argumenten till CreateDefaultBuilder utan i stället låta ConfigurationBuilder metoden AddCommandLine bearbeta både argumenten och ordlistan för switchmappning.

Ange miljö- och kommandoradsargument med Visual Studio

Miljö- och kommandoradsargument kan anges i Visual Studio från dialogrutan starta profiler:

• Högerklicka på projektet i Solution Explorer och välj Egenskaper.
• Välj fliken Felsök > Allmänt och välj Öppna användargränssnittet för felsökningsprofiler.

Hierarkiska konfigurationsdata

Konfigurations-API:et läser hierarkiska konfigurationsdata genom att platta ut hierarkiska data med hjälp av en avgränsare i konfigurationsnycklarna.

Exempelnedladdningen innehåller följande appsettings.json fil:

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

Följande kod från exempelnedladdningen visar flera av konfigurationsinställningarna:

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

Det bästa sättet att läsa hierarkiska konfigurationsdata är att använda alternativmönstret. Mer information finns i Binda hierarkiska konfigurationsdata i det här dokumentet.

GetSection och GetChildren-metoder är tillgängliga för att isolera avsnitt och underordnade av ett avsnitt i konfigurationsdata. Dessa metoder beskrivs senare i GetSection, GetChildren och Exists.

Konfigurationsnycklar och -värden

Varning

Den här artikeln visar användningen av anslutningssträngar. Med en lokal databas behöver användaren inte autentiseras, men i produktion innehåller anslutningssträngar ibland ett lösenord för att autentisera. En resursägares lösenordsautentiseringsuppgifter (ROPC) är en säkerhetsrisk som bör undvikas i produktionsdatabaser. Produktionsappar bör använda det säkraste tillgängliga autentiseringsflödet. Mer information om autentisering för appar som distribueras till test- eller produktionsmiljöer finns i Säkra autentiseringsflöden.

Konfigurationsnycklar:

• Är skiftlägesokänsliga. Till exempel behandlas ConnectionString och connectionstring som motsvarande nycklar.
• Om en nyckel och ett värde anges i mer än en konfigurationsprovider används värdet från den senaste providern som lades till. Mer information finns i Standardkonfiguration.
• Hierarkiska nycklar
  • I konfigurations-API:et fungerar en kolonavgränsare (:) på alla plattformar.
  • I miljövariabler kanske en kolonavgränsare inte fungerar på alla plattformar. Ett dubbelt understreck, __, stöds av alla plattformar och konverteras automatiskt till ett kolon :.
  • I Azure Key Vault används -- hierarkiska nycklar som avgränsare. Azure Key Vault-konfigurationsprovidern ersätter automatiskt -- med en : när sekreterna läses in i appens konfiguration.
• Stöder ConfigurationBinder bindning av matriser till objekt med matrisindex i konfigurationsnycklar. Matrisbindning beskrivs i avsnittet Bind en matris till en klass .

Konfigurationsvärden:

• Är strängar.
• Null-värden kan inte lagras i konfigurationen eller bindas till objekt.

Konfigurationsleverantörer

I följande tabell visas de konfigurationsprovidrar som är tillgängliga för ASP.NET Core-appar.

Leverantör	Tillhandahåller konfiguration från
Azure Key Vault-konfigurationsprovider	Azure 密钥保管库
Azure App-konfigurationsprovider	Azure App Configuration (programkonfiguration för appar)
kommandoradskonfigurationsprovider	Kommandoradsparametrar
Anpassad konfigurationsleverantör	Anpassad källa
konfigurationsleverantör för miljövariabler	Miljövariabler
Filkonfigurationsleverantör	INI-, JSON- och XML-filer
Nyckel-per-fil-konfigurationsprovider	Katalogfiler
Minneskonfigurationsleverantör	Minnesinterna samlingar
Användarhemligheter	Fil i användarprofilkatalogen

Konfigurationskällor läses i den ordning som konfigurationsleverantörer anges. Ordna konfigurationsanordnare i koden så att de passar prioriteringarna för de underliggande konfigurationskällor som behövs för appen.

En typisk sekvens av konfigurationsprovidrar är:

1. appsettings.json
2. appsettings.{Environment}.json
3. Användarhemligheter
4. Miljövariabler med konfigurationsprovidern för miljövariabler .
5. Kommandoradsargument med hjälp av kommandoradskonfigurationsprovider.

En vanlig metod är att lägga till kommandoradskonfigurationsprovidern senast i en serie leverantörer för att tillåta kommandoradsargument att åsidosätta konfigurationsuppsättningen av de andra leverantörerna.

Den föregående sekvensen av providrar används i standardkonfigurationen.

Anslutningssträngsprefix

Varning

Den här artikeln visar användningen av anslutningssträngar. Med en lokal databas behöver användaren inte autentiseras, men i produktion innehåller anslutningssträngar ibland ett lösenord för att autentisera. En resursägares lösenordsautentiseringsuppgifter (ROPC) är en säkerhetsrisk som bör undvikas i produktionsdatabaser. Produktionsappar bör använda det säkraste tillgängliga autentiseringsflödet. Mer information om autentisering för appar som distribueras till test- eller produktionsmiljöer finns i Säkra autentiseringsflöden.

Konfigurations-API:et har särskilda bearbetningsregler för fyra anslutningssträng miljövariabler. Dessa anslutningssträng ingår i konfigurationen av Azure anslutningssträng för appmiljön. Miljövariabler med prefixen som visas i tabellen läses in i appen med standardkonfigurationen eller när inget prefix anges till AddEnvironmentVariables.

Anslutningssträngsprefix	Leverantör
CUSTOMCONNSTR_	Anpassad leverantör
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL Database
SQLCONNSTR_	SQL Server

När en miljövariabel identifieras och läses in i konfigurationen med något av de fyra prefixen som visas i tabellen:

• Konfigurationsnyckeln skapas genom att miljövariabelprefixet tas bort och ett konfigurationsnyckelavsnitt läggs till (ConnectionStrings).
• Ett nytt nyckel/värde-par för konfiguration skapas som representerar databasanslutningsprovidern (förutom CUSTOMCONNSTR_, som inte har någon angiven provider).

Miljövariabelnyckel	Konverterad konfigurationsnyckel	Providerkonfigurationspost
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Konfigurationsposten har inte skapats.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Nyckel: ConnectionStrings:{KEY}_ProviderName: Värde: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Nyckel: ConnectionStrings:{KEY}_ProviderName: Värde: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Nyckel: ConnectionStrings:{KEY}_ProviderName: Värde: System.Data.SqlClient

Filkonfigurationsprovider

FileConfigurationProvider är basklassen för inläsning av konfiguration från filsystemet. Följande konfigurationsprovidrar härleds från FileConfigurationProvider:

• INI-konfigurationsprovider
• JSON-konfigurationsprovider
• XML-konfigurationsprovider

INI-konfigurationsprovider

IniConfigurationProvider läser in konfiguration från nyckel/värde-par i INI-filen vid körning.

Följande kod lägger till flera konfigurationsproviders:

var builder = WebApplication.CreateBuilder(args);

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

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

builder.Services.AddRazorPages();

var app = builder.Build();

I föregående kod åsidosättas inställningarna i MyIniConfig.ini filerna och MyIniConfig.{Environment}.ini av inställningarna i:

• Konfigurationsprovider för miljövariabler
• Konfigurationsprovider för kommandorad.

Exempelnedladdningen innehåller följande MyIniConfig.ini fil:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Följande kod från exempelnedladdningen visar flera av de föregående konfigurationsinställningarna:

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

JSON-konfigurationsprovider

Läser in konfiguration från nyckel/värde-par i en JSON-fil.

Överlagringar kan ange:

• Om filen är valfri.
• Om konfigurationen läses in igen om filen ändras.

Överväg följande kod:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Föregående kod:

• Konfigurerar JSON-konfigurationsprovidern för att läsa in MyConfig.json filen med följande alternativ:
  • optional: true: Filen är valfri.
  • reloadOnChange: true : Filen laddas om när ändringar sparas.
• Läser standardkonfigurationsprovidrar före MyConfig.json filen. Inställningar i MyConfig.json-filen åsidosätter inställningarna i standardkonfigurationsprovidrarna, inklusive Miljövariabelkonfigurationsprovidern och Kommandoradskonfigurationsprovidern.

Du vill vanligtvis inte att en anpassad JSON-fil ska åsidosätta värden som anges i konfigurationsprovidern Miljövariabler och kommandoradskonfigurationsprovidern.

XML-konfigurationsprovider

Läser XmlConfigurationProvider in konfigurationen från nyckel/värde-par för XML-filer vid körning.

Följande kod lägger till flera konfigurationsproviders:

var builder = WebApplication.CreateBuilder(args);

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

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

builder.Services.AddRazorPages();

var app = builder.Build();

I föregående kod åsidosättas inställningarna i MyXMLFile.xml filerna och MyXMLFile.{Environment}.xml av inställningarna i:

• Konfigurationsprovider för miljövariabler
• Konfigurationsprovider för kommandorad.

Exempelnedladdningen innehåller följande MyXMLFile.xml fil:

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

Följande kod från exempelnedladdningen visar flera av de föregående konfigurationsinställningarna:

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

Upprepande element som använder samma elementnamn fungerar om name attributet används för att särskilja elementen:

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

Följande kod läser den tidigare konfigurationsfilen och visar nycklar och värden:

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

Attribut kan användas för att ange värden:

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

Den tidigare konfigurationsfilen läser in följande nycklar med value:

• key:attribute
• section:key:attribute

Konfigurationsprovider för nyckel per fil

KeyPerFileConfigurationProvider Använder en katalogs filer som nyckel/värde-konfigurationspar. Nyckeln är filnamnet. Värdet innehåller filens innehåll. Nyckel-per-fil-konfigurationsprovidern används i Docker-värdscenarier.

Om du vill aktivera nyckel-per-fil-konfiguration anropar du AddKeyPerFile tilläggsmetoden på en instans av ConfigurationBuilder. Till directoryPath filerna måste vara en absolut sökväg.

Överlagringar tillåter att du anger:

• Ett Action<KeyPerFileConfigurationSource> ombud som konfigurerar källan.
• Om katalogen är valfri och sökvägen till katalogen.

Det dubbla understrecket (__) används som en avgränsare för konfigurationsnycklar i filnamn. Filnamnet Logging__LogLevel__System genererar till exempel konfigurationsnyckeln Logging:LogLevel:System.

Anropa ConfigureAppConfiguration när du skapar värden för att ange appens konfiguration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Minneskonfigurationsprovider

MemoryConfigurationProvider Använder en minnesintern samling som nyckel/värde-konfigurationspar.

Följande kod lägger till en minnessamling i konfigurationssystemet:

var builder = WebApplication.CreateBuilder(args);

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

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

builder.Services.AddRazorPages();

var app = builder.Build();

Följande kod från exempelnedladdningen visar de föregående konfigurationsinställningarna:

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

I föregående kod config.AddInMemoryCollection(Dict) läggs till efter standardkonfigurationsprovidrar. Ett exempel på hur du beställer konfigurationsprovidrar finns i JSON-konfigurationsprovidern.

Se Binda en matris för ett annat exempel med hjälp av MemoryConfigurationProvider.

Kestrel ändpunktkonfiguration

Kestrel specifik slutpunktskonfiguration åsidosätter alla konfigurationer av slutpunkter mellan servrar . Konfigurationer av slutpunkter mellan servrar omfattar:

• UseUrls
• --urls på kommandoraden
• MiljövariabelnASPNETCORE_URLS

Överväg följande appsettings.json fil som används i en ASP.NET Core-webbapp:

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

När den markerade markeringen ovan används i en ASP.NET Core-webbapp och appen startas på kommandoraden med följande korsserverslutpunktskonfiguration:

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

Kestrel ansluter till slutpunkten som är konfigurerad specifikt för Kestrel i appsettings.json-filen (https://localhost:9999) och inte https://localhost:7777.

Överväg den Kestrel specifika slutpunkt som konfigurerats som en miljövariabel:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

I föregående miljövariabel Https är namnet på den Kestrel specifika slutpunkten. appsettings.json Föregående fil definierar också en Kestrel specifik slutpunkt med namnet Https. Som standard läss miljövariabler som använder konfigurationsprovidern Miljövariabler efter appsettings.{Environment}.json, och därför används den föregående miljövariabeln för Https slutpunkten.

Hämta värde

ConfigurationBinder.GetValue extraherar ett enda värde från konfigurationen med en angiven nyckel och konverterar det till den angivna typen:

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

I föregående kod används standardvärdet 99 om NumberKey inte finns i konfigurationen.

GetSection, GetChildren och Exists

För de exempel som följer bör du överväga följande MySubsection.json fil:

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

Följande kod lägger till MySubsection.json i konfigurationsprovidrarna:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection returnerar ett konfigurationsunderavsnitt med den angivna underavsnittsnyckeln.

Följande kod returnerar värden för 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"]}'");
    }
}

Följande kod returnerar värden för 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 returnerar aldrig null. Om ett matchande avsnitt inte hittas returneras ett tomt IConfigurationSection .

När GetSection returnerar ett matchande avsnitt, Value lämnas tomt. Ett Key och ett Path returneras när avsnittet finns.

GetChildren och finns

Följande kod anropar IConfiguration.GetChildren och returnerar värden för 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);
    }
}

Föregående kod anropar ConfigurationExtensions.Exists för att verifiera att avsnittet finns.

Binda ett array

ConfigurationBinder.Bind stöder bindning av vektorer till objekt genom att använda matrisindex i konfigurationsnycklar. Alla matrisformat som exponerar ett numeriskt nyckelsegment kan binda till en POCO-klassmatris .

Överväg MyArray.json från exempelnedladdningen:

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

Följande kod lägger till MyArray.json bland konfigurationsleverantörerna.

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Följande kod läser konfigurationen och visar värdena:

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

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

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

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

        return Content(s);
    }
}

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

Föregående kod returnerar följande utdata:

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

I föregående utdata har Index 3 värdet value40, motsvarande "4": "value40", i MyArray.json. De bundna matrisindexen är kontinuerliga och är inte bundna till konfigurationsnyckelindexet. Konfigurationsbindningen kan inte binda null-värden eller skapa null-poster i bundna objekt.

Anpassad konfigurationsleverantör

Exempelappen visar hur du skapar en grundläggande konfigurationsprovider som läser konfigurationsnyckel/värde-par från en databas med hjälp av Entity Framework (EF).

Providern har följande egenskaper:

• Databasen ef in-memory används i demonstrationssyfte. Om du vill använda en databas som kräver en anslutningssträng implementerar du en sekundär ConfigurationBuilder för att ange anslutningssträngen från en annan konfigurationsprovider.
• Providern läser en databastabell i konfigurationen vid start. Providern frågar inte databasen för varje nyckel.
• Omladdning vid ändring implementeras inte, så att uppdatera databasen när appen startar har ingen effekt på appens konfiguration.

Definiera en entitet EFConfigurationValue för lagring av konfigurationsvärden i databasen.

Models/EFConfigurationValue.cs:

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

Lägg till en EFConfigurationContext för att lagra och komma åt de konfigurerade värdena.

EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Skapa en klass som implementerar 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);
}

Skapa den anpassade konfigurationsleverantören genom att ärva från ConfigurationProvider. Konfigurationsprovidern initierar databasen när den är tom. Eftersom konfigurationsnycklar inte är skiftlägeskänsliga skapas ordlistan som används för att initiera databasen med den skiftlägesokänsliga jämförelsen (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

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

        OptionsAction(builder);

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

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

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

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

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Med en AddEFConfiguration tilläggsmetod kan du lägga till konfigurationskällan i en ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

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

Följande kod visar hur du använder det anpassade EFConfigurationProvider i Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Åtkomstkonfiguration med Dependency Injection (DI)

Konfigurationen kan matas in i tjänster med hjälp av beroendeinmatning (DI) genom att lösa tjänsten IConfiguration :

public class Service
{
    private readonly IConfiguration _config;

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

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

        // ...
    }
}

För information om hur du kommer åt värden med hjälp av IConfiguration, se GetValue och GetSection, GetChildren och Exists i den här artikeln.

Åtkomstkonfiguration på Razor sidor

Följande kod visar konfigurationsdata på en Razor sida:

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

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

I följande kod MyOptions läggs till i tjänstcontainern med Configure och är bunden till konfigurationen:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Följande markering använder @injectRazor direktivet för att matcha och visa alternativvärdena:

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

Åtkomstkonfiguration i en MVC-vyfil

Följande kod visar konfigurationsdata i en MVC-vy:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Åtkomstkonfiguration i Program.cs

Följande kod kommer åt konfigurationen Program.cs i filen.

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

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

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

app.Run();

I appsettings.json för föregående exempel:

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

Konfigurera alternativ med ett ombud

Alternativ som konfigurerats i en delegering åsidosätter värden som anges i konfigurationsprovidrar.

I följande kod läggs en IConfigureOptions<TOptions> tjänst till i tjänstcontainern. Den använder en delegering för att konfigurera värden för 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();

Följande kod visar alternativvärdena:

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

I det föregående exemplet anges värdena av Option1 och Option2 i appsettings.json och åsidosätts sedan av den konfigurerade delegaten.

Konfiguration av värd kontra app

Innan appen konfigureras och startas konfigureras och startas en värd . Värden ansvarar för appstart och livslängdshantering. Både appen och värden konfigureras med hjälp av konfigurationsleverantörer som beskrivs i det här avsnittet. Nyckel/värde-par för värdkonfiguration ingår också i appens konfiguration. Mer information om hur konfigurationsleverantörer används när värden byggs och hur konfigurationskällor påverkar värdkonfigurationen finns i översikten över ASP.NET Core-grunderna.

Standardkonfiguration av värd

Mer information om standardkonfigurationen när du använder webbvärden finns i ASP.NET Core 2.2-versionen av det här avsnittet.

• Värdkonfiguration tillhandahålls från:
  • Miljövariabler prefixade med DOTNET_ (till exempel DOTNET_ENVIRONMENT) med hjälp av konfigurationsprovidern Miljövariabler. Prefixet (DOTNET_) tas bort när konfigurationens nyckel/värde-par läses in.
  • Kommandoradsargument med hjälp av kommandoradskonfigurationsprovider.
• Standardkonfigurationen för webbvärden upprättas (ConfigureWebHostDefaults):
  • Kestrel används som webbserver och konfigureras med hjälp av appens konfigurationsprovidrar.
  • Lägg till mellanprogram för värdfiltrering.
  • Lägg till Forwarded Headers-mellanprogramvara om ASPNETCORE_FORWARDEDHEADERS_ENABLED miljövariabeln är inställd på true.
  • Aktivera IIS-integrering.

Övrig konfiguration

Det här avsnittet gäller endast appkonfiguration. Andra aspekter av att köra och vara värd för ASP.NET Core-appar konfigureras med konfigurationsfiler som inte beskrivs i det här avsnittet:

• launch.json / launchSettings.json är verktygskonfigurationsfiler för utvecklingsmiljön, som beskrivs:
  • I Använd flera miljöer i ASP.NET Core.
  • I dokumentationsuppsättningen där filerna används för att konfigurera ASP.NET Core-appar för utvecklingsscenarier.
• web.config är en serverkonfigurationsfil som beskrivs i följande avsnitt:
  • Köra ASP.NET Core på Windows med IIS
  • ASP.NET Core Module (ANCM) för IIS

Miljövariabler som anges i launchSettings.json åsidosätter de som anges i systemmiljön.

Mer information om hur du migrerar appkonfiguration från tidigare versioner av ASP.NET finns i Migrera konfiguration till ASP.NET Core.

Lägga till konfiguration från en extern sammansättning

Med en IHostingStartup implementering kan du lägga till förbättringar i en app vid start från en extern sammansättning utanför appens Startup-klass. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

Generator för konfigurationsbindningskälla

Konfigurationsbindande källgeneratorn tillhandahåller AOT- och trimvänlig konfiguration. Mer information finns i Konfigurationsbindning av källgenerator.

Ytterligare resurser

• Konfigurationskällans kod
• WebApplicationBuilder-källkod
• Visa eller ladda ned exempelkod (hur du laddar ned)
• Alternativmönster i ASP.NET Core
• ASP.NET Core Blazor konfiguration