Configuratie in ASP.NET Core

App-configuratie 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, waaronder azure-app-configuratie
• Azure Key Vault
• Opdrachtregelargumenten
• Aangepaste providers, geïnstalleerd of gemaakt
• .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.

Zie Blazor voor aanvullende Blazor configuratierichtlijnen die hieraan worden toegevoegd of deze richtlijnen vervangen.

Dit artikel heeft voornamelijk betrekking op app-configuratie. Andere typen configuraties, zoals opstartinstellingenbestanden en het web.config bestand, worden hier vermeld, maar hun primaire documentatie is elders:

• Start instellingenbestanden (launch.json/launchSettings.json), die hulpprogramma-configuratiebestanden voor de Development omgeving zijn. Zie ASP.NET Core runtime-omgevingen voor meer informatie. Sommige details over startinstellingen worden in dit artikel behandeld in het gedeelte Instellingen voor het overschrijven van omgevingsvariabelen.
• web.config, een serverconfiguratiebestand voor IIS (Internet Information Services). Zie Host ASP.NET Core in Windows met IIS en ASP.NET Core Module (ANCM) voor IIS voor meer informatie.

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

Voorbeelden in dit artikel maken gebruik van primaire constructors, beschikbaar in C# 12 (.NET 8) of hoger. Zie Primaire constructors declareren voor klassen en structs (C#-documentatie) en Primaire constructors (C#-handleiding) voor meer informatie.

Configuratiewaarden lezen

De configuratie wordt doorgaans gelezen door de IConfiguration service (Microsoft.Extensions.Configuration naamruimte) op te lossen en de sleutel van configuratiesleutel-waardeparen te gebruiken om een configuratiewaarde te verkrijgen.

De volgende Razor onderdeelcode laat zien hoe een configuratiewaarde, een e-mailadres van een technische contactpersoon, wordt verkregen uit de configuratie door de sleutel TechnicalContactEmail.

@inject IConfiguration Config

Technical Contact: @Config["TechnicalContactEmail"]

App- en hostconfiguratie

ASP.NET Core-apps een host configureren en starten. De host is verantwoordelijk voor het opstarten en levensduurbeheer van apps. Hostconfiguratiesleutel-waardeparen worden opgenomen in de configuratie van de app. Hoewel u een aantal app-configuraties met hostconfiguratieproviders kunt uitvoeren, raden we u alleen aan om configuraties uit te voeren die nodig zijn voor de hostconfiguratie.

App-configuratie heeft de hoogste prioriteit. 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.

Standaard-app-configuratiebronnen

var builder = WebApplication.CreateBuilder(args);

Host.CreateDefaultBuilder(args)

De standaard-app-configuratie wordt in de volgende volgorde geladen, van hoogste naar laagste prioriteit:

1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.
2. Omgevingsvariabelen die niet worden voorafgegaan door ASPNETCORE_ of DOTNET_ met behulp van de configuratieprovider voor omgevingsvariabelen.
3. Gebruikersgeheimen wanneer de app wordt uitgevoerd in de Development omgeving met behulp van de bestandsconfiguratieprovider.
4. Configuratie van omgevings-app-instellingenbestand via appsettings.{ENVIRONMENT}.json, waarbij de {ENVIRONMENT} tijdelijke aanduiding de omgeving van de app is, met behulp van de JSON-configuratieprovider. Wordt bijvoorbeeld appsettings.Production.json gebruikt in productie en appsettings.Development.json wordt gebruikt tijdens de ontwikkeling.
5. Algemene configuratie van app-instellingenbestand via appsettings.json de JSON-configuratieprovider.
6. Noodhostconfiguratie.

Als u opdrachtregelargumenten wilt toestaan om instellingen zoals de omgevingsnaam te beheren. Dit is belangrijk om te bepalen welk app-instellingenbestand op basis van de omgeving moet worden geladen. De opdrachtregelconfiguratieprovider wordt twee keer gebruikt als een configuratiebron, aan het begin en einde van de configuratie. Omdat de provider aan het einde wordt gebruikt, heeft deze de hoogste prioriteit.

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

Standaardhostconfiguratiebronnen

Hostvariabelen

De volgende variabelen worden vroeg ingesteld in de initialisatie van hostbouwer en kunnen niet worden beïnvloed door app-configuratie:

• Toepassingsnaam.
• Omgevingsnaam.
• Inhoudsbasis.
• Webroot.
• Of er moet worden gescand op hosting startassemblies en welke assemblies gescand moeten worden.
• Variabelen die worden gelezen door app- en bibliotheekprogramma's vanuit HostBuilderContext.Configuration in IHostBuilder.ConfigureAppConfiguration callbacks.

Andere hostinstellingen worden gelezen uit app-configuratie in plaats van hostconfiguratie.

URLS is een van de vele algemene hostinstellingen die niet worden opgestart door de hostconfiguratie. URLS wordt later gelezen vanuit de app-configuratie. Hostconfiguratie is een terugval optie voor app-configuratie, dus hostconfiguratie kan worden gebruikt om URLS in te stellen, maar de waarde wordt overschreven door elke configuratiebron die URLS instelt in de app-configuratie, zoals app-instellingenbestanden (appsettings.{ENVIRONMENT}.json, waarbij de {ENVIRONMENT} tijdelijke aanduiding de omgevingsnaam is, of appsettings.json).

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

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.

De bestandsconfiguratiebron user secrets van de standaardconfiguratiebronnen wordt geregistreerd na de JSON-configuratiebronnen voor app-instellingenbestanden. 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:

• ASP.NET Core runtime-omgevingen
• Veilige opslag van app-geheimen in ontwikkeling in ASP.NET Core: bevat advies over het gebruik van omgevingsvariabelen voor het opslaan van gevoelige gegevens. Het hulpprogramma Secret Manager gebruikt de File Configuration Provider om gebruikersgeheimen op te slaan in een JSON-bestand op het lokale systeem.
• 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.

Toegangsconfiguratie met afhankelijkheidsinjectie (DI)

Configuratie kan worden geïnjecteerd in services met behulp van afhankelijkheidsinjectie (DI) door de IConfiguration service op te lossen. In het volgende voorbeeld wordt de configuratiewaarde die is opgeslagen voor de configuratiesleutel die wordt vertegenwoordigd door de {KEY} tijdelijke aanduiding, toegewezen aan value. Als de sleutel niet wordt gevonden, null wordt deze toegewezen aan value:

public class CustomService(IConfiguration config)
{
    public void CustomMethod()
    {
        var value = config["{KEY}"];
    }
}

Toegangsconfiguratie in het Program bestand

De volgende code heeft toegang tot de configuratie in het Program bestand met behulp van WebApplicationBuilder.Configuration (builder.Configuration):

var defaultConnectionString = 
   builder.Configuration.GetValue<string>("ConnectionStrings:DefaultConnection");

Nadat de app is gemaakt (na de regel var app = builder.Build();), gebruikt u WebApplication.Configuration (app.Configuration):

var defaultLogLevel = app.Configuration.GetValue<string>("Logging:LogLevel:Default");

Toegangsconfiguratie in de Startup klasse

Deze sectie is over het algemeen van toepassing op ASP.NET Core-apps vóór de release van .NET 6.

De volgende code geeft configuratiegegevens weer in Startup methoden:

public class Startup
{
    public Startup(IConfiguration config)
    {
        Config = config;
    }

    public IConfiguration Config { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = Config["ConnectionStrings.DefaultConnection"]}");

        ...
    }

    public void Configure(...)
    {
        var defaultLogLevel = Config["Logging:LogLevel:Default"]}");

        ...
    }
}

Configuratie-instellingen weergeven bij opstarten voor foutopsporing

In de volgende code worden de configuratiesleutel-waardeparen van de app weergegeven bij het opstarten van de app.

#if DEBUG
foreach (var c in app.Configuration.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

#if DEBUG
foreach (var c in config.AsEnumerable())
{
    Console.WriteLine($"CONFIG: Key: {c.Key} Value: {c.Value}");
}
#endif

Configuratiesleutels en -waarden

Configuratiesleutels:

• Zijn hoofdlettergevoelig. ConnectionString en connectionstring worden bijvoorbeeld behandeld als gelijkwaardige sleutels.
• Als een sleutel en waarde worden ingesteld door 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 puntscheidingsteken niet op alle platforms. Een dubbel onderstrepingsteken (__) wordt ondersteund door alle platforms en wordt automatisch geconverteerd naar een dubbele punt (:) wanneer de configuratie wordt gelezen door de app.
  • In Azure Key Vault gebruiken hiërarchische sleutels dubbele streepjes (--) als scheidingsteken. De Azure Key Vault-configuratieprovider vervangt automatisch de dubbele streepjes () door een dubbele punt (--:) wanneer de geheimen worden geladen in de configuratie van de app.
• De ConfigurationBinder functie ondersteunt bindingsmatrices voor objecten met behulp van matrixindexen in configuratiesleutels. Matrixbinding wordt beschreven in de sectie Een matrix binden .

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

Hoe hiërarchische configuratiegegevens worden georganiseerd

De configuratie-API leest hiërarchische configuratiegegevens door de hiërarchische gegevens plat te maken met behulp van een scheidingsteken, meestal dubbele punten (:), in de configuratiesleutels. Dubbele onderstrepingstekens (__) worden meestal gebruikt met configuratie van omgevingsvariabelen voor platformoverschrijdende ondersteuning.

Houd rekening met de volgende hiërarchische configuratiegegevens:

• ConnectionStrings
  • DefaultConnection (Value =no-loc text="Data Source=LocalSqlServer\MSSQLDev;":::")
• Logging
  • LogLevel
    • Default (Waarde = Information)
    • Microsoft (Waarde = Warning)
    • Microsoft.Hosting.Lifetime (Waarde = Information)
• AllowedHosts (Waarde = *)

In de volgende tabel worden de sleutels weergegeven die worden gebruikt om de waarden in de voorgaande configuratiegegevens te herstellen. Het scheidingsteken is niet vereist voor AllowedHosts.

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

Wanneer de elementstructuur een matrix bevat, moet de matrixindex worden behandeld als een extra elementnaam in het pad. Houd rekening met de volgende hiërarchische configuratiegegevens als een matrix.

MainObject (een array):

• Eerste item in de matrix
  • Object0
  • Object1
    • SubObject0
    • SubObject1
• Tweede item in de matrix
  • Object0
  • Object1
    • SubObject0
    • SubObject1

Sleutels met dubbelepunt-scheidingstekens.

• MainObject:0:Object0
• MainObject:0:Object1:SubObject0
• MainObject:0:Object1:SubObject1
• MainObject:1:Object0
• MainObject:1:Object1:SubObject0
• MainObject:1:Object1:SubObject1

Sleutels met onderstreep-scheidingstekens, aanbevolen voor cross-platform compatibiliteit wanneer de configuratie door omgevingsvariabelen wordt geleverd:

• MainObject__0__Object0
• MainObject__0__Object1:SubObject0
• MainObject__0__Object1:SubObject1
• MainObject__1__Object0
• MainObject__1__Object1:SubObject0
• MainObject__1__Object1:SubObject1

Omdat de configuratie die afkomstig is van matrices wordt afgevlakt en genummerd voor elke configuratiebron die door een app wordt gebruikt, kunnen waarden onverwacht worden overschreven als er geen zorg wordt genomen bij het structureren en lezen van de gegevens uit meerdere bronnen. Houd rekening met de volgende sleutel-waardeparen voor de configuratie:

Modules waarden (een matrix):

• Module1
• Module2
• Module3

De matrix wordt afgevlakt en geïndexeerd, wat de configuratiesleutel-waardeparen in de volgende tabel oplevert.

Nadat de voorgaande configuratie tot stand is gebracht, wordt de volgende configuratie door een andere configuratiebron geladen:

Modules waarden (een matrix):

• Module4
• Module5

Deze matrix wordt ook opeenvolgend afgevlakt en geïndexeerd.

Als u zich herinnert dat de laatste configuratiebron voor een bepaalde sleutel de waarde van die sleutel instelt, worden de laatste set configuratiesleutel-waardeparen weergegeven in de volgende tabel.

Dit is geen verrassend resultaat gezien hoe het framework matrixgegevens uit configuratiebronnen plat maakt en indexeert, maar het moet in gedachten worden gehouden om onverwachte overschrijvingen te voorkomen.

Om dergelijke overschrijven te voorkomen, structureert u matrixindexering zodat deze overeenkomt met verschillende configuratiebronnen die dezelfde matrixgegevens bieden. Een alternatieve oplossing is het scheiden van arraywaarden binnen een tekenreeks van één sleutel-waardepaar, bijvoorbeeld door een komma, puntkomma of pipe als scheidingsteken te gebruiken. Schrijf aangepaste code om de tekenreeks te splitsen en de gescheiden waarden toe te wijzen aan uw matrix.

Configuratieproviders

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

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. Algemene app-instellingen via appsettings.json.
2. Omgevingsapp-instellingen via appsettings.{ENVIRONMENT}.json, waarbij de {ENVIRONMENT} placeholder de omgeving van de app is (voorbeelden: Development, Production).
3. Gebruikersgeheimen.
4. Omgevingsvariabelen met behulp van de configuratieprovider voor 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.

Als u de configuratieproviders van de app wilt inspecteren, injecteertIConfiguration, castt u deze naar IConfigurationRooten leest u de Providers eigenschap.

In het volgende ConfigurationProvidersRazor onderdeel worden de ingeschakelde configuratieproviders weergegeven in de volgorde waarin ze aan de app worden toegevoegd.

Pages/ConfigurationProviders.razor:

@page "/configuration-providers"
@inject IConfiguration Config

<h1>Configuration Providers</h1>

@if (ConfigRoot is not null)
{
    <ul>
        @foreach (var provider in ConfigRoot.Providers)
        {
            <li>@provider</li>
        }
    </ul>
}

@code {
    private IConfigurationRoot? ConfigRoot;

    protected override void OnInitialized()
    {
        ConfigRoot = (IConfigurationRoot)Config;
    }
}

Het voorgaande Razor onderdeel produceert de volgende uitvoer, waarbij de {APP NAMESPACE} tijdelijke aanduiding de naamruimte van de app is.

MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'ASPNETCORE_'
MemoryConfigurationProvider
EnvironmentVariablesConfigurationProvider Prefix: 'DOTNET_'
JsonConfigurationProvider for 'appsettings.json' (Optional)
JsonConfigurationProvider for 'appsettings.Development.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.json' (Optional)
JsonConfigurationProvider for '{APP NAMESPACE}.settings.Development.json' (Optional)
EnvironmentVariablesConfigurationProvider
Microsoft.Extensions.Configuration.ChainedConfigurationProvider

In de sectie Standaard-app-configuratiebronnen eerder in dit artikel worden configuratiebronnen van hoogste naar laagste prioriteit vermeld. In het voorgaande ConfigurationProviders onderdeel worden de bronnen weergegeven in de volgorde waarin de app ze leest. De JSON-configuratieprovider voor het bestand met instellingen voor niet-omgevings-apps (appsettings.json) bevindt zich bijvoorbeeld eerder in de voorgaande lijst, omdat deze wordt toegevoegd vóór de provider voor het instellingenbestand voor de ontwikkelomgevings-app (appsettings.Development.json). De configuratieproviders worden uitgevoerd vanaf de bovenkant van de lijst tot aan de onderkant van de lijst. Voor een overeenkomende configuratiesleutel tussen de twee JSON-configuratieproviders van de twee app-instellingen heeft de laatste instelling voorrang. Dit is de waarde van appsettings.Development.json.

Configuratie van app-instellingenbestand (appsettings.json, appsettings.{ENVIRONMENT}.json)

Lees de configuratie die is geladen vanuit app-instellingenbestanden met behulp van de JSON-configuratieprovider.

Houd rekening met het volgende appsettings.json bestand:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=LocalSqlServer\\MSSQLDev;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Injecteer een exemplaar van IConfiguration om configuratiewaarden te lezen.

Het volgende AppSettingsConfigurationRazor onderdeel leest de standaardconfiguratie voor databaseverbindingsreeks en standaardconfiguratie op logboekregistratieniveau. IConfiguration wordt boven aan het onderdeel geïnjecteerd en gebruikt om configuratiewaarden te lezen. Er wordt een dubbele punt (:) scheidingsteken gebruikt in configuratiesleutels met tekenreekstypen om de juiste JSON-eigenschappen te vinden. De JSON-structuur voor het standaardobject voor de verbindingsreeks (DefaultConnection) is bijvoorbeeld genest onder het object verbindingsreeksen (ConnectionStrings), zodat de tekenreeks notatie voor toegang tot de standaardverbindingsreeks een dubbele punt gebruikt om te scheiden DefaultConnection en ConnectionStrings in de volgorde waarin de objecten worden weergegeven in het app-instellingenbestand: ConnectionStrings:DefaultConnection.

Pages/AppSettingsConfiguration.razor:

@page "/app-settings-configuration"
@inject IConfiguration Config

<h1>App Settings Configuration</h1>

<ul>
    <li>Default Connection String: @Config["ConnectionStrings:DefaultConnection"]
    <li>Default Log Level: @Config["Logging:LogLevel:Default"]
</ul>

Dezelfde benadering wordt gebruikt in een Razor Pagina's-paginamodel.

using Microsoft.Extensions.Configuration;

...

public class AppSettingsPageModel(IConfiguration config) : PageModel
{
    public ContentResult OnGet()
    {
        var defaultConnectionString = config["ConnectionStrings:DefaultConnection"];
        var defaultLogLevel = config["Logging:LogLevel:Default"];

        return Content(
            $"Default Connection String: {defaultConnectionString}\n" +
            $"Default Log Level: {defaultLogLevel}");
    }
}

De standaardinstellingen voor het laden van JsonConfigurationProvider-exemplaren volgen deze volgorde:

1. appsettings.json
2. appsettings.{ENVIRONMENT}.json, waarbij de {ENVIRONMENT} tijdelijke aanduiding de omgeving van de app is (voorbeelden: appsettings.Production.json, appsettings.Development.json). De omgevingsversie van het bestand wordt geladen op basis van de IHostingEnvironment.EnvironmentName.

appsettings.{ENVIRONMENT}.json waarden overschrijven sleutels in appsettings.json.

Standaard:

• In de ontwikkelomgeving overschrijft appsettings.Development.json configuratie waarden die gevonden worden in appsettings.json.
• In de productieomgeving overschrijft appsettings.Production.json configuratie de waarden die gevonden zijn in appsettings.json.

In het voorgaande voorbeeld worden alleen tekenreeksen gelezen en wordt geen standaardwaarde ondersteund. Als een configuratiewaarde moet worden gegarandeerd met een standaardwaarde, raadpleegt u de sectie Één waarde uit de configuratie extraheren met typeconversie (GetValue).

Als u de standaard-app-configuratiebronnen gebruikt, worden de appsettings.json bestanden appsettings.{ENVIRONMENT}.json ingeschakeld met reloadOnChange ingesteld op true, wat betekent dat wijzigingen die zijn aangebracht in de appsettings.json app of appsettings.{ENVIRONMENT}.json bestanden nadat de app is gestart direct nadat het bestand is opgeslagen, van kracht zijn.

Opmerkingen in appsettings.json en appsettings.{ENVIRONMENT}.json bestanden worden ondersteund met javaScript- of C#-stijlopmerkingen. Sommige IDE's (Integrated Development Environments) geven fouten weer bij het bewerken van een JSON-bestand dat opmerkingen bevat, omdat de officiële JSON-specificatie (RFC 7159) geen rekening houdt met opmerkingen in JSON-bestanden. Over het algemeen kunt u opmerkingenfouten en waarschuwingen negeren, maar u kunt ook meestal waarschuwingen of fouten 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"
}

De voorgaande instelling geeft aan VS Code aan dat app-instellingenbestanden, inclusief bestanden op basis van omgevingen, zijn gekoppeld aan de JSONC-bestandsindeling ('JSON met opmerkingen') die opmerkingen ondersteunt.

Voor andere IDE's raadpleegt u de documentatie en productondersteuningskanalen van de IDE om te bepalen hoe fouten of waarschuwingen over opmerkingen in JSON-bestanden moeten worden gedempt.

Configuratieprovider voor omgevingsvariabelen

De standaardconfiguratieprovider voor omgevingsvariabelen (EnvironmentVariablesConfigurationProvider) laadt de configuratie van omgevingsvariabelen die niet zijn voorafgegaan door ASPNETCORE_ of DOTNET_. Zie de sectie ASPNETCORE_ en DOTNET_ omgevingsvariabelen (.NET Core-documentatie) voor meer informatie over DOTNET_ en omgevingsvariabelen.

Met behulp van de standaardconfiguratieprovider voor omgevingsvariabelen laadt de app de configuratie van sleutel-waardeparen van omgevingsvariabelen na het lezen appsettings.json, appsettings.{ENVIRONMENT}.jsonen 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, __, wordt door alle platforms ondersteund en wordt automatisch vervangen door een punt, :.

Zie de volgende bronnen voor hulp bij het instellen van omgevingsvariabelen in een opdrachtshell in Windows of in een platformoverschrijdende PowerShell-opdrachtshell:

• set (omgevingsvariabele)
• setx
• about_Environment_Variables (PowerShell-documentatie)

Aangepast voorvoegsel voor omgevingsvariabelen

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

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

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

Opstartinstellingen overschrijven omgevingsvariabele-instellingen

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. In het volgende voorbeeld wordt het Linux-hulpprogramma systemd-escape gebruikt om het resultaat te verkrijgen http:--localhost:5001 van http://localhost:5001:

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

App-instellingen van Azure App Service (omgevingsvariabelen)

Zie de volgende resources voor de richtlijnen voor app-instellingen van Azure App Service (omgevingsvariabele):

• Een App Service-app configureren (Azure-documentatie)
• Voorvoegsels van Azure Database-verbindingsreeks

Verbindingsreeksvoorvoegsels

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 volgende tabel worden weergegeven, worden geladen in de app met de standaardconfiguratie of wanneer er geen voorvoegsel wordt opgegeven aan AddEnvironmentVariables.

Wanneer een omgevingsvariabele wordt gedetecteerd en in de configuratie wordt geladen met een van de vier voorvoegsels die in de voorgaande 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.

Command-line

Met behulp van de standaardconfiguratiebronnen laadt de CommandLineConfigurationProvider configuratie van opdrachtregelargumentsleutel-waardeparen na de volgende configuratiebronnen:

• appsettings.json en appsettings.{ENVIRONMENT}.json bestanden.
• App-geheimen in de Development omgeving.
• Omgevingsvariabelen.

Configuratiewaarden die zijn ingesteld op de opdrachtregel overschrijven standaard configuratiewaarden die zijn ingesteld door alle andere configuratieproviders.

Opdrachtregelargumenten

Met de volgende dotnet run opdracht worden sleutels en waarden ingesteld met gelijktekens (=):

dotnet run ConnectionStrings:DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;" Logging:LogLevel:Default=Information

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van forward slashes (/):

dotnet run /ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" /Logging:LogLevel:Default Information

Met de volgende opdracht worden sleutels en waarden ingesteld met behulp van dubbele streepjes (--):

dotnet run --ConnectionStrings:DefaultConnection "Data Source=LocalSqlServer\\MSSQLDev;" --Logging:LogLevel:Default Information

Argument-conventies

• De sleutelwaarde moet het gelijkteken (=) volgen, of de sleutel moet een voorvoegsel hebben van een dubbel streepje (--) of een schuine streep (/) wanneer de waarde op een spatie volgt.
• Het niet toewijzen van een waarde na een gelijkteken (=) resulteert in het toewijzen van een lege tekenreeks voor de configuratie-instelling. Het opgeven ConnectionStrings:DefaultConnection= is bijvoorbeeld geldig en resulteert in het toewijzen van een lege tekenreeks aan de standaardverbindingsreeks.
• Meng binnen dezelfde opdracht geen argument sleutel-waardeparen gescheiden door een gelijkteken (=) met sleutel-waardeparen gescheiden door een spatie.

Switchtoewijzingen

Switchtoewijzingen maken het mogelijk om vervangingslogica voor sleutelnamen toe te passen via een woordenboek van schakelvevangingen dat wordt doorgegeven aan 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 één streepje (-) of dubbel streepje (--).
• De woordenlijst voor switchtoewijzingen mag geen dubbele sleutels bevatten.

In het volgende voorbeeld wordt een switch-toewijzingswoordenboek (switchMappings) doorgegeven aan AddCommandLine in het Program-bestand van de app:

var switchMappings = 
    new Dictionary<string, string>(){ { "-k1", "key1" }, { "-k2", "key2" } };

builder.Configuration.AddCommandLine(args, switchMappings);

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    var switchMappings =
        new Dictionary<string, string>() { { "-k1", "key1" }, { "-k2", "key2" } };

    config.AddCommandLine(args, switchMappings);
});

De volgende dotnet run opdrachten demonstreren sleutelvervanging (value1 in key1 en value2 naar key2):

• dotnet run -k1 value1 -k2 value2
• dotnet run --k1=value1 --k2=value2
• dotnet run --k1 value1 --k2 value2
• dotnet run /k1=value1 /k2=value2
• dotnet run /k1 value1 /k2 value2

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.

Bestandsconfiguratie-provider

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

• INI-configuratieprovider
• JSON-configuratieprovider
• XML-configuratieprovider

INI-configuratieprovider

IniConfigurationProvider laadt configuratie-instellingen vanuit ini-bestand sleutelwaardeparen. In het volgende voorbeeld ziet u hoe u de provider gebruikt. Overladingsmethoden kunnen aangeven of het bestand optioneel is en of de configuratie opnieuw wordt geladen bij bestandswijzigingen.

IniConfig.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLDev;"

[Logging:LogLevel]
Default=Debug
Microsoft=Debug

IniConfig.Production.ini:

[ConnectionStrings]
DefaultConnection="Data Source=LocalSqlServer\\MSSQLProd;"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Laad de configuratie door aan te roepen AddIniFile. In het volgende voorbeeld wordt een configuratiebron gemaakt voor elk van de voorgaande bestanden. De configuratie van het niet-omgevingsbestand wordt opnieuw geladen als het bestand wordt gewijzigd (reloadOnChange parameter, standaardwaarde: false). De omgevingsversie van het bestand geeft aan dat het bestand optioneel is (optional parameter, standaardinstelling: false). Als u het bestand opnieuw wilt laden bij wijziging (reloadOnChange: true), moet u ook opgeven of het bestand optioneel is (optional).

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    config
        .AddIniFile("IniConfig.ini", optional:false, reloadOnChange: true)
        .AddIniFile("IniConfig.Production.ini", optional: true);
});

JSON-configuratieprovider

De JsonConfigurationProvider laadt de configuratie vanuit de sleutel-waardeparen van het JSON-bestand. In het volgende voorbeeld ziet u hoe u de provider gebruikt. Overladingsmethoden kunnen aangeven of het bestand optioneel is en of de configuratie opnieuw wordt geladen bij bestandswijzigingen.

Roep AddJsonFile aan met het bestandspad (of de bestandsnaam als het bestand zich in de hoofdmap van de app bevindt). Het volgende maakt het bestand optioneel (optionalparameter, standaard: false) en geeft aan dat de configuratie opnieuw wordt geladen als het bestand wordt gewijzigd (reloadOnChangeparameter, standaard): false Als u het bestand opnieuw wilt laden bij wijziging (reloadOnChange: true), moet u ook opgeven of het bestand optioneel is (optional).

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    config.AddJsonFile("config.json", optional: true, reloadOnChange: true);
});

XML-configuratieprovider

De XmlConfigurationProvider laadt de configuratie vanuit sleutel-waardeparen in een XML-bestand. In het volgende voorbeeld ziet u hoe u de provider gebruikt. Overladingsmethoden kunnen aangeven of het bestand optioneel is en of de configuratie opnieuw wordt geladen bij bestandswijzigingen.

XmlFile.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnection>Data Source=LocalSqlServer\\MSSQLDev;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Debug</Default>
      <Microsoft>Debug</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

XmlFile.Production.xml:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <ConnectionStrings>
    <DefaultConnectionString>Data Source=LocalSqlServer\\MSSQLProd;</DefaultConnectionString>
  </ConnectionStrings>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Laad de configuratie door aan te roepen AddXmlFile. In het volgende voorbeeld wordt een configuratiebron gemaakt voor elk van de voorgaande bestanden. De configuratie van het niet-omgevingsbestand wordt opnieuw geladen als het bestand wordt gewijzigd (reloadOnChange parameter, standaardwaarde: false). De omgevingsversie van het bestand geeft aan dat het bestand optioneel is (optional parameter, standaardinstelling: false). Als u het bestand opnieuw wilt laden bij wijziging (reloadOnChange: true), moet u ook opgeven of het bestand optioneel is (optional).

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
.ConfigureAppConfiguration(config =>
{ 
    config
        .AddXmlFile("XmlFile.xml", optional:false, reloadOnChange: true)
        .AddXmlFile("XmlFile.Production.xml", optional: true);
});

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>

var value_00 = Config["section:section0:key:key0"];
var value_01 = Config["section:section0:key:key1"];
var value_10 = Config["section:section1:key:key0"];
var value_11 = Config["section:section1:key:key1"];

Kenmerken die waarden leveren, worden ondersteund:

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

Met de vorige configuratie 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.

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
builder.Configuration.AddKeyPerFile(directoryPath: path, optional: true);

.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 configSettings = new Dictionary<string, string>
{
    { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
    { "Logging:LogLevel:Default", "Information" }
};

builder.Configuration.AddInMemoryCollection(configSettings);

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .ConfigureAppConfiguration(config =>
    { 
        var configSettings = new Dictionary<string, string>
        {
            { "ConnectionStrings:DefaultConnection", "Data Source=LocalSqlServer\\MSSQLDev;" },
            { "Logging:LogLevel:Default", "Information" }
        };

        config.AddInMemoryCollection(configSettings);
    });

Zie de sectie MemoryConfigurationProvider voor een aanvullend voorbeeld waarin een wordt gebruikt.

Kestrel eindpuntconfiguratie

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

• UseUrls.
• --urls op de opdrachtregel.
• De ASPNETCORE_URLSomgevingsvariabele.

Bekijk de volgende Kestrel configuratiesectie in een appsettings.json bestand:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:9999"
    }
  }
},

De app wordt gestart op de opdrachtregel met dotnet run en de volgende configuratie voor eindpunten tussen servers:

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 de configuratie van het eindpunt tussen servers die is doorgegeven aan de dotnet run opdracht (https://localhost:7777).

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

• Sleutel: Kestrel__Endpoints__Https__Url
• Waarde: https://localhost:8888

In de voorgaande omgevingsvariabele is 'Https' de naam van het Kestrel-specifieke eindpunt. De voorgaande configuratie van app-instellingen definieert ook een Kestrel-specifiek eindpunt met de naam Https. Volgens de standaardhostconfiguratieproviders worden omgevingsvariabelen gelezen door de configuratieprovider voor omgevingsvariabelen na appsettings.{ENVIRONMENT}.json. Daarom wordt de voorgaande omgevingsvariabele (Kestrel__Endpoints__Https__Url) gebruikt voor het Https eindpunt.

Eén waarde extraheren uit de configuratie met typeconversie (GetValue)

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

var number = Config.GetValue<int>("NumberKey", 99);

In de voorgaande code:

• Config is een geïnjecteerde IConfiguration.
• Als NumberKey niet wordt gevonden in de configuratie, wordt de standaardwaarde 99 gebruikt.

Werken met secties, de onderliggende items van een sectie ophalen en bepalen of er een sectie bestaat

Bekijk het volgende subsection.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"
    }
  }
}

Een configuratieprovider voor subsection.json wordt toegevoegd door AddJsonFile aan te roepen.

GetSection

IConfiguration.GetSection retourneert een configuratiesubsectie met de opgegeven subsectiesleutel.

De volgende code retourneert waarden voor section1, waarbij Config een geïnjecteerde IConfigurationwaarde is:

var subsection = Config.GetSection("section1");
var value1 = subsection["key0"];
var value2 = subsection["key1"];

De volgende code retourneert waarden voor section2:subsection0, waarbij Config een geïnjecteerde IConfigurationwaarde is:

var subsection = Config.GetSection("section2:subsection0");
var value1 = subsection["key0"];
var value2 = subsection["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 en Exists

Met de volgende code wordt aanroepen uitgevoerd:

• ConfigurationExtensions.Exists om te controleren of dit section2 bestaat.
• IConfiguration.GetChildren en retourneert waarden voor de subsecties van section2.

var section = Config.GetSection("section2");

if (!section.Exists())
{
    throw new Exception("section2 doesn't exist!");
}

var children = section.GetChildren();

foreach (var subSection in children)
{
    int i = 0;
    var key1 = subSection.Key + ":key" + i++.ToString();
    var key2 = subSection.Key + ":key" + i.ToString();
    Console.WriteLine($"{key1} value: {section[key1]}");
    Console.WriteLine($"{key2} value: {section[key2]}");
}

Uitvoer:

no-loc text="subsection0:key0 value: value200":::
no-loc text="subsection0:key1 value: value201":::
no-loc text="subsection1:key0 value: value210":::
no-loc text="subsection1:key1 value: value211":::

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 .

array.json:

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

Een configuratieprovider voor array.json wordt toegevoegd door AddJsonFile aan te roepen.

De volgende code leest de configuratiewaarden:

ArrayExample.cs:

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

var array = Config.GetSection("array").Get<ArrayExample>();

if (array is null)
{
    throw new ArgumentNullException(nameof(array));
}

string output = String.Empty;

for (int j = 0; j < array.Entries?.Length; j++)
{
    Console.WriteLine($"Index: {j} Value: {array.Entries[j]}");
}

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 array.json. De afhankelijke matrixindexen zijn doorlopend en zijn niet gebonden aan de configuratiesleutelindex. De configuratiebinder is niet in staat om null waarden te binden of null invoerwaarden te maken in gebonden objecten.

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

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

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

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

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

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

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

// 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) => 
        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 het woordenboek dat wordt gebruikt om de database te initialiseren, gemaakt met de niet-hoofdlettergevoelige vergelijker, 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;
    }
}

// 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 het bestand van Program de app:

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

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

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

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

• ASP.NET Core Blazor-configuratie
• Broncode voor configuratie
• Voorbeeldcode bekijken of downloaden (hoe download je)
• Optiepatroon in ASP.NET Core