Delen via

Configuratie in ASP.NET Core

Door Rick Anderson en Kirk Larkin

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikel voor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET- en .NET Core-ondersteuningsbeleid voor meer informatie. Zie de .NET 9-versie van dit artikel voor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikel voor de huidige release.

Toepassingsconfiguratie in ASP.NET Core wordt uitgevoerd met behulp van een of meer configuratieproviders. Configuratieproviders lezen configuratiegegevens van sleutel-waardeparen met behulp van verschillende configuratiebronnen:

  • Instellingenbestanden, zoals appsettings.json
  • Omgevingsvariabelen
  • Azure Key Vault
  • Azure App Configuration (Configuratie van Azure-apps)
  • Opdrachtregelargumenten
  • Aangepaste providers, geïnstalleerd of gemaakt
  • Directorybestanden
  • .NET-objecten in het geheugen

Dit artikel bevat informatie over de configuratie in ASP.NET Core. Zie .NET-configuratie voor meer informatie over het gebruik van configuratie in non-ASP.NET Core-apps.

Raadpleeg Blazor de ASP.NET Core-configuratie Blazor voor configuratierichtlijnen die worden toegevoegd aan of de richtlijnen in dit knooppunt vervangen.

Toepassings- en hostconfiguratie

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. De ASP.NET Core-sjablonen maken een WebApplicationBuilder sjabloon die de host bevat. Hoewel sommige configuraties kunnen worden uitgevoerd in zowel de host als de toepassingsconfiguratieproviders, moet doorgaans alleen de configuratie die nodig is voor de host worden uitgevoerd in de hostconfiguratie.

Toepassingsconfiguratie is de hoogste prioriteit en wordt in de volgende sectie beschreven. Hostconfiguratie volgt de toepassingsconfiguratie en wordt beschreven in dit artikel.

Standaardbronnen voor toepassingsconfiguratie

ASP.NET Core-web-apps die zijn gemaakt met dotnet nieuwe of Visual Studio genereren de volgende code:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder-klasse met vooraf geconfigureerde standaardwaarden. De geïnitialiseerde WebApplicationBuilder (builder) biedt standaardconfiguratie voor de app in de volgende volgorde, van hoogste naar laagste prioriteit:

  1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.
  2. Omgevingsvariabelen zonder voorvoegsel met behulp van de configuratieprovider voor omgevingsvariabelen zonder voorvoegsel.
  3. Gebruikersgeheimen wanneer de app draait in de Development-omgeving.
  4. appsettings.{Environment}.json met behulp van de JSON-configuratieprovider. Bijvoorbeeld appsettings.Production.json en appsettings.Development.json.
  5. appsettings.json met de JSON-configuratieprovider.
  6. Een terugval naar de hostconfiguratie die wordt beschreven in de volgende sectie.

Opmerking: WebApplication.CreateBuilder(args) mag slechts eenmaal worden aangeroepen in apps die afhankelijk zijn van IIS-hosting in proces.

Standaardhostconfiguratiebronnen

De volgende lijst bevat de standaardhostconfiguratiebronnen van hoogste naar laagste prioriteit voor WebApplicationBuilder:

  1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider
  2. Omgevingsvariabelen met het voorvoegsel DOTNET_ gebruiken met behulp van de configuratieprovider voor omgevingsvariabelen.
  3. Omgevingsvariabelen met het voorvoegsel ASPNETCORE_ met behulp van de configuratieprovider voor omgevingsvariabelen.

Voor de .NET Generic Host en Web Host zijn de standaardhostconfiguratiebronnen van hoogste naar laagste prioriteit:

  1. Omgevingsvariabelen met het ASPNETCORE_-voorvoegsel met behulp van de configuratieprovider voor omgevingsvariabelen.
  2. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider
  3. Omgevingsvariabelen die beginnen met DOTNET_ met behulp van de configuratieprovider voor omgevingsvariabelen.

Wanneer een configuratiewaarde is ingesteld in de host- en toepassingsconfiguratie, wordt de toepassingsconfiguratie gebruikt.

Hostvariabelen

De volgende variabelen worden vroeg vergrendeld bij het initialiseren van de hostbuilders en kunnen niet worden beïnvloed door de configuratie van de toepassing:

Elke andere hostinstelling wordt gelezen uit de configuratie van de toepassing in plaats van de hostconfiguratie.

URLS is een van de vele algemene hostinstellingen die geen bootstrap-instelling is. Net als elke andere hostinstelling die niet in de vorige lijst staat, URLS wordt deze later gelezen uit de configuratie van de toepassing. Hostconfiguratie is een terugval voor toepassingsconfiguratie, dus hostconfiguratie kan worden gebruikt om in te stellen URLS, maar deze wordt overschreven door elke configuratiebron in de configuratie van de toepassing, zoals appsettings.json.

Zie De hoofdmap, app-naam en omgeving van deinhoud wijzigen en de inhoudshoofdmap, app-naam en omgeving wijzigen op omgevingsvariabelen of opdrachtregel voor meer informatie

De overige secties in dit artikel verwijzen naar toepassingsconfiguratie.

Toepassingsconfiguratieproviders

De volgende code geeft de ingeschakelde configuratieproviders weer in de volgorde waarin ze zijn toegevoegd:

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

In de voorgaande lijst met standaardconfiguratiebronnen met de hoogste tot laagste prioriteit worden de providers weergegeven in de tegenovergestelde volgorde waarin ze worden toegevoegd aan de door de sjabloon gegenereerde toepassing. De JSON-configuratieprovider wordt bijvoorbeeld toegevoegd vóór de opdrachtregelconfiguratieprovider.

Configuratieproviders die later worden toegevoegd, hebben een hogere prioriteit en overschrijven eerdere sleutelinstellingen. Als MyKey is ingesteld in zowel appsettings.json als in de omgeving, wordt de waarde van de omgeving gebruikt. Met behulp van de standaardconfiguratieproviders overschrijft de opdrachtregelconfiguratieprovider alle andere providers.

Zie Instellingen voor standaardbouwer voor meer informatieCreateBuilder.

appsettings.json

Houd rekening met het volgende appsettings.json bestand:

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

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

De standaardconfiguratie JsonConfigurationProvider wordt geladen in de volgende volgorde:

  1. appsettings.json
  2. appsettings.{Environment}.json : bijvoorbeeld de appsettings.Production.json en appsettings.Development.json bestanden. De omgevingsversie van het bestand wordt geladen op basis van de IHostingEnvironment.EnvironmentName. Zie Meerdere omgevingen gebruiken in ASP.NET Core voor meer informatie.

appsettings.{Environment}.json waarden overschrijven sleutels in appsettings.json. Bijvoorbeeld, standaard:

  • Tijdens ontwikkeling overschrijft appsettings.Development.json configuratiewaarden in appsettings.json.
  • In productie overschrijft appsettings.Production.json configuratie de waarden in appsettings.json. Bijvoorbeeld bij het implementeren van de app in Azure.

Als een configuratiewaarde moet worden gegarandeerd, raadpleegt u GetValue. In het voorgaande voorbeeld worden alleen tekenreeksen gelezen en wordt geen standaardwaarde ondersteund.

Met behulp van de standaardconfiguratie worden de appsettings.json en appsettings.{Environment}.json bestanden ingeschakeld met reloadOnChange: true. Wijzigingen die zijn aangebracht in het appsettings.json-bestand en het appsettings.{Environment}.json-bestand nadat de app is gestart, worden gelezen door de JSON-configuratieprovider.

Opmerkingen in appsettings.json

Opmerkingen in appsettings.json en appsettings.{Environment}.json bestanden worden ondersteund met javaScript- of C#-stijlopmerkingen.

In sommige IDE's (Integrated Development Environments) worden fouten weergegeven bij het bewerken van een JSON-bestand dat opmerkingen bevat. Over het algemeen kunt u opmerkingenfouten en waarschuwingen negeren, maar u kunt ze meestal ook uitschakelen met een instelling in de IDE. Voeg in Visual Studio Code bijvoorbeeld het volgende toe aan het settings.json bestand om de fouten uit te schakelen:

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

Voor andere IDE's raadpleegt u de documentatie van het hulpprogramma en andere productondersteuningskanalen om te bepalen hoe u de fouten stil kunt leggen.

Hiërarchische configuratiegegevens binden met behulp van het optiespatroon

De voorkeursmethode voor het lezen van gerelateerde configuratiewaarden is het gebruik van het patroon opties. Bijvoorbeeld om de volgende configuratiewaarden te lezen:

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

Maak de volgende PositionOptions klasse:

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

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

Een opties klasse:

  • Moet niet-abstract zijn met een openbare parameterloze constructor.
  • Alle openbare lees-schrijfeigenschappen van het type zijn gebonden.
  • Velden zijn niet gebonden. In de voorgaande code, Position is niet gebonden. Het Position veld wordt gebruikt, zodat de tekenreeks "Position" niet hard gecodeerd hoeft te worden in de app wanneer de klasse aan een configuratieprovider wordt gekoppeld.

De volgende code:

  • Roept ConfigurationBinder.Bind aan om de PositionOptions klasse aan de Position sectie te binden.
  • Geeft de Position configuratiegegevens weer.
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}");
    }
}

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand standaard gelezen nadat de app is gestart.

ConfigurationBinder.Get<T> bindt en retourneert het opgegeven type. ConfigurationBinder.Get<T>kan handiger zijn dan het gebruik.ConfigurationBinder.Bind De volgende code laat zien hoe u deze kunt gebruiken ConfigurationBinder.Get<T> met de PositionOptions klasse:

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

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand standaard gelezen nadat de app is gestart.

Een alternatieve benadering bij het gebruik van het optiepatroon is om de Position sectie te binden en toe te voegen aan de afhankelijkheidsinjectieservicecontainer. In de volgende code PositionOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Met behulp van de voorgaande code leest de volgende code de positieopties:

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

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand nadat de app is gestart, niet gelezen. Als u wijzigingen wilt lezen nadat de app is gestart, gebruikt u IOptionsSnapshot.

Met behulp van de standaardconfiguratie worden de appsettings.json en appsettings.{Environment}.json bestanden ingeschakeld met reloadOnChange: true. Wijzigingen die zijn aangebracht in het appsettings.json bestand en het appsettings.{Environment}.json bestand nadat de app gestart is, worden gelezen door JSON-configuratieprovider.

Zie de JSON-configuratieprovider in dit document voor informatie over het toevoegen van extra JSON-configuratiebestanden.

Serviceverzameling combineren

Houd rekening met het volgende waarmee services worden geregistreerd en opties worden geconfigureerd:

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

Gerelateerde groepen registraties kunnen worden verplaatst naar een extensiemethode om services te registreren. De configuratieservices worden bijvoorbeeld toegevoegd aan de volgende klasse:

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 resterende services worden geregistreerd in een vergelijkbare klasse. De volgende code maakt gebruik van de nieuwe extensiemethoden om de services te registreren:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Opmerking: Elke services.Add{GROUP_NAME} extensiemethode voegt services toe en configureert deze mogelijk. AddControllersWithViews voegt bijvoorbeeld de services toe die vereist zijn door MVC-controllers met weergaven, en AddRazorPages voegt de services toe die vereist zijn door Razor Pagina's.

Beveiligings- en gebruikersgeheimen

Richtlijnen voor configuratiegegevens:

  • Sla nooit wachtwoorden of andere gevoelige gegevens op in configuratieprovidercode of in configuratiebestanden met tekst zonder opmaak. Het hulpprogramma Secret Manager kan worden gebruikt om geheimen voor ontwikkelingsdoeleinden op te slaan.
  • Gebruik geen productiegeheimen in ontwikkel- of testomgevingen.
  • Geef geheimen buiten het project op, zodat ze niet per ongeluk kunnen worden doorgevoerd in een opslagplaats met broncode.
  • Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromen voor meer informatie.

Standaard wordt de configuratiebron voor gebruikersgeheimen geregistreerd na de JSON-configuratiebronnen. Daarom hebben gebruikersgeheimsleutels voorrang op sleutels in appsettings.json en appsettings.{Environment}.json.

Voor meer informatie over het opslaan van wachtwoorden of andere gevoelige gegevens:

Omgevingsvariabelen zonder voorvoegsel

Omgevingsvariabelen zonder voorvoegsel zijn andere omgevingsvariabelen dan omgevingsvariabelen die zijn voorafgegaan door ASPNETCORE_ of DOTNET_. Bijvoorbeeld, de sjablonen voor ASP.NET Core-webtoepassingen stellen "ASPNETCORE_ENVIRONMENT": "Development" in launchSettings.json in. Zie voor meer informatie over ASPNETCORE_ en DOTNET_ omgevingsvariabelen:

Met behulp van de standaardconfiguratie laadt de EnvironmentVariablesConfigurationProvider configuratie van sleutel-waardeparen van de omgevingsvariabele na het lezenappsettings.jsonappsettings.{Environment}.json, en gebruikersgeheimen. Sleutelwaarden die uit de omgeving worden gelezen, overschrijven daarom waarden uit appsettings.json, appsettings.{Environment}.json en gebruikersgeheimen.

Het :-scheidingsteken werkt niet met hiërarchische sleutels van omgevingsvariabelen op alle platformen. Het :-scheidingsteken wordt bijvoorbeeld niet ondersteund door Bash. Het dubbele onderstrepingsteken, __, is:

  • Ondersteund door alle platforms.
  • Automatisch vervangen door dubbelpunt, :.

De volgende opdrachten:

  • Stel de omgevingssleutels en -waarden in van het voorgaande voorbeeld in Windows.
  • Test de instellingen bij het gebruik van het voorbeelddownload. De dotnet run opdracht moet worden uitgevoerd in de projectmap.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

De voorgaande omgevingsinstellingen:

  • Worden alleen ingesteld in processen die zijn gestart vanuit het opdrachtvenster waarin ze zijn ingesteld.
  • Wordt niet gelezen door browsers die zijn gestart met Visual Studio.

De volgende setx-opdrachten kunnen worden gebruikt om de omgevingssleutels en -waarden in Windows in te stellen. In tegenstelling tot set, setx instellingen blijven behouden. /M stelt de variabele in de systeemomgeving in. Als de /M switch niet wordt gebruikt, wordt een gebruikersomgevingsvariabele ingesteld.

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

Testen of de voorgaande opdrachten appsettings.json en appsettings.{Environment}.json overschrijven:

  • Met Visual Studio: Visual Studio afsluiten en opnieuw starten.
  • Met de CLI: Start een nieuw opdrachtvenster en voer dit in dotnet run.

Roep AddEnvironmentVariables een tekenreeks aan om een voorvoegsel voor omgevingsvariabelen op te geven:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

In de voorgaande code:

Het voorvoegsel wordt verwijderd wanneer de configuratiesleutel-waardeparen worden gelezen.

Met de volgende opdrachten wordt het aangepaste voorvoegsel getest:

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

De standaardconfiguratie laadt omgevingsvariabelen en opdrachtregelargumenten voorafgegaan door DOTNET_ en ASPNETCORE_. De DOTNET_ en ASPNETCORE_ voorvoegsels worden gebruikt door ASP.NET Core voor host- en app-configuratie, maar niet voor gebruikersconfiguratie. Zie .NET Generic Host voor meer informatie over host- en app-configuratie.

Selecteer op Azure-app Service de optie Nieuwe toepassingsinstelling Azure-app servicetoepassingsinstellingen zijn:

  • Versleuteld at-rest en verzonden via een versleuteld kanaal.
  • Weergegeven als omgevingsvariabelen.

Zie Azure Apps: App-configuratie overschrijven met behulp van Azure Portal voor meer informatie.

Zie verbindingsreeksvoorvoegsels voor informatie over Verbindingsreeksen in Azure Database.

Naamgeving van omgevingsvariabelen

Namen van omgevingsvariabelen weerspiegelen de structuur van een appsettings.json bestand. Elk element in de hiërarchie wordt gescheiden door een dubbele onderstrepingsteken (bij voorkeur) of een dubbele punt. Wanneer de elementstructuur een matrix bevat, moet de matrixindex worden behandeld als een extra elementnaam in dit pad. Houd rekening met het volgende appsettings.json bestand en de bijbehorende equivalente waarden die worden weergegeven als omgevingsvariabelen.

appsettings.json

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

Omgevingsvariabelen

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

Omgevingsvariabelen die zijn ingesteld in gegenereerde launchSettings.json

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving. De ASP.NET Core-websjablonen genereren bijvoorbeeld een launchSettings.json bestand waarmee de eindpuntconfiguratie wordt ingesteld op:

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

Door de applicationUrl te configureren, wordt de ASPNETCORE_URLS omgevingsvariabele ingesteld en worden waarden in de omgeving overschreven.

Omgevingsvariabelen ontsnappen in Linux

Op Linux moeten de waarden van URL-omgevingsvariabelen worden geëscaped zodat systemd deze kan parsen. Gebruik de Linux-tool systemd-escape die http:--localhost:5001 oplevert

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

Omgevingsvariabelen weergeven

In de volgende code worden de omgevingsvariabelen en -waarden weergegeven bij het opstarten van toepassingen. Dit kan handig zijn bij het opsporen van fouten in de omgevingsinstellingen:

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

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

Opdrachtregel

Met behulp van de standaardconfiguratie laadt de CommandLineConfigurationProvider de configuratie, van sleutel-waardekoppels van opdrachtregelargumenten, na de volgende configuratiebronnen:

  • appsettings.json en appsettings.{Environment}.json bestanden.
  • App-geheimen in de ontwikkelomgeving.
  • Omgevingsvariabelen.

Standaard worden configuratiewaarden die zijn ingesteld op de opdrachtregel configuratiewaarden vervangen die zijn ingesteld bij alle andere configuratieproviders.

Opdrachtregelargumenten

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van =:

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

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van /:

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

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van --:

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

De sleutelwaarde:

  • Moet volgen =of de sleutel moet een voorvoegsel hebben van -- of / wanneer de waarde een spatie volgt.
  • Is niet vereist als = deze wordt gebruikt. Bijvoorbeeld: MySetting=.

Combineer binnen dezelfde opdracht geen sleutel-waardeparen met opdrachtregelargumenten die worden gebruikt = met sleutel-waardeparen die gebruikmaken van een spatie.

Switchtoewijzingen

Schakelmappingen staan vervangingslogica voor sleutelnamen toe. Geef een woordenlijst op met switchvervangingen voor de AddCommandLine methode.

Wanneer het woordenboek voor switchtoewijzingen wordt gebruikt, wordt het woordenboek gecontroleerd op een sleutel die overeenkomt met de sleutel die door een opdrachtregelargument wordt geleverd. Als de opdrachtregelsleutel wordt gevonden in de woordenlijst, wordt de waarde van de woordenlijst teruggegeven om het sleutel-waardepaar in te stellen in de configuratie van de app. Een switchtoewijzing is vereist voor elke opdrachtregelsleutel die wordt voorafgegaan door één streepje (-).

Regels voor sleutels van schakelmappings in woordenboeken:

  • Schakelopties moeten beginnen met - of --.
  • De woordenlijst voor switchtoewijzingen mag geen dubbele sleutels bevatten.

Als u een woordenlijst voor switchtoewijzingen wilt gebruiken, geeft u deze door bij de aanroep van 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();

Voer de volgende opdracht uit om de sleutelvervanging te testen:

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

De volgende code toont de sleutelwaarden voor de vervangen sleutels:

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

Voor apps die switchtoewijzingen gebruiken, mag de aanroep geen argumenten doorgeven. De CreateDefaultBuilder aanroep van AddCommandLine de methode bevat geen toegewezen switches en er is geen manier om de woordenlijst voor switchtoewijzing door te geven aan CreateDefaultBuilder. De oplossing is niet om de argumenten door te geven aanCreateDefaultBuilder, maar in plaats daarvan de methode van AddCommandLine de ConfigurationBuilder methode toe te staan zowel de argumenten als de woordenlijst voor switchtoewijzing te verwerken.

Omgevings- en opdrachtregelargumenten instellen met Visual Studio

Omgevings- en opdrachtregelargumenten kunnen in Visual Studio worden ingesteld vanuit het dialoogvenster Opstartprofielen:

  • Klik in Solution Explorer met de rechtermuisknop op het project en selecteer Eigenschappen.
  • Selecteer het tabblad Foutopsporings > algemeen en selecteer de gebruikersinterface voor het openen van startprofielen voor foutopsporing.

Hiërarchische configuratiegegevens

De configuratie-API leest hiërarchische configuratiegegevens door de hiërarchische gegevens plat te maken met behulp van een scheidingsteken in de configuratiesleutels.

Het voorbeelddownload bevat het volgende appsettings.json bestand:

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

In de volgende code van het voorbeelddownload worden verschillende configuratie-instellingen weergegeven:

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

De voorkeursmethode voor het lezen van hiërarchische configuratiegegevens is het gebruik van het optiespatroon. Zie Hiërarchische bindingsconfiguratiegegevens in dit document voor meer informatie.

GetSection en GetChildren methoden zijn beschikbaar om secties en onderliggende elementen van een sectie in de configuratiegegevens te isoleren. Deze methoden worden verderop beschreven in GetSection, GetChildren en Exists.

Configuratiesleutels en -waarden

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

Configuratiesleutels:

  • Zijn niet hoofdlettergevoelig. ConnectionString en connectionstring worden bijvoorbeeld behandeld als gelijkwaardige sleutels.
  • Als een sleutel en waarde zijn ingesteld in meer dan één configuratieprovider, wordt de waarde van de laatste toegevoegde provider gebruikt. Zie De standaardconfiguratie voor meer informatie.
  • Hiërarchische sleutels
    • Binnen de configuratie-API werkt een dubbele puntscheidingsteken (:) op alle platforms.
    • In omgevingsvariabelen werkt een dubbele punt als scheidingsteken mogelijk niet op alle platforms. Een dubbele onderstrepingsteken, __, wordt ondersteund door alle platforms en wordt automatisch omgezet naar een dubbelpunt :.
    • In Azure Key Vault gebruiken hiërarchische sleutels -- als scheidingsteken. De Azure Key Vault-configuratieprovider vervangt automatisch -- door een : wanneer de geheimen in de configuratie van de app worden geladen.
  • De ConfigurationBinder functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Matrixbinding wordt beschreven in de matrix binden aan een klassesectie .

Configuratiewaarden:

  • Dit zijn tekenreeksen.
  • Null-waarden kunnen niet worden opgeslagen in de configuratie of gebonden aan objecten.

Configuratieproviders

In de volgende tabel ziet u de configuratieproviders die beschikbaar zijn voor ASP.NET Core-apps.

Aanbieder Zorgt voor configuratie vanuit
Azure Key Vault-configuratieprovider Azure Key Vault
Azure-app-configuratieprovider Azure App Configuration (Configuratie van Azure-apps)
Commandoregelconfiguratieprovider Opdrachtregelparameters
aangepaste configuratieprovider Aangepaste bron
configuratieprovider voor omgevingsvariabelen Omgevingsvariabelen
bestandsconfiguratieprovider INI-, JSON- en XML-bestanden
nl-NL: Sleutel-per-bestand-configuratieprovider Directorybestanden
geheugenconfiguratieprovider Verzamelingen in het geheugen
Gebruikersgeheimen Het bestand in de gebruikersprofielmap

Configuratiebronnen worden gelezen in de volgorde waarin hun configuratieproviders worden opgegeven. Rangschik configuratieproviders in de code volgens de prioriteiten voor de configuratiebronnen die de app nodig heeft.

Een typische reeks configuratieproviders is:

  1. appsettings.json
  2. appsettings.{Environment}.json
  3. Gebruikersgeheimen
  4. Omgevingsvariabelen met behulp van de configuratieprovider Omgevingsvariabelen .
  5. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.

Een veelvoorkomende procedure is om de opdrachtregelconfiguratieprovider voor het laatst toe te voegen in een reeks providers om opdrachtregelargumenten toe te staan om de configuratie die door de andere providers is ingesteld, te overschrijven.

De voorgaande reeks providers wordt gebruikt in de standaardconfiguratie.

Verbindingsreeksvoorvoegsels

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

De configuratie-API heeft speciale verwerkingsregels voor vier verbindingsreeks omgevingsvariabelen. Deze verbindingsreeks zijn betrokken bij het configureren van Azure-verbindingsreeks s voor de app-omgeving. Omgevingsvariabelen met de voorvoegsels die in de tabel worden weergegeven, worden in de app geladen met de standaardconfiguratie of wanneer er geen voorvoegsel wordt opgegeven aan AddEnvironmentVariables.

Verbindingsreeksvoorvoegsel Aanbieder
CUSTOMCONNSTR_ Aangepaste leverancier
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

Wanneer een omgevingsvariabele wordt gedetecteerd en in de configuratie wordt geladen met een van de vier voorvoegsels die in de tabel worden weergegeven:

  • De configuratiesleutel wordt gemaakt door het voorvoegsel van de omgevingsvariabele te verwijderen en een sectie met een configuratiesleutel (ConnectionStrings) toe te voegen.
  • Er wordt een nieuw sleutel-waardepaar voor de configuratie gemaakt dat de databaseverbindingsprovider vertegenwoordigt (met uitzondering van CUSTOMCONNSTR_, waarvoor geen vermelde provider is opgegeven).
Sleutel voor omgevingsvariabele Geconverteerde configuratiesleutel Providerconfiguratie-vermelding
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Configuratievermelding niet gemaakt.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: System.Data.SqlClient

Bestandsconfiguratieprovider

FileConfigurationProvider is de basisklasse voor het laden van de configuratie van het bestandssysteem. De volgende configuratieproviders zijn afgeleid van FileConfigurationProvider:

INI-configuratieprovider

De IniConfigurationProvider laadt tijdens runtime configuratie vanuit INI-bestandssleutel-waardeparen.

Met de volgende code worden verschillende configuratieproviders toegevoegd:

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

In de voorgaande code worden instellingen in de MyIniConfig.ini en MyIniConfig.{Environment}.ini bestanden overschreven door instellingen in de:

Het voorbeelddownload bevat het volgende MyIniConfig.ini bestand:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

De JsonConfigurationProvider laadt de configuratie vanuit de sleutel-waardeparen van het JSON-bestand.

Overbelastingen kunnen het volgende opgeven:

  • Of het bestand optioneel is.
  • Of de configuratie opnieuw wordt geladen als het bestand wordt gewijzigd.

Houd rekening met de volgende code:

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

De voorgaande code:

  • Hiermee configureert u de JSON-configuratieprovider om het MyConfig.json bestand te laden met de volgende opties:
    • optional: true: Het bestand is optioneel.
    • reloadOnChange: true : het bestand wordt opnieuw geladen wanneer wijzigingen worden opgeslagen.
  • Leest de standaardconfiguratieproviders vóór het MyConfig.json bestand. Instellingen in de MyConfig.json instelling voor het overschrijven van bestanden in de standaardconfiguratieproviders, waaronder de configuratieprovider voor omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

Normaal gesproken wilt u geen aangepast JSON-bestand dat waarden overschrijft die zijn ingesteld in de configuratieprovider omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

XML-configuratieprovider

De XmlConfigurationProvider configuratie wordt tijdens runtime geladen van sleutel-waardeparen van XML-bestanden.

Met de volgende code worden verschillende configuratieproviders toegevoegd:

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

In de voorgaande code worden instellingen in de MyXMLFile.xml en MyXMLFile.{Environment}.xml bestanden overschreven door instellingen in de:

Het voorbeelddownload bevat het volgende MyXMLFile.xml bestand:

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

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

Herhalende elementen die dezelfde elementnaam gebruiken, werken als het name kenmerk wordt gebruikt om de elementen te onderscheiden:

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

De volgende code leest het vorige configuratiebestand en geeft de sleutels en waarden weer:

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

Kenmerken kunnen worden gebruikt om waarden op te geven:

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

In het vorige configuratiebestand worden de volgende sleutels geladen met value:

  • key:attribute
  • section:key:attribute

Configuratieprovider voor sleutel per bestand

De KeyPerFileConfigurationProvider map maakt gebruik van de bestanden van een map als configuratiesleutel-waardeparen. De sleutel is de bestandsnaam. De waarde bevat de inhoud van het bestand. De key-per-file-configuratieprovider wordt gebruikt in Docker-hostingscenario's.

Als u key-per-file-configuratie wilt activeren, roept u de AddKeyPerFile extensiemethode aan op een exemplaar van ConfigurationBuilder. De directoryPath bestanden moeten een absoluut pad zijn.

Overbelastingen maken het opgeven van:

  • Een Action<KeyPerFileConfigurationSource> gemachtigde die de bron configureert.
  • Of de map optioneel is en of het pad naar de map is.

Het dubbele onderstrepingsteken (__) wordt gebruikt als scheidingsteken voor configuratiesleutels in bestandsnamen. De bestandsnaam Logging__LogLevel__System produceert bijvoorbeeld de configuratiesleutel Logging:LogLevel:System.

Aanroepen ConfigureAppConfiguration bij het bouwen van de host om de configuratie van de app op te geven:

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

Geheugenconfiguratieprovider

Hierbij MemoryConfigurationProvider wordt een verzameling in het geheugen gebruikt als configuratiesleutel-waardeparen.

Met de volgende code wordt een geheugenverzameling toegevoegd aan het configuratiesysteem:

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

In de volgende code van het voorbeelddownload worden de voorgaande configuratie-instellingen weergegeven:

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

In de voorgaande code config.AddInMemoryCollection(Dict) wordt deze toegevoegd na de standaardconfiguratieproviders. Zie JSON-configuratieprovider voor een voorbeeld van het ordenen van de configuratieprovider.

Zie Een matrix binden voor een ander voorbeeld met behulp van MemoryConfigurationProvider.

Kestrel eindpuntconfiguratie

Kestrel specifieke eindpuntconfiguratie overschrijft alle serveroverschrijdende eindpuntconfiguraties. Configuraties voor eindpunten tussen servers zijn onder andere:

Houd rekening met het volgende appsettings.json bestand dat wordt gebruikt in een ASP.NET Core-web-app:

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

Wanneer de voorgaande gemarkeerde markering wordt gebruikt in een ASP.NET Core-web-app en de app wordt gestart op de opdrachtregel met de volgende server-overschrijdende eindpuntconfiguratie:

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

Kestrel verbindt met het eindpunt dat specifiek is geconfigureerd voor Kestrel in het appsettings.json bestand (https://localhost:9999) en niet https://localhost:7777.

Overweeg het Kestrel specifieke eindpunt dat is geconfigureerd als een omgevingsvariabele:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

In de voorgaande omgevingsvariabele Https is dit de naam van het Kestrel specifieke eindpunt. Het voorgaande appsettings.json bestand definieert ook een specifiek eindpunt met de Kestrel naam Https. Standaard wordt de omgevingsvariabele die gebruikmaakt van de configuratieprovider Omgevingsvariabelen gelezen nadat appsettings.{Environment}.json, daarom wordt de voorgaande omgevingsvariabele gebruikt voor het Https eindpunt.

WaardeOphalen

ConfigurationBinder.GetValue extraheert één waarde uit de configuratie met een opgegeven sleutel en converteert deze naar het opgegeven type:

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

In de voorgaande code, als NumberKey niet in de configuratie wordt gevonden, wordt de standaardwaarde 99 gebruikt.

GetSection, GetChildren en Exists

Bekijk het volgende MySubsection.json bestand voor de volgende voorbeelden:

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

De volgende code voegt MySubsection.json toe aan de configuratieproviders:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection retourneert een configuratiesubsectie met de opgegeven subsectiesleutel.

De volgende code retourneert waarden voor 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"]}'");
    }
}

De volgende code retourneert waarden voor 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 keert nullnooit terug. Als er geen overeenkomende sectie wordt gevonden, wordt een lege IConfigurationSection sectie geretourneerd.

Wanneer GetSection een overeenkomende sectie retourneert, wordt Value niet ingevuld. Key en Path worden geretourneerd wanneer de sectie bestaat.

GetChildren and Exists

De volgende code roept IConfiguration.GetChildren waarden aan en retourneert waarden voor 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);
    }
}

De voorgaande code aanroepen ConfigurationExtensions.Exists om te controleren of de sectie bestaat:

Een matrix binden

De ConfigurationBinder.Bind functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Elke matrixindeling die een numeriek sleutelsegment beschikbaar maakt, kan matrixbindingen uitvoeren op een POCO-klassematrix .

Houd rekening met MyArray.json uit de voorbeeld-download:

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

De volgende code voegt MyArray.json toe aan de configuratieproviders:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Met de volgende code wordt de configuratie gelezen en worden de waarden weergegeven:

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

De voorgaande code retourneert de volgende uitvoer:

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

In de voorgaande uitvoer heeft Index 3 een waarde value40die overeenkomt met "4": "value40", in MyArray.json. De afhankelijke matrixindexen zijn doorlopend en zijn niet gebonden aan de configuratiesleutelindex. De configuratiebinding kan geen null-waarden binden of null-vermeldingen maken in afhankelijke objecten.

Aangepaste configuratieprovider

De voorbeeld-app laat zien hoe u een eenvoudige configuratieprovider maakt die configuratiesleutel-waardeparen van een database leest met behulp van Entity Framework (EF).

De provider heeft de volgende kenmerken:

  • De EF-database in het geheugen wordt gebruikt voor demonstratiedoeleinden. Als u een database wilt gebruiken waarvoor een verbindingsreeks is vereist, implementeert u een secundaire ConfigurationBuilder om de verbindingsreeks van een andere configuratieprovider op te geven.
  • De provider leest een databasetabel in de configuratie bij het opstarten. De provider doorzoekt de database niet per sleutel.
  • Reload-on-change is niet geïmplementeerd, dus het bijwerken van de database nadat de app is gestart, heeft geen invloed op de configuratie van de app.

Definieer een EFConfigurationValue entiteit voor het opslaan van configuratiewaarden in de database.

Models/EFConfigurationValue.cs:

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

Voeg een EFConfigurationContext toe om de geconfigureerde waarden op te slaan en te openen.

EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Maak een klasse die IConfigurationSource implementeert.

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

Maak de aangepaste configuratieprovider door deze over te nemen van ConfigurationProvider. De configuratieprovider initialiseert de database wanneer deze leeg is. Omdat configuratiesleutels niet hoofdlettergevoelig zijn, wordt de woordenlijst die wordt gebruikt om de database te initialiseren gemaakt met de niet-hoofdlettergevoelige vergelijking (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;
    }
}

Met een AddEFConfiguration extensiemethode kan de configuratiebron worden toegevoegd aan een ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

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

De volgende code laat zien hoe u de aangepaste EFConfigurationProvider code gebruikt in Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Toegangsconfiguratie met afhankelijkheidsinjectie (DI)

Configuratie kan worden geïnjecteerd in services met behulp van afhankelijkheidsinjectie (DI) door de service IConfiguration op te lossen.

public class Service
{
    private readonly IConfiguration _config;

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

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

        // ...
    }
}

Zie voor informatie over hoe u waarden kunt benaderen met behulp van IConfiguration, GetValue en GetSection, GetChildren en Exists in dit artikel.

Configuratie voor toegang in Razor Pagina's

De volgende code geeft configuratiegegevens weer op een Razor pagina:

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

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

In de volgende code MyOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

In de volgende markeringen wordt de @injectRazor instructie gebruikt om de waarde van de opties op te lossen en weer te geven:

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

Toegangsconfiguratie in een MVC-weergavebestand

De volgende code geeft configuratiegegevens weer in een MVC-weergave:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Toegangsconfiguratie in Program.cs

De volgende code heeft toegang tot de configuratie in het Program.cs bestand.

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

In appsettings.json het voorgaande voorbeeld:

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

Opties configureren met een gemachtigde

Opties die zijn geconfigureerd in een delegaat, overschrijven waarden die zijn ingesteld in de configuratieproviders.

In de volgende code wordt een IConfigureOptions<TOptions> service toegevoegd aan de servicecontainer. Er wordt een gemachtigde gebruikt om waarden te configureren voor 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();

In de volgende code worden de optieswaarden weergegeven:

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

In het voorgaande voorbeeld worden de waarden van Option1 en Option2 opgegeven in appsettings.json en vervolgens overschreven door de geconfigureerde gemachtigde.

Host versus app-configuratie

Voordat de app is geconfigureerd en gestart, wordt een host geconfigureerd en gestart. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. Zowel de app als de host worden geconfigureerd met behulp van de configuratieproviders die in dit onderwerp worden beschreven. Hostconfiguratiesleutel-waardeparen worden ook opgenomen in de configuratie van de app. Zie voor meer informatie over hoe de configuratieproviders worden gebruikt wanneer de host wordt gebouwd en hoe configuratiebronnen van invloed zijn op de hostconfiguratie ASP.NET overzicht van basisbeginselen.

Standaardhostconfiguratie

Zie de ASP.NET Core 2.2-versie van dit onderwerp voor meer informatie over de standaardconfiguratie wanneer u de webhost gebruikt.

  • Hostconfiguratie wordt geleverd van:
  • De standaardconfiguratie van de webhost is ingesteld (ConfigureWebHostDefaults):
    • Kestrel wordt gebruikt als de webserver en geconfigureerd met behulp van de configuratieproviders van de app.
    • Voeg middleware voor het filteren van hosts toe.
    • Voeg Forwarded Headers-middleware toe als de ASPNETCORE_FORWARDEDHEADERS_ENABLED omgevingsvariabele is gesteld op true.
    • IIS-integratie inschakelen.

Andere configuratie

Dit onderwerp heeft alleen betrekking op app-configuratie. Andere aspecten van het uitvoeren en hosten van ASP.NET Core-apps worden geconfigureerd met behulp van configuratiebestanden die niet in dit onderwerp worden behandeld:

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving.

Zie Configuratie migreren naar ASP.NET Core voor meer informatie over het migreren van app-configuratie van eerdere versies van ASP.NET.

Configuratie toevoegen vanuit een externe assembly

Met een IHostingStartup-implementatie kunt u verbeteringen aan een app toevoegen bij het opstarten vanuit een externe assembly buiten de Startup klasse van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Configuratiebindingsbrongenerator

De brongenerator voor configuratiebinding biedt een AOT- en trimvriendelijke configuratie. Zie configuratiebindingsbrongenerator voor meer informatie.

Aanvullende bronnen

Toepassingsconfiguratie in ASP.NET Core wordt uitgevoerd met behulp van een of meer configuratieproviders. Configuratieproviders lezen configuratiegegevens van sleutel-waardeparen met behulp van verschillende configuratiebronnen:

  • Instellingenbestanden, zoals appsettings.json
  • Omgevingsvariabelen
  • Azure Key Vault
  • Azure App Configuration (Configuratie van Azure-apps)
  • Opdrachtregelargumenten
  • Aangepaste providers, geïnstalleerd of gemaakt
  • Directorybestanden
  • .NET-objecten in het geheugen

Dit artikel bevat informatie over de configuratie in ASP.NET Core. Zie .NET-configuratie voor meer informatie over het gebruik van configuratie in console-apps.

Toepassings- en hostconfiguratie

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. De ASP.NET Core-sjablonen maken een WebApplicationBuilder sjabloon die de host bevat. Hoewel sommige configuraties kunnen worden uitgevoerd in zowel de host als de toepassingsconfiguratieproviders, moet doorgaans alleen de configuratie die nodig is voor de host worden uitgevoerd in de hostconfiguratie.

Toepassingsconfiguratie is de hoogste prioriteit en wordt in de volgende sectie beschreven. Hostconfiguratie volgt de toepassingsconfiguratie en wordt beschreven in dit artikel.

Standaardbronnen voor toepassingsconfiguratie

ASP.NET Core-web-apps die zijn gemaakt met dotnet nieuwe of Visual Studio genereren de volgende code:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder-klasse met vooraf geconfigureerde standaardwaarden. De geïnitialiseerde WebApplicationBuilder (builder) biedt standaardconfiguratie voor de app in de volgende volgorde, van hoogste naar laagste prioriteit:

  1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.
  2. Omgevingsvariabelen zonder voorvoegsel met behulp van de configuratieprovider voor omgevingsvariabelen zonder voorvoegsel.
  3. Gebruikersgeheimen wanneer de app draait in de Development-omgeving.
  4. appsettings.{Environment}.json met behulp van de JSON-configuratieprovider. Bijvoorbeeld appsettings.Production.json en appsettings.Development.json.
  5. appsettings.json met de JSON-configuratieprovider.
  6. Een terugval naar de hostconfiguratie die wordt beschreven in de volgende sectie.

Standaardhostconfiguratiebronnen

De volgende lijst bevat de standaardhostconfiguratiebronnen van hoogste naar laagste prioriteit voor WebApplicationBuilder:

  1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider
  2. Omgevingsvariabelen die beginnen met DOTNET_ met behulp van de configuratieprovider voor omgevingsvariabelen.
  3. Omgevingsvariabelen die beginnen met ASPNETCORE_ met behulp van de configuratieprovider voor omgevingsvariabelen.

Voor de .NET Generic Host en Web Host zijn de standaardhostconfiguratiebronnen van hoogste naar laagste prioriteit:

  1. Omgevingsvariabelen die beginnen met ASPNETCORE_ met behulp van de configuratieprovider voor omgevingsvariabelen.
  2. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider
  3. Omgevingsvariabelen die beginnen met DOTNET_ met behulp van de configuratieprovider voor omgevingsvariabelen.

Wanneer een configuratiewaarde is ingesteld in de host- en toepassingsconfiguratie, wordt de toepassingsconfiguratie gebruikt.

Hostvariabelen

De volgende variabelen worden vroeg vergrendeld bij het initialiseren van de hostbuilders en kunnen niet worden beïnvloed door de configuratie van de toepassing:

Elke andere hostinstelling wordt gelezen uit de configuratie van de toepassing in plaats van de hostconfiguratie.

URLS is een van de vele algemene hostinstellingen die geen bootstrap-instelling is. Net als elke andere hostinstelling die niet in de vorige lijst staat, URLS wordt deze later gelezen uit de configuratie van de toepassing. Hostconfiguratie is een terugval voor toepassingsconfiguratie, dus hostconfiguratie kan worden gebruikt om in te stellen URLS, maar deze wordt overschreven door elke configuratiebron in de configuratie van de toepassing, zoals appsettings.json.

Zie De hoofdmap, app-naam en omgeving van deinhoud wijzigen en de inhoudshoofdmap, app-naam en omgeving wijzigen op omgevingsvariabelen of opdrachtregel voor meer informatie

De overige secties in dit artikel verwijzen naar toepassingsconfiguratie.

Toepassingsconfiguratieproviders

De volgende code geeft de ingeschakelde configuratieproviders weer in de volgorde waarin ze zijn toegevoegd:

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

In de voorgaande lijst met standaardconfiguratiebronnen met de hoogste tot laagste prioriteit worden de providers weergegeven in de tegenovergestelde volgorde waarin ze worden toegevoegd aan de door de sjabloon gegenereerde toepassing. De JSON-configuratieprovider wordt bijvoorbeeld toegevoegd vóór de opdrachtregelconfiguratieprovider.

Configuratieproviders die later worden toegevoegd, hebben een hogere prioriteit en overschrijven eerdere sleutelinstellingen. Als MyKey is ingesteld in zowel appsettings.json als in de omgeving, wordt de waarde van de omgeving gebruikt. Met behulp van de standaardconfiguratieproviders overschrijft de opdrachtregelconfiguratieprovider alle andere providers.

Zie Instellingen voor standaardbouwer voor meer informatieCreateBuilder.

appsettings.json

Houd rekening met het volgende appsettings.json bestand:

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

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

De standaardconfiguratie JsonConfigurationProvider wordt geladen in de volgende volgorde:

  1. appsettings.json
  2. appsettings.{Environment}.json : bijvoorbeeld de appsettings.Production.json en appsettings.Development.json bestanden. De omgevingsversie van het bestand wordt geladen op basis van de IHostingEnvironment.EnvironmentName. Zie Meerdere omgevingen gebruiken in ASP.NET Core voor meer informatie.

appsettings.{Environment}.json waarden overschrijven sleutels in appsettings.json. Bijvoorbeeld, standaard:

  • Tijdens ontwikkeling overschrijft appsettings.Development.json configuratiewaarden in appsettings.json.
  • In productie overschrijft appsettings.Production.json configuratie de waarden in appsettings.json. Bijvoorbeeld bij het implementeren van de app in Azure.

Als een configuratiewaarde moet worden gegarandeerd, raadpleegt u GetValue. In het voorgaande voorbeeld worden alleen tekenreeksen gelezen en wordt geen standaardwaarde ondersteund.

Met behulp van de standaardconfiguratie worden de appsettings.json en appsettings.{Environment}.json bestanden ingeschakeld met reloadOnChange: true. Wijzigingen die zijn aangebracht in het appsettings.json bestand en het appsettings.{Environment}.json bestand nadat de app gestart is, worden gelezen door JSON-configuratieprovider.

Opmerkingen in appsettings.json

Opmerkingen in appsettings.json en appsettings.{Environment}.jsonbestanden worden ondersteund met javaScript- of C#-stijlopmerkingen.

Hiërarchische configuratiegegevens binden met behulp van het optiespatroon

De voorkeursmethode voor het lezen van gerelateerde configuratiewaarden is het gebruik van het patroon opties. Bijvoorbeeld om de volgende configuratiewaarden te lezen:

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

Maak de volgende PositionOptions klasse:

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

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

Een opties klasse:

  • Moet niet-abstract zijn met een openbare parameterloze constructor.
  • Alle openbare lees-schrijfeigenschappen van het type zijn gebonden.
  • Velden zijn niet gebonden. In de voorgaande code, Position is niet gebonden. Het Position veld wordt gebruikt, zodat de tekenreeks "Position" niet hard gecodeerd hoeft te worden in de app wanneer de klasse aan een configuratieprovider wordt gekoppeld.

De volgende code:

  • Roept ConfigurationBinder.Bind aan om de PositionOptions klasse aan de Position sectie te binden.
  • Geeft de Position configuratiegegevens weer.
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}");
    }
}

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand standaard gelezen nadat de app is gestart.

ConfigurationBinder.Get<T> bindt en retourneert het opgegeven type. ConfigurationBinder.Get<T>kan handiger zijn dan het gebruik.ConfigurationBinder.Bind De volgende code laat zien hoe u deze kunt gebruiken ConfigurationBinder.Get<T> met de PositionOptions klasse:

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

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand standaard gelezen nadat de app is gestart.

Een alternatieve benadering bij het gebruik van het optiepatroon is om de Position sectie te binden en toe te voegen aan de afhankelijkheidsinjectieservicecontainer. In de volgende code PositionOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Met behulp van de voorgaande code leest de volgende code de positieopties:

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

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand nadat de app is gestart, niet gelezen. Als u wijzigingen wilt lezen nadat de app is gestart, gebruikt u IOptionsSnapshot.

Met behulp van de standaardconfiguratie worden de appsettings.json en appsettings.{Environment}.json bestanden ingeschakeld met reloadOnChange: true. Wijzigingen die zijn aangebracht in het appsettings.json bestand en het appsettings.{Environment}.json bestand nadat de app gestart is, worden gelezen door JSON-configuratieprovider.

Zie de JSON-configuratieprovider in dit document voor informatie over het toevoegen van extra JSON-configuratiebestanden.

Serviceverzameling combineren

Houd rekening met het volgende waarmee services worden geregistreerd en opties worden geconfigureerd:

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

Gerelateerde groepen registraties kunnen worden verplaatst naar een extensiemethode om services te registreren. De configuratieservices worden bijvoorbeeld toegevoegd aan de volgende klasse:

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 resterende services worden geregistreerd in een vergelijkbare klasse. De volgende code maakt gebruik van de nieuwe extensiemethoden om de services te registreren:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Opmerking: Elke services.Add{GROUP_NAME} extensiemethode voegt services toe en configureert deze mogelijk. AddControllersWithViews voegt bijvoorbeeld de services toe die vereist zijn door MVC-controllers met weergaven, en AddRazorPages voegt de services toe die vereist zijn door Razor Pagina's.

Beveiligings- en gebruikersgeheimen

Richtlijnen voor configuratiegegevens:

  • Sla nooit wachtwoorden of andere gevoelige gegevens op in configuratieprovidercode of in configuratiebestanden met tekst zonder opmaak. Het hulpprogramma Secret Manager kan worden gebruikt om geheimen voor ontwikkelingsdoeleinden op te slaan.
  • Gebruik geen productiegeheimen in ontwikkel- of testomgevingen.
  • Geef geheimen buiten het project op, zodat ze niet per ongeluk kunnen worden doorgevoerd in een opslagplaats met broncode.
  • Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromen voor meer informatie.

Standaard wordt de configuratiebron voor gebruikersgeheimen geregistreerd na de JSON-configuratiebronnen. Daarom hebben gebruikersgeheimsleutels voorrang op sleutels in appsettings.json en appsettings.{Environment}.json.

Voor meer informatie over het opslaan van wachtwoorden of andere gevoelige gegevens:

Azure Key Vault slaat app-geheimen veilig op voor ASP.NET Core-apps. Zie de Azure Key Vault-configuratieprovider in ASP.NET Core voor meer informatie.

Omgevingsvariabelen zonder voorvoegsel

Omgevingsvariabelen zonder voorvoegsel zijn andere omgevingsvariabelen dan omgevingsvariabelen die zijn voorafgegaan door ASPNETCORE_ of DOTNET_. Bijvoorbeeld, de sjablonen voor ASP.NET Core-webtoepassingen stellen "ASPNETCORE_ENVIRONMENT": "Development" in launchSettings.json in. Zie voor meer informatie over ASPNETCORE_ en DOTNET_ omgevingsvariabelen:

Met behulp van de standaardconfiguratie laadt de EnvironmentVariablesConfigurationProvider configuratie van sleutel-waardeparen van de omgevingsvariabele na het lezenappsettings.jsonappsettings.{Environment}.json, en gebruikersgeheimen. Sleutelwaarden die uit de omgeving worden gelezen, overschrijven daarom waarden uit appsettings.json, appsettings.{Environment}.json en gebruikersgeheimen.

Het :-scheidingsteken werkt niet met hiërarchische sleutels van omgevingsvariabelen op alle platformen. Het :-scheidingsteken wordt bijvoorbeeld niet ondersteund door Bash. Het dubbele onderstrepingsteken, __, is:

  • Ondersteund door alle platforms.
  • Automatisch vervangen door dubbelpunt, :.

De volgende set opdrachten:

  • Stel de omgevingssleutels en -waarden in van het voorgaande voorbeeld in Windows.
  • Test de instellingen bij het gebruik van het voorbeelddownload. De dotnet run opdracht moet worden uitgevoerd in de projectmap.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

De voorgaande omgevingsinstellingen:

  • Worden alleen ingesteld in processen die zijn gestart vanuit het opdrachtvenster waarin ze zijn ingesteld.
  • Wordt niet gelezen door browsers die zijn gestart met Visual Studio.

De volgende setx-opdrachten kunnen worden gebruikt om de omgevingssleutels en -waarden in Windows in te stellen. In tegenstelling tot set, setx instellingen blijven behouden. /M stelt de variabele in de systeemomgeving in. Als de /M switch niet wordt gebruikt, wordt een gebruikersomgevingsvariabele ingesteld.

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

Testen of de voorgaande opdrachten appsettings.json en appsettings.{Environment}.json overschrijven:

  • Met Visual Studio: Visual Studio afsluiten en opnieuw starten.
  • Met de CLI: Start een nieuw opdrachtvenster en voer dit in dotnet run.

Roep AddEnvironmentVariables een tekenreeks aan om een voorvoegsel voor omgevingsvariabelen op te geven:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

In de voorgaande code:

Het voorvoegsel wordt verwijderd wanneer de configuratiesleutel-waardeparen worden gelezen.

Met de volgende opdrachten wordt het aangepaste voorvoegsel getest:

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

De standaardconfiguratie laadt omgevingsvariabelen en opdrachtregelargumenten voorafgegaan door DOTNET_ en ASPNETCORE_. De DOTNET_ en ASPNETCORE_ voorvoegsels worden gebruikt door ASP.NET Core voor host- en app-configuratie, maar niet voor gebruikersconfiguratie. Zie .NET Generic Host voor meer informatie over host- en app-configuratie.

Selecteer op Azure-app Service de optie Nieuwe toepassingsinstelling Azure-app servicetoepassingsinstellingen zijn:

  • Versleuteld at-rest en verzonden via een versleuteld kanaal.
  • Weergegeven als omgevingsvariabelen.

Zie Azure Apps: App-configuratie overschrijven met behulp van Azure Portal voor meer informatie.

Zie verbindingsreeksvoorvoegsels voor informatie over Verbindingsreeksen in Azure Database.

Naamgeving van omgevingsvariabelen

Namen van omgevingsvariabelen weerspiegelen de structuur van een appsettings.json bestand. Elk element in de hiërarchie wordt gescheiden door een dubbele onderstrepingsteken (bij voorkeur) of een dubbele punt. Wanneer de elementstructuur een matrix bevat, moet de matrixindex worden behandeld als een extra elementnaam in dit pad. Houd rekening met het volgende appsettings.json bestand en de bijbehorende equivalente waarden die worden weergegeven als omgevingsvariabelen.

appsettings.json

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

Omgevingsvariabelen

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

Omgevingsvariabelen die zijn ingesteld in gegenereerde launchSettings.json

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving. De ASP.NET Core-websjablonen genereren bijvoorbeeld een launchSettings.json bestand waarmee de eindpuntconfiguratie wordt ingesteld op:

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

Door de applicationUrl te configureren, wordt de ASPNETCORE_URLS omgevingsvariabele ingesteld en worden waarden in de omgeving overschreven.

Omgevingsvariabelen ontsnappen in Linux

Op Linux moeten de waarden van URL-omgevingsvariabelen worden geëscaped zodat systemd deze kan parsen. Gebruik de Linux-tool systemd-escape die http:--localhost:5001 oplevert

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

Omgevingsvariabelen weergeven

In de volgende code worden de omgevingsvariabelen en -waarden weergegeven bij het opstarten van toepassingen. Dit kan handig zijn bij het opsporen van fouten in de omgevingsinstellingen:

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

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

Opdrachtregel

Met behulp van de standaardconfiguratie laadt de CommandLineConfigurationProvider de configuratie, van sleutel-waardekoppels van opdrachtregelargumenten, na de volgende configuratiebronnen:

  • appsettings.json en appsettings.{Environment}.json bestanden.
  • App-geheimen in de ontwikkelomgeving.
  • Omgevingsvariabelen.

Standaard worden configuratiewaarden die zijn ingesteld op de opdrachtregel configuratiewaarden vervangen die zijn ingesteld bij alle andere configuratieproviders.

Opdrachtregelargumenten

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van =:

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

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van /:

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

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van --:

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

De sleutelwaarde:

  • Moet volgen =of de sleutel moet een voorvoegsel hebben van -- of / wanneer de waarde een spatie volgt.
  • Is niet vereist als = deze wordt gebruikt. Bijvoorbeeld: MySetting=.

Combineer binnen dezelfde opdracht geen sleutel-waardeparen met opdrachtregelargumenten die worden gebruikt = met sleutel-waardeparen die gebruikmaken van een spatie.

Switchtoewijzingen

Schakelmappingen staan vervangingslogica voor sleutelnamen toe. Geef een woordenlijst op met switchvervangingen voor de AddCommandLine methode.

Wanneer het woordenboek voor switchtoewijzingen wordt gebruikt, wordt het woordenboek gecontroleerd op een sleutel die overeenkomt met de sleutel die door een opdrachtregelargument wordt geleverd. Als de opdrachtregelsleutel wordt gevonden in de woordenlijst, wordt de waarde van de woordenlijst teruggegeven om het sleutel-waardepaar in te stellen in de configuratie van de app. Een switchtoewijzing is vereist voor elke opdrachtregelsleutel die wordt voorafgegaan door één streepje (-).

Regels voor sleutels van schakelmappings in woordenboeken:

  • Schakelopties moeten beginnen met - of --.
  • De woordenlijst voor switchtoewijzingen mag geen dubbele sleutels bevatten.

Als u een woordenlijst voor switchtoewijzingen wilt gebruiken, geeft u deze door bij de aanroep van 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();

Voer de volgende opdracht uit om de sleutelvervanging te testen:

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

De volgende code toont de sleutelwaarden voor de vervangen sleutels:

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

Voor apps die switchtoewijzingen gebruiken, mag de aanroep geen argumenten doorgeven. De CreateDefaultBuilder aanroep van AddCommandLine de methode bevat geen toegewezen switches en er is geen manier om de woordenlijst voor switchtoewijzing door te geven aan CreateDefaultBuilder. De oplossing is niet om de argumenten door te geven aanCreateDefaultBuilder, maar in plaats daarvan de methode van AddCommandLine de ConfigurationBuilder methode toe te staan zowel de argumenten als de woordenlijst voor switchtoewijzing te verwerken.

Omgevings- en opdrachtregelargumenten instellen met Visual Studio

Omgevings- en opdrachtregelargumenten kunnen in Visual Studio worden ingesteld vanuit het dialoogvenster Opstartprofielen:

  • Klik in Solution Explorer met de rechtermuisknop op het project en selecteer Eigenschappen.
  • Selecteer het tabblad Foutopsporings > algemeen en selecteer de gebruikersinterface voor het openen van startprofielen voor foutopsporing.

Hiërarchische configuratiegegevens

De configuratie-API leest hiërarchische configuratiegegevens door de hiërarchische gegevens plat te maken met behulp van een scheidingsteken in de configuratiesleutels.

Het voorbeelddownload bevat het volgende appsettings.json bestand:

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

In de volgende code van het voorbeelddownload worden verschillende configuratie-instellingen weergegeven:

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

De voorkeursmethode voor het lezen van hiërarchische configuratiegegevens is het gebruik van het optiespatroon. Zie Hiërarchische bindingsconfiguratiegegevens in dit document voor meer informatie.

GetSection en GetChildren methoden zijn beschikbaar om secties en onderliggende elementen van een sectie in de configuratiegegevens te isoleren. Deze methoden worden verderop beschreven in GetSection, GetChildren en Exists.

Configuratiesleutels en -waarden

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

Configuratiesleutels:

  • Zijn niet hoofdlettergevoelig. ConnectionString en connectionstring worden bijvoorbeeld behandeld als gelijkwaardige sleutels.
  • Als een sleutel en waarde zijn ingesteld in meer dan één configuratieprovider, wordt de waarde van de laatste toegevoegde provider gebruikt. Zie De standaardconfiguratie voor meer informatie.
  • Hiërarchische sleutels
    • Binnen de configuratie-API werkt een dubbele puntscheidingsteken (:) op alle platforms.
    • In omgevingsvariabelen werkt een dubbele punt als scheidingsteken mogelijk niet op alle platforms. Een dubbele onderstrepingsteken, __, wordt ondersteund door alle platforms en wordt automatisch omgezet naar een dubbelpunt :.
    • In Azure Key Vault gebruiken hiërarchische sleutels -- als scheidingsteken. De Azure Key Vault-configuratieprovider vervangt automatisch -- door een : wanneer de geheimen in de configuratie van de app worden geladen.
  • De ConfigurationBinder functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Matrixbinding wordt beschreven in de matrix binden aan een klassesectie .

Configuratiewaarden:

  • Dit zijn tekenreeksen.
  • Null-waarden kunnen niet worden opgeslagen in de configuratie of gebonden aan objecten.

Configuratieproviders

In de volgende tabel ziet u de configuratieproviders die beschikbaar zijn voor ASP.NET Core-apps.

Aanbieder Zorgt voor configuratie vanuit
Azure Key Vault-configuratieprovider Azure Key Vault
Azure-app-configuratieprovider Azure App Configuration (Configuratie van Azure-apps)
Commandoregelconfiguratieprovider Opdrachtregelparameters
aangepaste configuratieprovider Aangepaste bron
configuratieprovider voor omgevingsvariabelen Omgevingsvariabelen
bestandsconfiguratieprovider INI-, JSON- en XML-bestanden
nl-NL: Sleutel-per-bestand-configuratieprovider Directorybestanden
geheugenconfiguratieprovider Verzamelingen in het geheugen
Gebruikersgeheimen Het bestand in de gebruikersprofielmap

Configuratiebronnen worden gelezen in de volgorde waarin hun configuratieproviders worden opgegeven. Rangschik configuratieproviders in de code volgens de prioriteiten voor de configuratiebronnen die de app nodig heeft.

Een typische reeks configuratieproviders is:

  1. appsettings.json
  2. appsettings.{Environment}.json
  3. Gebruikersgeheimen
  4. Omgevingsvariabelen met behulp van de configuratieprovider Omgevingsvariabelen .
  5. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.

Een veelvoorkomende procedure is om de opdrachtregelconfiguratieprovider voor het laatst toe te voegen in een reeks providers om opdrachtregelargumenten toe te staan om de configuratie die door de andere providers is ingesteld, te overschrijven.

De voorgaande reeks providers wordt gebruikt in de standaardconfiguratie.

Verbindingsreeksvoorvoegsels

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

De configuratie-API heeft speciale verwerkingsregels voor vier verbindingsreeks omgevingsvariabelen. Deze verbindingsreeks zijn betrokken bij het configureren van Azure-verbindingsreeks s voor de app-omgeving. Omgevingsvariabelen met de voorvoegsels die in de tabel worden weergegeven, worden in de app geladen met de standaardconfiguratie of wanneer er geen voorvoegsel wordt opgegeven aan AddEnvironmentVariables.

Verbindingsreeksvoorvoegsel Aanbieder
CUSTOMCONNSTR_ Aangepaste leverancier
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

Wanneer een omgevingsvariabele wordt gedetecteerd en in de configuratie wordt geladen met een van de vier voorvoegsels die in de tabel worden weergegeven:

  • De configuratiesleutel wordt gemaakt door het voorvoegsel van de omgevingsvariabele te verwijderen en een sectie met een configuratiesleutel (ConnectionStrings) toe te voegen.
  • Er wordt een nieuw sleutel-waardepaar voor de configuratie gemaakt dat de databaseverbindingsprovider vertegenwoordigt (met uitzondering van CUSTOMCONNSTR_, waarvoor geen vermelde provider is opgegeven).
Sleutel voor omgevingsvariabele Geconverteerde configuratiesleutel Providerconfiguratie-vermelding
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Configuratievermelding niet gemaakt.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: System.Data.SqlClient

Bestandsconfiguratieprovider

FileConfigurationProvider is de basisklasse voor het laden van de configuratie van het bestandssysteem. De volgende configuratieproviders zijn afgeleid van FileConfigurationProvider:

INI-configuratieprovider

De IniConfigurationProvider laadt tijdens runtime configuratie vanuit INI-bestandssleutel-waardeparen.

Met de volgende code worden verschillende configuratieproviders toegevoegd:

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

In de voorgaande code worden instellingen in de MyIniConfig.ini en MyIniConfig.{Environment}.ini bestanden overschreven door instellingen in de:

Het voorbeelddownload bevat het volgende MyIniConfig.ini bestand:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

De JsonConfigurationProvider laadt de configuratie vanuit de sleutel-waardeparen van het JSON-bestand.

Overbelastingen kunnen het volgende opgeven:

  • Of het bestand optioneel is.
  • Of de configuratie opnieuw wordt geladen als het bestand wordt gewijzigd.

Houd rekening met de volgende code:

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

De voorgaande code:

  • Hiermee configureert u de JSON-configuratieprovider om het MyConfig.json bestand te laden met de volgende opties:
    • optional: true: Het bestand is optioneel.
    • reloadOnChange: true : het bestand wordt opnieuw geladen wanneer wijzigingen worden opgeslagen.
  • Leest de standaardconfiguratieproviders vóór het MyConfig.json bestand. Instellingen in de MyConfig.json instelling voor het overschrijven van bestanden in de standaardconfiguratieproviders, waaronder de configuratieprovider voor omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

Normaal gesproken wilt u geen aangepast JSON-bestand dat waarden overschrijft die zijn ingesteld in de configuratieprovider omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

XML-configuratieprovider

De XmlConfigurationProvider configuratie wordt tijdens runtime geladen van sleutel-waardeparen van XML-bestanden.

Met de volgende code worden verschillende configuratieproviders toegevoegd:

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

In de voorgaande code worden instellingen in de MyXMLFile.xml en MyXMLFile.{Environment}.xml bestanden overschreven door instellingen in de:

Het voorbeelddownload bevat het volgende MyXMLFile.xml bestand:

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

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

Herhalende elementen die dezelfde elementnaam gebruiken, werken als het name kenmerk wordt gebruikt om de elementen te onderscheiden:

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

De volgende code leest het vorige configuratiebestand en geeft de sleutels en waarden weer:

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

Kenmerken kunnen worden gebruikt om waarden op te geven:

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

In het vorige configuratiebestand worden de volgende sleutels geladen met value:

  • key:attribute
  • section:key:attribute

Configuratieprovider voor sleutel per bestand

De KeyPerFileConfigurationProvider map maakt gebruik van de bestanden van een map als configuratiesleutel-waardeparen. De sleutel is de bestandsnaam. De waarde bevat de inhoud van het bestand. De key-per-file-configuratieprovider wordt gebruikt in Docker-hostingscenario's.

Als u key-per-file-configuratie wilt activeren, roept u de AddKeyPerFile extensiemethode aan op een exemplaar van ConfigurationBuilder. De directoryPath bestanden moeten een absoluut pad zijn.

Overbelastingen maken het opgeven van:

  • Een Action<KeyPerFileConfigurationSource> gemachtigde die de bron configureert.
  • Of de map optioneel is en of het pad naar de map is.

Het dubbele onderstrepingsteken (__) wordt gebruikt als scheidingsteken voor configuratiesleutels in bestandsnamen. De bestandsnaam Logging__LogLevel__System produceert bijvoorbeeld de configuratiesleutel Logging:LogLevel:System.

Aanroepen ConfigureAppConfiguration bij het bouwen van de host om de configuratie van de app op te geven:

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

Geheugenconfiguratieprovider

Hierbij MemoryConfigurationProvider wordt een verzameling in het geheugen gebruikt als configuratiesleutel-waardeparen.

Met de volgende code wordt een geheugenverzameling toegevoegd aan het configuratiesysteem:

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

In de volgende code van het voorbeelddownload worden de voorgaande configuratie-instellingen weergegeven:

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

In de voorgaande code config.AddInMemoryCollection(Dict) wordt deze toegevoegd na de standaardconfiguratieproviders. Zie JSON-configuratieprovider voor een voorbeeld van het ordenen van de configuratieprovider.

Zie Een matrix binden voor een ander voorbeeld met behulp van MemoryConfigurationProvider.

Kestrel eindpuntconfiguratie

Kestrel specifieke eindpuntconfiguratie overschrijft alle serveroverschrijdende eindpuntconfiguraties. Configuraties voor eindpunten tussen servers zijn onder andere:

Houd rekening met het volgende appsettings.json bestand dat wordt gebruikt in een ASP.NET Core-web-app:

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

Wanneer de voorgaande gemarkeerde markering wordt gebruikt in een ASP.NET Core-web-app en de app wordt gestart op de opdrachtregel met de volgende server-overschrijdende eindpuntconfiguratie:

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

Kestrel verbindt met het eindpunt dat specifiek is geconfigureerd voor Kestrel in het appsettings.json bestand (https://localhost:9999) en niet https://localhost:7777.

Overweeg het Kestrel specifieke eindpunt dat is geconfigureerd als een omgevingsvariabele:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

In de voorgaande omgevingsvariabele Https is dit de naam van het Kestrel specifieke eindpunt. Het voorgaande appsettings.json bestand definieert ook een specifiek eindpunt met de Kestrel naam Https. Standaard wordt de omgevingsvariabele die gebruikmaakt van de configuratieprovider Omgevingsvariabelen gelezen nadat appsettings.{Environment}.json, daarom wordt de voorgaande omgevingsvariabele gebruikt voor het Https eindpunt.

WaardeOphalen

ConfigurationBinder.GetValue extraheert één waarde uit de configuratie met een opgegeven sleutel en converteert deze naar het opgegeven type:

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

In de voorgaande code, als NumberKey niet in de configuratie wordt gevonden, wordt de standaardwaarde 99 gebruikt.

GetSection, GetChildren en Exists

Bekijk het volgende MySubsection.json bestand voor de volgende voorbeelden:

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

De volgende code voegt MySubsection.json toe aan de configuratieproviders:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection retourneert een configuratiesubsectie met de opgegeven subsectiesleutel.

De volgende code retourneert waarden voor 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"]}'");
    }
}

De volgende code retourneert waarden voor 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 keert nullnooit terug. Als er geen overeenkomende sectie wordt gevonden, wordt een lege IConfigurationSection sectie geretourneerd.

Wanneer GetSection een overeenkomende sectie retourneert, wordt Value niet ingevuld. Key en Path worden geretourneerd wanneer de sectie bestaat.

GetChildren and Exists

De volgende code roept IConfiguration.GetChildren waarden aan en retourneert waarden voor 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);
    }
}

De voorgaande code aanroepen ConfigurationExtensions.Exists om te controleren of de sectie bestaat:

Een matrix binden

De ConfigurationBinder.Bind functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Elke matrixindeling die een numeriek sleutelsegment beschikbaar maakt, kan matrixbindingen uitvoeren op een POCO-klassematrix .

Houd rekening met MyArray.json uit de voorbeeld-download:

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

De volgende code voegt MyArray.json toe aan de configuratieproviders:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Met de volgende code wordt de configuratie gelezen en worden de waarden weergegeven:

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

De voorgaande code retourneert de volgende uitvoer:

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

In de voorgaande uitvoer heeft Index 3 een waarde value40die overeenkomt met "4": "value40", in MyArray.json. De afhankelijke matrixindexen zijn doorlopend en zijn niet gebonden aan de configuratiesleutelindex. De configuratiebinding kan geen null-waarden binden of null-vermeldingen maken in afhankelijke objecten.

Aangepaste configuratieprovider

De voorbeeld-app laat zien hoe u een eenvoudige configuratieprovider maakt die configuratiesleutel-waardeparen van een database leest met behulp van Entity Framework (EF).

De provider heeft de volgende kenmerken:

  • De EF-database in het geheugen wordt gebruikt voor demonstratiedoeleinden. Als u een database wilt gebruiken waarvoor een verbindingsreeks is vereist, implementeert u een secundaire ConfigurationBuilder om de verbindingsreeks van een andere configuratieprovider op te geven.
  • De provider leest een databasetabel in de configuratie bij het opstarten. De provider doorzoekt de database niet per sleutel.
  • Reload-on-change is niet geïmplementeerd, dus het bijwerken van de database nadat de app is gestart, heeft geen invloed op de configuratie van de app.

Definieer een EFConfigurationValue entiteit voor het opslaan van configuratiewaarden in de database.

Models/EFConfigurationValue.cs:

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

Voeg een EFConfigurationContext toe om de geconfigureerde waarden op te slaan en te openen.

EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Maak een klasse die IConfigurationSource implementeert.

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

Maak de aangepaste configuratieprovider door deze over te nemen van ConfigurationProvider. De configuratieprovider initialiseert de database wanneer deze leeg is. Omdat configuratiesleutels niet hoofdlettergevoelig zijn, wordt de woordenlijst die wordt gebruikt om de database te initialiseren gemaakt met de niet-hoofdlettergevoelige vergelijking (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;
    }
}

Met een AddEFConfiguration extensiemethode kan de configuratiebron worden toegevoegd aan een ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

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

De volgende code laat zien hoe u de aangepaste EFConfigurationProvider code gebruikt in Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Toegangsconfiguratie met afhankelijkheidsinjectie (DI)

Configuratie kan worden geïnjecteerd in services met behulp van afhankelijkheidsinjectie (DI) door de service IConfiguration op te lossen.

public class Service
{
    private readonly IConfiguration _config;

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

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

        // ...
    }
}

Zie voor informatie over hoe u waarden kunt benaderen met behulp van IConfiguration, GetValue en GetSection, GetChildren en Exists in dit artikel.

Configuratie voor toegang in Razor Pagina's

De volgende code geeft configuratiegegevens weer op een Razor pagina:

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

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

In de volgende code MyOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

In de volgende markeringen wordt de @injectRazor instructie gebruikt om de waarde van de opties op te lossen en weer te geven:

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

Toegangsconfiguratie in een MVC-weergavebestand

De volgende code geeft configuratiegegevens weer in een MVC-weergave:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Toegangsconfiguratie in Program.cs

De volgende code heeft toegang tot de configuratie in het Program.cs bestand.

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

In appsettings.json het voorgaande voorbeeld:

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

Opties configureren met een gemachtigde

Opties die zijn geconfigureerd in een delegaat, overschrijven waarden die zijn ingesteld in de configuratieproviders.

In de volgende code wordt een IConfigureOptions<TOptions> service toegevoegd aan de servicecontainer. Er wordt een gemachtigde gebruikt om waarden te configureren voor 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();

In de volgende code worden de optieswaarden weergegeven:

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

In het voorgaande voorbeeld worden de waarden van Option1 en Option2 opgegeven in appsettings.json en vervolgens overschreven door de geconfigureerde gemachtigde.

Host versus app-configuratie

Voordat de app is geconfigureerd en gestart, wordt een host geconfigureerd en gestart. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. Zowel de app als de host worden geconfigureerd met behulp van de configuratieproviders die in dit onderwerp worden beschreven. Hostconfiguratiesleutel-waardeparen worden ook opgenomen in de configuratie van de app. Zie voor meer informatie over hoe de configuratieproviders worden gebruikt wanneer de host wordt gebouwd en hoe configuratiebronnen van invloed zijn op de hostconfiguratie ASP.NET overzicht van basisbeginselen.

Standaardhostconfiguratie

Zie de ASP.NET Core 2.2-versie van dit onderwerp voor meer informatie over de standaardconfiguratie wanneer u de webhost gebruikt.

  • Hostconfiguratie wordt geleverd van:
  • De standaardconfiguratie van de webhost is ingesteld (ConfigureWebHostDefaults):
    • Kestrel wordt gebruikt als de webserver en geconfigureerd met behulp van de configuratieproviders van de app.
    • Voeg middleware voor het filteren van hosts toe.
    • Voeg Forwarded Headers-middleware toe als de ASPNETCORE_FORWARDEDHEADERS_ENABLED omgevingsvariabele is gesteld op true.
    • IIS-integratie inschakelen.

Andere configuratie

Dit onderwerp heeft alleen betrekking op app-configuratie. Andere aspecten van het uitvoeren en hosten van ASP.NET Core-apps worden geconfigureerd met behulp van configuratiebestanden die niet in dit onderwerp worden behandeld:

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving.

Zie Configuratie migreren naar ASP.NET Core voor meer informatie over het migreren van app-configuratie van eerdere versies van ASP.NET.

Configuratie toevoegen vanuit een externe assembly

Met een IHostingStartup-implementatie kunt u verbeteringen aan een app toevoegen bij het opstarten vanuit een externe assembly buiten de Startup klasse van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Aanvullende bronnen

Toepassingsconfiguratie in ASP.NET Core wordt uitgevoerd met behulp van een of meer configuratieproviders. Configuratieproviders lezen configuratiegegevens van sleutel-waardeparen met behulp van verschillende configuratiebronnen:

  • Instellingenbestanden, zoals appsettings.json
  • Omgevingsvariabelen
  • Azure Key Vault
  • Azure App Configuration (Configuratie van Azure-apps)
  • Opdrachtregelargumenten
  • Aangepaste providers, geïnstalleerd of gemaakt
  • Directorybestanden
  • .NET-objecten in het geheugen

Dit artikel bevat informatie over de configuratie in ASP.NET Core. Zie .NET-configuratie voor meer informatie over het gebruik van configuratie in console-apps.

Toepassings- en hostconfiguratie

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. De ASP.NET Core-sjablonen maken een WebApplicationBuilder sjabloon die de host bevat. Hoewel sommige configuraties kunnen worden uitgevoerd in zowel de host als de toepassingsconfiguratieproviders, moet doorgaans alleen de configuratie die nodig is voor de host worden uitgevoerd in de hostconfiguratie.

Toepassingsconfiguratie is de hoogste prioriteit en wordt in de volgende sectie beschreven. Hostconfiguratie volgt de toepassingsconfiguratie en wordt beschreven in dit artikel.

Standaardbronnen voor toepassingsconfiguratie

ASP.NET Core-web-apps die zijn gemaakt met dotnet nieuwe of Visual Studio genereren de volgende code:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder-klasse met vooraf geconfigureerde standaardwaarden. De geïnitialiseerde WebApplicationBuilder (builder) biedt standaardconfiguratie voor de app in de volgende volgorde, van hoogste naar laagste prioriteit:

  1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.
  2. Omgevingsvariabelen zonder voorvoegsel met behulp van de configuratieprovider voor omgevingsvariabelen zonder voorvoegsel.
  3. Gebruikersgeheimen wanneer de app draait in de Development-omgeving.
  4. appsettings.{Environment}.json met behulp van de JSON-configuratieprovider. Bijvoorbeeld appsettings.Production.json en appsettings.Development.json.
  5. appsettings.json met de JSON-configuratieprovider.
  6. Een terugval naar de hostconfiguratie die wordt beschreven in de volgende sectie.

Standaardhostconfiguratiebronnen

De volgende lijst bevat de standaardhostconfiguratiebronnen van hoogste naar laagste prioriteit:

  1. Omgevingsvariabelen die beginnen met ASPNETCORE_ met behulp van de configuratieprovider voor omgevingsvariabelen.
  2. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider
  3. Omgevingsvariabelen die beginnen met DOTNET_ met behulp van de configuratieprovider voor omgevingsvariabelen.

Wanneer een configuratiewaarde is ingesteld in de host- en toepassingsconfiguratie, wordt de toepassingsconfiguratie gebruikt.

Zie Uitleg in deze GitHub-opmerking voor een uitleg van waarom in hostconfiguratie, ASPNETCORE_ voorvoegsel omgevingsvariabelen een hogere prioriteit hebben dan opdrachtregelargumenten.

Hostvariabelen

De volgende variabelen worden vroeg vergrendeld bij het initialiseren van de hostbuilders en kunnen niet worden beïnvloed door de configuratie van de toepassing:

Elke andere hostinstelling wordt gelezen uit de configuratie van de toepassing in plaats van de hostconfiguratie.

URLS is een van de vele algemene hostinstellingen die geen bootstrap-instelling is. Net als elke andere hostinstelling die niet in de vorige lijst staat, URLS wordt deze later gelezen uit de configuratie van de toepassing. Hostconfiguratie is een terugval voor toepassingsconfiguratie, dus hostconfiguratie kan worden gebruikt om in te stellen URLS, maar deze wordt overschreven door elke configuratiebron in de configuratie van de toepassing, zoals appsettings.json.

Zie De hoofdmap, app-naam en omgeving van deinhoud wijzigen en de inhoudshoofdmap, app-naam en omgeving wijzigen op omgevingsvariabelen of opdrachtregel voor meer informatie

De overige secties in dit artikel verwijzen naar toepassingsconfiguratie.

Toepassingsconfiguratieproviders

De volgende code geeft de ingeschakelde configuratieproviders weer in de volgorde waarin ze zijn toegevoegd:

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

In de voorgaande lijst met standaardconfiguratiebronnen met de hoogste tot laagste prioriteit worden de providers weergegeven in de tegenovergestelde volgorde waarin ze worden toegevoegd aan de door de sjabloon gegenereerde toepassing. De JSON-configuratieprovider wordt bijvoorbeeld toegevoegd vóór de opdrachtregelconfiguratieprovider.

Configuratieproviders die later worden toegevoegd, hebben een hogere prioriteit en overschrijven eerdere sleutelinstellingen. Als MyKey is ingesteld in zowel appsettings.json als in de omgeving, wordt de waarde van de omgeving gebruikt. Met behulp van de standaardconfiguratieproviders overschrijft de opdrachtregelconfiguratieprovider alle andere providers.

Zie Instellingen voor standaardbouwer voor meer informatieCreateBuilder.

appsettings.json

Houd rekening met het volgende appsettings.json bestand:

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

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

De standaardconfiguratie JsonConfigurationProvider wordt geladen in de volgende volgorde:

  1. appsettings.json
  2. appsettings.{Environment}.json : bijvoorbeeld de appsettings.Production.json en appsettings.Development.json bestanden. De omgevingsversie van het bestand wordt geladen op basis van de IHostingEnvironment.EnvironmentName. Zie Meerdere omgevingen gebruiken in ASP.NET Core voor meer informatie.

appsettings.{Environment}.json waarden overschrijven sleutels in appsettings.json. Bijvoorbeeld, standaard:

  • Tijdens ontwikkeling overschrijft appsettings.Development.json configuratiewaarden in appsettings.json.
  • In productie overschrijft appsettings.Production.json configuratie de waarden in appsettings.json. Bijvoorbeeld bij het implementeren van de app in Azure.

Als een configuratiewaarde moet worden gegarandeerd, raadpleegt u GetValue. In het voorgaande voorbeeld worden alleen tekenreeksen gelezen en wordt geen standaardwaarde ondersteund.

Met behulp van de standaardconfiguratie worden de appsettings.json en appsettings.{Environment}.json bestanden ingeschakeld met reloadOnChange: true. Wijzigingen die zijn aangebracht in het appsettings.json bestand en het appsettings.{Environment}.json bestand nadat de app gestart is, worden gelezen door JSON-configuratieprovider.

Hiërarchische configuratiegegevens binden met behulp van het optiespatroon

De voorkeursmethode voor het lezen van gerelateerde configuratiewaarden is het gebruik van het patroon opties. Bijvoorbeeld om de volgende configuratiewaarden te lezen:

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

Maak de volgende PositionOptions klasse:

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

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

Een opties klasse:

  • Moet niet-abstract zijn met een openbare parameterloze constructor.
  • Alle openbare lees-schrijfeigenschappen van het type zijn gebonden.
  • Velden zijn niet gebonden. In de voorgaande code, Position is niet gebonden. Het Position veld wordt gebruikt, zodat de tekenreeks "Position" niet hard gecodeerd hoeft te worden in de app wanneer de klasse aan een configuratieprovider wordt gekoppeld.

De volgende code:

  • Roept ConfigurationBinder.Bind aan om de PositionOptions klasse aan de Position sectie te binden.
  • Geeft de Position configuratiegegevens weer.
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}");
    }
}

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand standaard gelezen nadat de app is gestart.

ConfigurationBinder.Get<T> bindt en retourneert het opgegeven type. ConfigurationBinder.Get<T>kan handiger zijn dan het gebruik.ConfigurationBinder.Bind De volgende code laat zien hoe u deze kunt gebruiken ConfigurationBinder.Get<T> met de PositionOptions klasse:

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

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand standaard gelezen nadat de app is gestart.

Een alternatieve benadering bij het gebruik van het optiepatroon is om de Position sectie te binden en toe te voegen aan de afhankelijkheidsinjectieservicecontainer. In de volgende code PositionOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Met behulp van de voorgaande code leest de volgende code de positieopties:

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

In de voorgaande code worden wijzigingen in het JSON-configuratiebestand nadat de app is gestart, niet gelezen. Als u wijzigingen wilt lezen nadat de app is gestart, gebruikt u IOptionsSnapshot.

Met behulp van de standaardconfiguratie worden de appsettings.json en appsettings.{Environment}.json bestanden ingeschakeld met reloadOnChange: true. Wijzigingen die zijn aangebracht in het appsettings.json bestand en het appsettings.{Environment}.json bestand nadat de app gestart is, worden gelezen door JSON-configuratieprovider.

Zie de JSON-configuratieprovider in dit document voor informatie over het toevoegen van extra JSON-configuratiebestanden.

Serviceverzameling combineren

Houd rekening met het volgende waarmee services worden geregistreerd en opties worden geconfigureerd:

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

Gerelateerde groepen registraties kunnen worden verplaatst naar een extensiemethode om services te registreren. De configuratieservices worden bijvoorbeeld toegevoegd aan de volgende klasse:

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 resterende services worden geregistreerd in een vergelijkbare klasse. De volgende code maakt gebruik van de nieuwe extensiemethoden om de services te registreren:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Opmerking: Elke services.Add{GROUP_NAME} extensiemethode voegt services toe en configureert deze mogelijk. AddControllersWithViews voegt bijvoorbeeld de services toe die vereist zijn door MVC-controllers met weergaven, en AddRazorPages voegt de services toe die vereist zijn door Razor Pagina's.

Beveiligings- en gebruikersgeheimen

Richtlijnen voor configuratiegegevens:

  • Sla nooit wachtwoorden of andere gevoelige gegevens op in configuratieprovidercode of in configuratiebestanden met tekst zonder opmaak. Het hulpprogramma Secret Manager kan worden gebruikt om geheimen voor ontwikkelingsdoeleinden op te slaan.
  • Gebruik geen productiegeheimen in ontwikkel- of testomgevingen.
  • Geef geheimen buiten het project op, zodat ze niet per ongeluk kunnen worden doorgevoerd in een opslagplaats met broncode.
  • Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromen voor meer informatie.

Standaard wordt de configuratiebron voor gebruikersgeheimen geregistreerd na de JSON-configuratiebronnen. Daarom hebben gebruikersgeheimsleutels voorrang op sleutels in appsettings.json en appsettings.{Environment}.json.

Voor meer informatie over het opslaan van wachtwoorden of andere gevoelige gegevens:

Azure Key Vault slaat app-geheimen veilig op voor ASP.NET Core-apps. Zie de Azure Key Vault-configuratieprovider in ASP.NET Core voor meer informatie.

Omgevingsvariabelen zonder voorvoegsel

Omgevingsvariabelen zonder voorvoegsel zijn andere omgevingsvariabelen dan omgevingsvariabelen die zijn voorafgegaan door ASPNETCORE_ of DOTNET_. Bijvoorbeeld, de sjablonen voor ASP.NET Core-webtoepassingen stellen "ASPNETCORE_ENVIRONMENT": "Development" in launchSettings.json in. Zie voor meer informatie over ASPNETCORE_ en DOTNET_ omgevingsvariabelen:

Met behulp van de standaardconfiguratie laadt de EnvironmentVariablesConfigurationProvider configuratie van sleutel-waardeparen van de omgevingsvariabele na het lezenappsettings.jsonappsettings.{Environment}.json, en gebruikersgeheimen. Sleutelwaarden die uit de omgeving worden gelezen, overschrijven daarom waarden uit appsettings.json, appsettings.{Environment}.json en gebruikersgeheimen.

Het :-scheidingsteken werkt niet met hiërarchische sleutels van omgevingsvariabelen op alle platformen. Het :-scheidingsteken wordt bijvoorbeeld niet ondersteund door Bash. Het dubbele onderstrepingsteken, __, is:

  • Ondersteund door alle platforms.
  • Automatisch vervangen door dubbelpunt, :.

De volgende set opdrachten:

  • Stel de omgevingssleutels en -waarden in van het voorgaande voorbeeld in Windows.
  • Test de instellingen bij het gebruik van het voorbeelddownload. De dotnet run opdracht moet worden uitgevoerd in de projectmap.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

De voorgaande omgevingsinstellingen:

  • Worden alleen ingesteld in processen die zijn gestart vanuit het opdrachtvenster waarin ze zijn ingesteld.
  • Wordt niet gelezen door browsers die zijn gestart met Visual Studio.

De volgende setx-opdrachten kunnen worden gebruikt om de omgevingssleutels en -waarden in Windows in te stellen. In tegenstelling tot set, setx instellingen blijven behouden. /M stelt de variabele in de systeemomgeving in. Als de /M switch niet wordt gebruikt, wordt een gebruikersomgevingsvariabele ingesteld.

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

Testen of de voorgaande opdrachten appsettings.json en appsettings.{Environment}.json overschrijven:

  • Met Visual Studio: Visual Studio afsluiten en opnieuw starten.
  • Met de CLI: Start een nieuw opdrachtvenster en voer dit in dotnet run.

Roep AddEnvironmentVariables een tekenreeks aan om een voorvoegsel voor omgevingsvariabelen op te geven:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

In de voorgaande code:

Het voorvoegsel wordt verwijderd wanneer de configuratiesleutel-waardeparen worden gelezen.

Met de volgende opdrachten wordt het aangepaste voorvoegsel getest:

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

De standaardconfiguratie laadt omgevingsvariabelen en opdrachtregelargumenten voorafgegaan door DOTNET_ en ASPNETCORE_. De DOTNET_ en ASPNETCORE_ voorvoegsels worden gebruikt door ASP.NET Core voor host- en app-configuratie, maar niet voor gebruikersconfiguratie. Zie .NET Generic Host voor meer informatie over host- en app-configuratie.

Selecteer op Azure-app Service de optie Nieuwe toepassingsinstelling Azure-app servicetoepassingsinstellingen zijn:

  • Versleuteld at-rest en verzonden via een versleuteld kanaal.
  • Weergegeven als omgevingsvariabelen.

Zie Azure Apps: App-configuratie overschrijven met behulp van Azure Portal voor meer informatie.

Zie verbindingsreeksvoorvoegsels voor informatie over Verbindingsreeksen in Azure Database.

Naamgeving van omgevingsvariabelen

Namen van omgevingsvariabelen weerspiegelen de structuur van een appsettings.json bestand. Elk element in de hiërarchie wordt gescheiden door een dubbele onderstrepingsteken (bij voorkeur) of een dubbele punt. Wanneer de elementstructuur een matrix bevat, moet de matrixindex worden behandeld als een extra elementnaam in dit pad. Houd rekening met het volgende appsettings.json bestand en de bijbehorende equivalente waarden die worden weergegeven als omgevingsvariabelen.

appsettings.json

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

Omgevingsvariabelen

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

Omgevingsvariabelen die zijn ingesteld in gegenereerde launchSettings.json

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving. De ASP.NET Core-websjablonen genereren bijvoorbeeld een launchSettings.json bestand waarmee de eindpuntconfiguratie wordt ingesteld op:

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

Door de applicationUrl te configureren, wordt de ASPNETCORE_URLS omgevingsvariabele ingesteld en worden waarden in de omgeving overschreven.

Omgevingsvariabelen ontsnappen in Linux

Op Linux moeten de waarden van URL-omgevingsvariabelen worden geëscaped zodat systemd deze kan parsen. Gebruik de Linux-tool systemd-escape die http:--localhost:5001 oplevert

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

Omgevingsvariabelen weergeven

In de volgende code worden de omgevingsvariabelen en -waarden weergegeven bij het opstarten van toepassingen. Dit kan handig zijn bij het opsporen van fouten in de omgevingsinstellingen:

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

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

Opdrachtregel

Met behulp van de standaardconfiguratie laadt de CommandLineConfigurationProvider de configuratie, van sleutel-waardekoppels van opdrachtregelargumenten, na de volgende configuratiebronnen:

  • appsettings.json en appsettings.{Environment}.json bestanden.
  • App-geheimen in de ontwikkelomgeving.
  • Omgevingsvariabelen.

Standaard worden configuratiewaarden die zijn ingesteld op de opdrachtregel configuratiewaarden vervangen die zijn ingesteld bij alle andere configuratieproviders.

Opdrachtregelargumenten

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van =:

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

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van /:

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

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van --:

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

De sleutelwaarde:

  • Moet volgen =of de sleutel moet een voorvoegsel hebben van -- of / wanneer de waarde een spatie volgt.
  • Is niet vereist als = deze wordt gebruikt. Bijvoorbeeld: MySetting=.

Combineer binnen dezelfde opdracht geen sleutel-waardeparen met opdrachtregelargumenten die worden gebruikt = met sleutel-waardeparen die gebruikmaken van een spatie.

Switchtoewijzingen

Schakelmappingen staan vervangingslogica voor sleutelnamen toe. Geef een woordenlijst op met switchvervangingen voor de AddCommandLine methode.

Wanneer het woordenboek voor switchtoewijzingen wordt gebruikt, wordt het woordenboek gecontroleerd op een sleutel die overeenkomt met de sleutel die door een opdrachtregelargument wordt geleverd. Als de opdrachtregelsleutel wordt gevonden in de woordenlijst, wordt de waarde van de woordenlijst teruggegeven om het sleutel-waardepaar in te stellen in de configuratie van de app. Een switchtoewijzing is vereist voor elke opdrachtregelsleutel die wordt voorafgegaan door één streepje (-).

Regels voor sleutels van schakelmappings in woordenboeken:

  • Schakelopties moeten beginnen met - of --.
  • De woordenlijst voor switchtoewijzingen mag geen dubbele sleutels bevatten.

Als u een woordenlijst voor switchtoewijzingen wilt gebruiken, geeft u deze door bij de aanroep van 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();

Voer de volgende opdracht uit om de sleutelvervanging te testen:

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

De volgende code toont de sleutelwaarden voor de vervangen sleutels:

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

Voor apps die switchtoewijzingen gebruiken, mag de aanroep geen argumenten doorgeven. De CreateDefaultBuilder aanroep van AddCommandLine de methode bevat geen toegewezen switches en er is geen manier om de woordenlijst voor switchtoewijzing door te geven aan CreateDefaultBuilder. De oplossing is niet om de argumenten door te geven aanCreateDefaultBuilder, maar in plaats daarvan de methode van AddCommandLine de ConfigurationBuilder methode toe te staan zowel de argumenten als de woordenlijst voor switchtoewijzing te verwerken.

Omgevings- en opdrachtregelargumenten instellen met Visual Studio

Omgevings- en opdrachtregelargumenten kunnen in Visual Studio worden ingesteld vanuit het dialoogvenster Opstartprofielen:

  • Klik in Solution Explorer met de rechtermuisknop op het project en selecteer Eigenschappen.
  • Selecteer het tabblad Foutopsporings > algemeen en selecteer de gebruikersinterface voor het openen van startprofielen voor foutopsporing.

Hiërarchische configuratiegegevens

De configuratie-API leest hiërarchische configuratiegegevens door de hiërarchische gegevens plat te maken met behulp van een scheidingsteken in de configuratiesleutels.

Het voorbeelddownload bevat het volgende appsettings.json bestand:

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

In de volgende code van het voorbeelddownload worden verschillende configuratie-instellingen weergegeven:

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

De voorkeursmethode voor het lezen van hiërarchische configuratiegegevens is het gebruik van het optiespatroon. Zie Hiërarchische bindingsconfiguratiegegevens in dit document voor meer informatie.

GetSection en GetChildren methoden zijn beschikbaar om secties en onderliggende elementen van een sectie in de configuratiegegevens te isoleren. Deze methoden worden verderop beschreven in GetSection, GetChildren en Exists.

Configuratiesleutels en -waarden

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

Configuratiesleutels:

  • Zijn niet hoofdlettergevoelig. ConnectionString en connectionstring worden bijvoorbeeld behandeld als gelijkwaardige sleutels.
  • Als een sleutel en waarde is ingesteld in meer dan één configuratieprovider, wordt de waarde van de laatste toegevoegde provider gebruikt. Zie De standaardconfiguratie voor meer informatie.
  • Hiërarchische sleutels
    • Binnen de configuratie-API werkt een dubbele puntscheidingsteken (:) op alle platforms.
    • In omgevingsvariabelen werkt een dubbele punt als scheidingsteken mogelijk niet op alle platforms. Een dubbele onderstrepingsteken, __, wordt ondersteund door alle platforms en wordt automatisch omgezet naar een dubbelpunt :.
    • In Azure Key Vault gebruiken hiërarchische sleutels -- als scheidingsteken. De Azure Key Vault-configuratieprovider vervangt automatisch -- door een : wanneer de geheimen in de configuratie van de app worden geladen.
  • De ConfigurationBinder functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Matrixbinding wordt beschreven in de matrix binden aan een klassesectie .

Configuratiewaarden:

  • Dit zijn tekenreeksen.
  • Null-waarden kunnen niet worden opgeslagen in de configuratie of gebonden aan objecten.

Configuratieproviders

In de volgende tabel ziet u de configuratieproviders die beschikbaar zijn voor ASP.NET Core-apps.

Aanbieder Zorgt voor configuratie vanuit
Azure Key Vault-configuratieprovider Azure Key Vault
Azure-app-configuratieprovider Azure App Configuration (Configuratie van Azure-apps)
Commandoregelconfiguratieprovider Opdrachtregelparameters
aangepaste configuratieprovider Aangepaste bron
configuratieprovider voor omgevingsvariabelen Omgevingsvariabelen
bestandsconfiguratieprovider INI-, JSON- en XML-bestanden
nl-NL: Sleutel-per-bestand-configuratieprovider Directorybestanden
geheugenconfiguratieprovider Verzamelingen in het geheugen
Gebruikersgeheimen Het bestand in de gebruikersprofielmap

Configuratiebronnen worden gelezen in de volgorde waarin hun configuratieproviders worden opgegeven. Rangschik configuratieproviders in de code volgens de prioriteiten voor de configuratiebronnen die de app nodig heeft.

Een typische reeks configuratieproviders is:

  1. appsettings.json
  2. appsettings.{Environment}.json
  3. Gebruikersgeheimen
  4. Omgevingsvariabelen met behulp van de configuratieprovider Omgevingsvariabelen .
  5. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.

Een veelvoorkomende procedure is om de opdrachtregelconfiguratieprovider voor het laatst toe te voegen in een reeks providers om opdrachtregelargumenten toe te staan om de configuratie die door de andere providers is ingesteld, te overschrijven.

De voorgaande reeks providers wordt gebruikt in de standaardconfiguratie.

Verbindingsreeksvoorvoegsels

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

De configuratie-API heeft speciale verwerkingsregels voor vier verbindingsreeks omgevingsvariabelen. Deze verbindingsreeks zijn betrokken bij het configureren van Azure-verbindingsreeks s voor de app-omgeving. Omgevingsvariabelen met de voorvoegsels die in de tabel worden weergegeven, worden in de app geladen met de standaardconfiguratie of wanneer er geen voorvoegsel wordt opgegeven aan AddEnvironmentVariables.

Verbindingsreeksvoorvoegsel Aanbieder
CUSTOMCONNSTR_ Aangepaste leverancier
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

Wanneer een omgevingsvariabele wordt gedetecteerd en in de configuratie wordt geladen met een van de vier voorvoegsels die in de tabel worden weergegeven:

  • De configuratiesleutel wordt gemaakt door het voorvoegsel van de omgevingsvariabele te verwijderen en een sectie met een configuratiesleutel (ConnectionStrings) toe te voegen.
  • Er wordt een nieuw sleutel-waardepaar voor de configuratie gemaakt dat de databaseverbindingsprovider vertegenwoordigt (met uitzondering van CUSTOMCONNSTR_, waarvoor geen vermelde provider is opgegeven).
Sleutel voor omgevingsvariabele Geconverteerde configuratiesleutel Providerconfiguratie-vermelding
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Configuratievermelding niet gemaakt.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Sleutel: : ConnectionStrings:{KEY}_ProviderName
Waarde: System.Data.SqlClient

Bestandsconfiguratieprovider

FileConfigurationProvider is de basisklasse voor het laden van de configuratie van het bestandssysteem. De volgende configuratieproviders zijn afgeleid van FileConfigurationProvider:

INI-configuratieprovider

De IniConfigurationProvider laadt tijdens runtime configuratie vanuit INI-bestandssleutel-waardeparen.

Met de volgende code worden verschillende configuratieproviders toegevoegd:

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

In de voorgaande code worden instellingen in de MyIniConfig.ini en MyIniConfig.{Environment}.ini bestanden overschreven door instellingen in de:

Het voorbeelddownload bevat het volgende MyIniConfig.ini bestand:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

De JsonConfigurationProvider laadt de configuratie vanuit de sleutel-waardeparen van het JSON-bestand.

Overbelastingen kunnen het volgende opgeven:

  • Of het bestand optioneel is.
  • Of de configuratie opnieuw wordt geladen als het bestand wordt gewijzigd.

Houd rekening met de volgende code:

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

De voorgaande code:

  • Hiermee configureert u de JSON-configuratieprovider om het MyConfig.json bestand te laden met de volgende opties:
    • optional: true: Het bestand is optioneel.
    • reloadOnChange: true : het bestand wordt opnieuw geladen wanneer wijzigingen worden opgeslagen.
  • Leest de standaardconfiguratieproviders vóór het MyConfig.json bestand. Instellingen in de MyConfig.json instelling voor het overschrijven van bestanden in de standaardconfiguratieproviders, waaronder de configuratieprovider voor omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

Normaal gesproken wilt u geen aangepast JSON-bestand dat waarden overschrijft die zijn ingesteld in de configuratieprovider omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

XML-configuratieprovider

De XmlConfigurationProvider configuratie wordt tijdens runtime geladen van sleutel-waardeparen van XML-bestanden.

Met de volgende code worden verschillende configuratieproviders toegevoegd:

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

In de voorgaande code worden instellingen in de MyXMLFile.xml en MyXMLFile.{Environment}.xml bestanden overschreven door instellingen in de:

Het voorbeelddownload bevat het volgende MyXMLFile.xml bestand:

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

In de volgende code uit het voorbeelddownload worden verschillende van de voorgaande configuratie-instellingen weergegeven:

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

Herhalende elementen die dezelfde elementnaam gebruiken, werken als het name kenmerk wordt gebruikt om de elementen te onderscheiden:

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

De volgende code leest het vorige configuratiebestand en geeft de sleutels en waarden weer:

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

Kenmerken kunnen worden gebruikt om waarden op te geven:

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

In het vorige configuratiebestand worden de volgende sleutels geladen met value:

  • key:attribute
  • section:key:attribute

Configuratieprovider voor sleutel per bestand

De KeyPerFileConfigurationProvider map maakt gebruik van de bestanden van een map als configuratiesleutel-waardeparen. De sleutel is de bestandsnaam. De waarde bevat de inhoud van het bestand. De key-per-file-configuratieprovider wordt gebruikt in Docker-hostingscenario's.

Als u key-per-file-configuratie wilt activeren, roept u de AddKeyPerFile extensiemethode aan op een exemplaar van ConfigurationBuilder. De directoryPath bestanden moeten een absoluut pad zijn.

Overbelastingen maken het opgeven van:

  • Een Action<KeyPerFileConfigurationSource> gemachtigde die de bron configureert.
  • Of de map optioneel is en of het pad naar de map is.

Het dubbele onderstrepingsteken (__) wordt gebruikt als scheidingsteken voor configuratiesleutels in bestandsnamen. De bestandsnaam Logging__LogLevel__System produceert bijvoorbeeld de configuratiesleutel Logging:LogLevel:System.

Aanroepen ConfigureAppConfiguration bij het bouwen van de host om de configuratie van de app op te geven:

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

Geheugenconfiguratieprovider

Hierbij MemoryConfigurationProvider wordt een verzameling in het geheugen gebruikt als configuratiesleutel-waardeparen.

Met de volgende code wordt een geheugenverzameling toegevoegd aan het configuratiesysteem:

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

In de volgende code van het voorbeelddownload worden de voorgaande configuratie-instellingen weergegeven:

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

In de voorgaande code config.AddInMemoryCollection(Dict) wordt deze toegevoegd na de standaardconfiguratieproviders. Zie JSON-configuratieprovider voor een voorbeeld van het ordenen van de configuratieprovider.

Zie Een matrix binden voor een ander voorbeeld met behulp van MemoryConfigurationProvider.

Kestrel eindpuntconfiguratie

Kestrel specifieke eindpuntconfiguratie overschrijft alle serveroverschrijdende eindpuntconfiguraties. Configuraties voor eindpunten tussen servers zijn onder andere:

Houd rekening met het volgende appsettings.json bestand dat wordt gebruikt in een ASP.NET Core-web-app:

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

Wanneer de voorgaande gemarkeerde markering wordt gebruikt in een ASP.NET Core-web-app en de app wordt gestart op de opdrachtregel met de volgende server-overschrijdende eindpuntconfiguratie:

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

Kestrel verbindt met het eindpunt dat specifiek is geconfigureerd voor Kestrel in het appsettings.json bestand (https://localhost:9999) en niet https://localhost:7777.

Overweeg het Kestrel specifieke eindpunt dat is geconfigureerd als een omgevingsvariabele:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

In de voorgaande omgevingsvariabele Https is dit de naam van het Kestrel specifieke eindpunt. Het voorgaande appsettings.json bestand definieert ook een specifiek eindpunt met de Kestrel naam Https. Standaard wordt de omgevingsvariabele die gebruikmaakt van de configuratieprovider Omgevingsvariabelen gelezen nadat appsettings.{Environment}.json, daarom wordt de voorgaande omgevingsvariabele gebruikt voor het Https eindpunt.

WaardeOphalen

ConfigurationBinder.GetValue extraheert één waarde uit de configuratie met een opgegeven sleutel en converteert deze naar het opgegeven type:

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

In de voorgaande code, als NumberKey niet in de configuratie wordt gevonden, wordt de standaardwaarde 99 gebruikt.

GetSection, GetChildren en Exists

Bekijk het volgende MySubsection.json bestand voor de volgende voorbeelden:

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

De volgende code voegt MySubsection.json toe aan de configuratieproviders:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection retourneert een configuratiesubsectie met de opgegeven subsectiesleutel.

De volgende code retourneert waarden voor 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"]}'");
    }
}

De volgende code retourneert waarden voor 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 keert nullnooit terug. Als er geen overeenkomende sectie wordt gevonden, wordt een lege IConfigurationSection sectie geretourneerd.

Wanneer GetSection een overeenkomende sectie retourneert, wordt Value niet ingevuld. Key en Path worden geretourneerd wanneer de sectie bestaat.

GetChildren and Exists

De volgende code roept IConfiguration.GetChildren waarden aan en retourneert waarden voor 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);
    }
}

De voorgaande code aanroepen ConfigurationExtensions.Exists om te controleren of de sectie bestaat:

Een matrix binden

De ConfigurationBinder.Bind functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Elke matrixindeling die een numeriek sleutelsegment beschikbaar maakt, kan matrixbindingen uitvoeren op een POCO-klassematrix .

Houd rekening met MyArray.json uit de voorbeeld-download:

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

De volgende code voegt MyArray.json toe aan de configuratieproviders:

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Met de volgende code wordt de configuratie gelezen en worden de waarden weergegeven:

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

De voorgaande code retourneert de volgende uitvoer:

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

In de voorgaande uitvoer heeft Index 3 een waarde value40die overeenkomt met "4": "value40", in MyArray.json. De afhankelijke matrixindexen zijn doorlopend en zijn niet gebonden aan de configuratiesleutelindex. De configuratiebinding kan geen null-waarden binden of null-vermeldingen maken in afhankelijke objecten.

Aangepaste configuratieprovider

De voorbeeld-app laat zien hoe u een eenvoudige configuratieprovider maakt die configuratiesleutel-waardeparen van een database leest met behulp van Entity Framework (EF).

De provider heeft de volgende kenmerken:

  • De EF-database in het geheugen wordt gebruikt voor demonstratiedoeleinden. Als u een database wilt gebruiken waarvoor een verbindingsreeks is vereist, implementeert u een secundaire ConfigurationBuilder om de verbindingsreeks van een andere configuratieprovider op te geven.
  • De provider leest een databasetabel in de configuratie bij het opstarten. De provider doorzoekt de database niet per sleutel.
  • Reload-on-change is niet geïmplementeerd, dus het bijwerken van de database nadat de app is gestart, heeft geen invloed op de configuratie van de app.

Definieer een EFConfigurationValue entiteit voor het opslaan van configuratiewaarden in de database.

Models/EFConfigurationValue.cs:

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

Voeg een EFConfigurationContext toe om de geconfigureerde waarden op te slaan en te openen.

EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Maak een klasse die IConfigurationSource implementeert.

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

Maak de aangepaste configuratieprovider door deze over te nemen van ConfigurationProvider. De configuratieprovider initialiseert de database wanneer deze leeg is. Omdat configuratiesleutels niet hoofdlettergevoelig zijn, wordt de woordenlijst die wordt gebruikt om de database te initialiseren gemaakt met de niet-hoofdlettergevoelige vergelijking (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;
    }
}

Met een AddEFConfiguration extensiemethode kan de configuratiebron worden toegevoegd aan een ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

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

De volgende code laat zien hoe u de aangepaste EFConfigurationProvider code gebruikt in Program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Toegangsconfiguratie met afhankelijkheidsinjectie (DI)

Configuratie kan worden geïnjecteerd in services met behulp van afhankelijkheidsinjectie (DI) door de service IConfiguration op te lossen.

public class Service
{
    private readonly IConfiguration _config;

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

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

        // ...
    }
}

Zie voor informatie over hoe u waarden kunt benaderen met behulp van IConfiguration, GetValue en GetSection, GetChildren en Exists in dit artikel.

Configuratie voor toegang in Razor Pagina's

De volgende code geeft configuratiegegevens weer op een Razor pagina:

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

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

In de volgende code MyOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

In de volgende markeringen wordt de @injectRazor instructie gebruikt om de waarde van de opties op te lossen en weer te geven:

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

Toegangsconfiguratie in een MVC-weergavebestand

De volgende code geeft configuratiegegevens weer in een MVC-weergave:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Toegangsconfiguratie in Program.cs

De volgende code heeft toegang tot de configuratie in het Program.cs bestand.

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

In appsettings.json het voorgaande voorbeeld:

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

Opties configureren met een gemachtigde

Opties die zijn geconfigureerd in een delegaat, overschrijven waarden die zijn ingesteld in de configuratieproviders.

In de volgende code wordt een IConfigureOptions<TOptions> service toegevoegd aan de servicecontainer. Er wordt een gemachtigde gebruikt om waarden te configureren voor 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();

In de volgende code worden de optieswaarden weergegeven:

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

In het voorgaande voorbeeld worden de waarden van Option1 en Option2 opgegeven in appsettings.json en vervolgens overschreven door de geconfigureerde gemachtigde.

Host versus app-configuratie

Voordat de app is geconfigureerd en gestart, wordt een host geconfigureerd en gestart. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. Zowel de app als de host worden geconfigureerd met behulp van de configuratieproviders die in dit onderwerp worden beschreven. Hostconfiguratiesleutel-waardeparen worden ook opgenomen in de configuratie van de app. Zie voor meer informatie over hoe de configuratieproviders worden gebruikt wanneer de host wordt gebouwd en hoe configuratiebronnen van invloed zijn op de hostconfiguratie ASP.NET overzicht van basisbeginselen.

Standaardhostconfiguratie

Zie de ASP.NET Core 2.2-versie van dit onderwerp voor meer informatie over de standaardconfiguratie wanneer u de webhost gebruikt.

  • Hostconfiguratie wordt geleverd van:
  • De standaardconfiguratie van de webhost is ingesteld (ConfigureWebHostDefaults):
    • Kestrel wordt gebruikt als de webserver en geconfigureerd met behulp van de configuratieproviders van de app.
    • Voeg middleware voor het filteren van hosts toe.
    • Voeg Forwarded Headers-middleware toe als de ASPNETCORE_FORWARDEDHEADERS_ENABLED omgevingsvariabele is gesteld op true.
    • IIS-integratie inschakelen.

Andere configuratie

Dit onderwerp heeft alleen betrekking op app-configuratie. Andere aspecten van het uitvoeren en hosten van ASP.NET Core-apps worden geconfigureerd met behulp van configuratiebestanden die niet in dit onderwerp worden behandeld:

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving.

Zie Configuratie migreren naar ASP.NET Core voor meer informatie over het migreren van app-configuratie van eerdere versies van ASP.NET.

Configuratie toevoegen vanuit een externe assembly

Met een IHostingStartup-implementatie kunt u verbeteringen aan een app toevoegen bij het opstarten vanuit een externe assembly buiten de Startup klasse van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Aanvullende bronnen

Kestrel eindpuntconfiguratie

Kestrel specifieke eindpuntconfiguratie overschrijft alle serveroverschrijdende eindpuntconfiguraties. Configuraties voor eindpunten tussen servers zijn onder andere:

Houd rekening met het volgende appsettings.json bestand dat wordt gebruikt in een ASP.NET Core-web-app:

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

Wanneer de voorgaande gemarkeerde markering wordt gebruikt in een ASP.NET Core-web-app en de app wordt gestart op de opdrachtregel met de volgende server-overschrijdende eindpuntconfiguratie:

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

Kestrel verbindt met het eindpunt dat specifiek is geconfigureerd voor Kestrel in het appsettings.json bestand (https://localhost:9999) en niet https://localhost:7777.

Overweeg het Kestrel specifieke eindpunt dat is geconfigureerd als een omgevingsvariabele:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

In de voorgaande omgevingsvariabele Https is dit de naam van het Kestrel specifieke eindpunt. Het voorgaande appsettings.json bestand definieert ook een specifiek eindpunt met de Kestrel naam Https. Standaard wordt de omgevingsvariabele die gebruikmaakt van de configuratieprovider Omgevingsvariabelen gelezen nadat appsettings.{Environment}.json, daarom wordt de voorgaande omgevingsvariabele gebruikt voor het Https eindpunt.

WaardeOphalen

ConfigurationBinder.GetValue extraheert één waarde uit de configuratie met een opgegeven sleutel en converteert deze naar het opgegeven type. Deze methode is een extensiemethode voor IConfiguration:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

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

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

In de voorgaande code, als NumberKey niet in de configuratie wordt gevonden, wordt de standaardwaarde 99 gebruikt.

GetSection, GetChildren en Exists

Bekijk het volgende MySubsection.json bestand voor de volgende voorbeelden:

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

De volgende code voegt MySubsection.json toe aan de configuratieproviders:

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 retourneert een configuratiesubsectie met de opgegeven subsectiesleutel.

De volgende code retourneert waarden voor 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"]}'");
    }
}

De volgende code retourneert waarden voor 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 keert nullnooit terug. Als er geen overeenkomende sectie wordt gevonden, wordt een lege IConfigurationSection sectie geretourneerd.

Wanneer GetSection een overeenkomende sectie retourneert, wordt Value niet ingevuld. Key en Path worden geretourneerd wanneer de sectie bestaat.

GetChildren and Exists

De volgende code roept IConfiguration.GetChildren waarden aan en retourneert waarden voor 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);
    }
}

De voorgaande code aanroepen ConfigurationExtensions.Exists om te controleren of de sectie bestaat:

Een matrix binden

De ConfigurationBinder.Bind functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Elke matrixindeling die een numeriek sleutelsegment beschikbaar maakt, kan matrixbindingen uitvoeren op een POCO-klassematrix .

Houd rekening met MyArray.json uit de voorbeeld-download:

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

De volgende code voegt MyArray.json toe aan de configuratieproviders:

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

Met de volgende code wordt de configuratie gelezen en worden de waarden weergegeven:

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

De voorgaande code retourneert de volgende uitvoer:

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

In de voorgaande uitvoer heeft Index 3 een waarde value40die overeenkomt met "4": "value40", in MyArray.json. De afhankelijke matrixindexen zijn doorlopend en zijn niet gebonden aan de configuratiesleutelindex. De configuratiebinding kan geen null-waarden binden of null-vermeldingen maken in afhankelijke objecten

Met de volgende code wordt de array:entries configuratie geladen met de AddInMemoryCollection extensiemethode:

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

De volgende code leest de configuratie in de arrayDictDictionary en geeft de waarden weer:

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

De voorgaande code retourneert de volgende uitvoer:

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

Index #3 in het gebonden object bevat de configuratiegegevens voor de configuratiesleutel array:4 en de waarde ervan van value4. Wanneer configuratiegegevens met een matrix zijn gebonden, worden de matrixindexen in de configuratiesleutels gebruikt om de configuratiegegevens te herhalen bij het maken van het object. Een null-waarde kan niet worden bewaard in configuratiegegevens en een vermelding met null-waarden wordt niet gemaakt in een afhankelijk object wanneer een matrix in configuratiesleutels een of meer indexen overslaat.

Het ontbrekende configuratie-item voor index 3 kan worden opgegeven voordat de binding met het ArrayExample exemplaar wordt uitgevoerd door een configuratieprovider die het sleutel-/waardepaar van de index #3 leest. Bekijk het volgende Value3.json bestand uit de voorbeelddownload:

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

De volgende code bevat configuratie voor Value3.json en de arrayDictDictionary.

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

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

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

De volgende code leest de voorgaande configuratie en geeft de waarden weer:

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

De voorgaande code retourneert de volgende uitvoer:

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

Aangepaste configuratieproviders zijn niet vereist om matrixbinding te implementeren.

Aangepaste configuratieprovider

Waarschuwing

In dit artikel wordt het gebruik van verbindingsreeksen beschreven. Met een lokale database hoeft de gebruiker niet te worden geverifieerd, maar in productie bevatten verbindingsreeksen soms een wachtwoord om te verifiëren. Een wachtwoordgegevens voor een eigenaar van een bron (ROPC) is een beveiligingsrisico dat moet worden vermeden in productiedatabases. Productie-apps moeten gebruikmaken van de veiligste verificatiestroom die beschikbaar is. Zie Beveiligde verificatiestromenvoor meer informatie over verificatie voor apps die zijn geïmplementeerd voor test- of productieomgevingen.

De voorbeeld-app laat zien hoe u een eenvoudige configuratieprovider maakt die configuratiesleutel-waardeparen van een database leest met behulp van Entity Framework (EF).

De provider heeft de volgende kenmerken:

  • De EF-database in het geheugen wordt gebruikt voor demonstratiedoeleinden. Als u een database wilt gebruiken waarvoor een verbindingsreeks is vereist, implementeert u een secundaire ConfigurationBuilder om de verbindingsreeks van een andere configuratieprovider op te geven.
  • De provider leest een databasetabel in de configuratie bij het opstarten. De provider doorzoekt de database niet per sleutel.
  • Reload-on-change is niet geïmplementeerd, dus het bijwerken van de database nadat de app is gestart, heeft geen invloed op de configuratie van de app.

Definieer een EFConfigurationValue entiteit voor het opslaan van configuratiewaarden in de database.

Models/EFConfigurationValue.cs:

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

Voeg een EFConfigurationContext toe om de geconfigureerde waarden op te slaan en te openen.

EFConfigurationProvider/EFConfigurationContext.cs:

// using Microsoft.EntityFrameworkCore;

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

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

Maak een klasse die IConfigurationSource implementeert.

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

Maak de aangepaste configuratieprovider door deze over te nemen van ConfigurationProvider. De configuratieprovider initialiseert de database wanneer deze leeg is. Omdat configuratiesleutels niet hoofdlettergevoelig zijn, wordt de woordenlijst die wordt gebruikt om de database te initialiseren gemaakt met de niet-hoofdlettergevoelige vergelijking (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-2005
        var configValues = 
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Met een AddEFConfiguration extensiemethode kan de configuratiebron worden toegevoegd aan een ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:

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

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

De volgende code laat zien hoe u de aangepaste EFConfigurationProvider code gebruikt in Program.cs:

// using Microsoft.EntityFrameworkCore;

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

Toegangsconfiguratie bij opstarten

De volgende code geeft configuratiegegevens weer in Startup methoden:

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

Zie App startup: Convenience methods voor een voorbeeld van toegang tot de configuratie met behulp van startgemakmethoden.

Configuratie voor toegang in Razor Pagina's

De volgende code geeft configuratiegegevens weer op een Razor pagina:

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

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

In de volgende code MyOptions wordt deze toegevoegd aan de servicecontainer met Configure en gebonden aan de configuratie:

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

    services.AddRazorPages();
}

In de volgende markeringen wordt de @injectRazor instructie gebruikt om de waarde van de opties op te lossen en weer te geven:

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

Toegangsconfiguratie in een MVC-weergavebestand

De volgende code geeft configuratiegegevens weer in een MVC-weergave:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Opties configureren met een gemachtigde

Opties die zijn geconfigureerd in een delegaat, overschrijven waarden die zijn ingesteld in de configuratieproviders.

Het configureren van opties met een gemachtigde wordt gedemonstreerd als voorbeeld 2 in de voorbeeld-app.

In de volgende code wordt een IConfigureOptions<TOptions> service toegevoegd aan de servicecontainer. Er wordt een gemachtigde gebruikt om waarden te configureren voor MyOptions:

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

    services.AddRazorPages();
}

In de volgende code worden de optieswaarden weergegeven:

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

In het voorgaande voorbeeld worden de waarden van Option1 en Option2 opgegeven in appsettings.json en vervolgens overschreven door de geconfigureerde gemachtigde.

Host versus app-configuratie

Voordat de app is geconfigureerd en gestart, wordt een host geconfigureerd en gestart. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. Zowel de app als de host worden geconfigureerd met behulp van de configuratieproviders die in dit onderwerp worden beschreven. Hostconfiguratiesleutel-waardeparen worden ook opgenomen in de configuratie van de app. Zie voor meer informatie over hoe de configuratieproviders worden gebruikt wanneer de host wordt gebouwd en hoe configuratiebronnen van invloed zijn op de hostconfiguratie ASP.NET overzicht van basisbeginselen.

Standaardhostconfiguratie

Zie de ASP.NET Core 2.2-versie van dit onderwerp voor meer informatie over de standaardconfiguratie wanneer u de webhost gebruikt.

  • Hostconfiguratie wordt geleverd van:
    • Omgevingsvariabelen voorafgegaan door DOTNET_ (bijvoorbeeld DOTNET_ENVIRONMENT) met behulp van de configuratieprovider Omgevingsvariabelen. Het voorvoegsel (DOTNET_) wordt verwijderd wanneer de configuratiesleutel-waardeparen worden geladen.
    • Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.
  • De standaardconfiguratie van de webhost is ingesteld (ConfigureWebHostDefaults):
    • Kestrel wordt gebruikt als de webserver en geconfigureerd met behulp van de configuratieproviders van de app.
    • Voeg middleware voor het filteren van hosts toe.
    • Voeg Forwarded Headers-middleware toe als de ASPNETCORE_FORWARDEDHEADERS_ENABLED omgevingsvariabele is gesteld op true.
    • IIS-integratie inschakelen.

Andere configuratie

Dit onderwerp heeft alleen betrekking op app-configuratie. Andere aspecten van het uitvoeren en hosten van ASP.NET Core-apps worden geconfigureerd met behulp van configuratiebestanden die niet in dit onderwerp worden behandeld:

Omgevingsvariabelen die zijn ingesteld in launchSettings.json overschrijven die in de systeemomgeving.

Zie Configuratie migreren naar ASP.NET Core voor meer informatie over het migreren van app-configuratie van eerdere versies van ASP.NET.

Configuratie toevoegen vanuit een externe assembly

Met een IHostingStartup-implementatie kunt u verbeteringen aan een app toevoegen bij het opstarten vanuit een externe assembly buiten de Startup klasse van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Aanvullende bronnen