Configuratieproviders in .NET

Configuratie in .NET is mogelijk bij configuratieproviders. Verschillende typen providers zijn afhankelijk van verschillende configuratiebronnen. In dit artikel worden alle verschillende configuratieproviders en de bijbehorende bronnen beschreven.

• Bestandsconfiguratieprovider
• Configuratieprovider voor omgevingsvariabelen
• Opdrachtregelconfiguratieprovider
• Configuratieprovider voor sleutel per bestand
• Geheugenconfiguratieprovider

Bestandsconfiguratieprovider

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

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

Sleutels zijn niet-hoofdlettergevoelig. Alle bestandsconfiguratieproviders genereren de FormatException wanneer dubbele sleutels worden gevonden in één provider.

JSON-configuratieprovider

De JsonConfigurationProvider klasse laadt de configuratie van een JSON-bestand. Installeer het Microsoft.Extensions.Configuration.Json NuGet-pakket.

Overbelastingen kunnen het volgende opgeven:

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

Kijk eens naar de volgende code:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

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

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Met de voorgaande code wordt:

• Hiermee wist u alle bestaande configuratieproviders die standaard in de CreateApplicationBuilder(String[]) methode zijn toegevoegd.
• Hiermee configureert u de JSON-configuratieprovider om de appsettings.json en appsettings te laden.Environmentjson-bestanden met de volgende opties:
  • optional: true: Het bestand is optioneel.
  • reloadOnChange: true: het bestand wordt opnieuw geladen wanneer wijzigingen worden opgeslagen.

Belangrijk

Wanneer u configuratieproviders toevoegt met IConfigurationBuilder.Add, wordt de toegevoegde configuratieprovider toegevoegd aan het einde van de IConfigurationSource lijst. Wanneer sleutels door meerdere providers worden gevonden, overschrijft de laatste provider de vorige providers.

Een voorbeeld appsettings.json bestand met verschillende configuratie-instellingen volgt:

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

Nadat de configuratieproviders zijn toegevoegd, kunt u vanuit het IConfigurationBuilder exemplaar aanroepen IConfigurationBuilder.Build() om het IConfigurationRoot object op te halen. De hoofdmap van de configuratie vertegenwoordigt de hoofdmap van een configuratiehiërarchie. Secties uit de configuratie kunnen worden gebonden aan exemplaren van .NET-objecten en later worden geleverd via IOptions<TOptions> afhankelijkheidsinjectie.

Notitie

De eigenschappen Build Action en Copy naar Output Directory van het JSON-bestand moeten worden ingesteld op Inhoud en Kopiëren als nieuwer (of Altijd kopiëren).

Houd rekening met de TransientFaultHandlingOptions klasse die als volgt is gedefinieerd:

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Met de volgende code wordt de hoofdmap van de configuratie gebouwd, wordt een sectie gekoppeld aan het TransientFaultHandlingOptions klassetype en worden de afhankelijke waarden afgedrukt in het consolevenster:

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

De toepassing schrijft de volgende voorbeelduitvoer:

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

XML-configuratieprovider

De XmlConfigurationProvider klasse laadt de configuratie van een XML-bestand tijdens runtime. Installeer het Microsoft.Extensions.Configuration.Xml NuGet-pakket.

De volgende code toont de configuratie van XML-bestanden met behulp van de XML-configuratieprovider.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Met de voorgaande code wordt:

• Hiermee wist u alle bestaande configuratieproviders die standaard in de CreateApplicationBuilder(String[]) methode zijn toegevoegd.
• Hiermee configureert u de XML-configuratieprovider om de appsettings.xml - en repeating-example.xml-bestanden te laden met de volgende opties:
  • optional: true: Het bestand is optioneel.
  • reloadOnChange: true: het bestand wordt opnieuw geladen wanneer wijzigingen worden opgeslagen.
• Hiermee configureert u de configuratieprovider voor omgevingsvariabelen.
• Hiermee configureert u de opdrachtregelconfiguratieprovider als de opgegeven args argumenten bevatten.

De XML-instellingen worden overschreven door instellingen in de configuratieprovider voor omgevingsvariabelen en de opdrachtregelconfiguratieprovider.

Een voorbeeld appsettings.xml bestand met verschillende configuratie-instellingen volgt:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Tip

Als u het IConfiguration type in WinForms-apps wilt gebruiken, voegt u een verwijzing toe naar het NuGet-pakket Microsoft.Extensions.Configuration.Xml . Instantieer de ConfigurationBuilder aanroepen en ketengesprekken naar AddXmlFile en Build(). Zie .NET Docs Issue #29679 voor meer informatie.

Voeg in .NET 5 en eerdere versies het name kenmerk toe om herhalende elementen te onderscheiden die dezelfde elementnaam gebruiken. In .NET 6 en latere versies indexeert de XML-configuratieprovider automatisch herhalende elementen. Dit betekent dat u het kenmerk niet hoeft op te geven name , behalve als u de index 0 in de sleutel wilt gebruiken en er slechts één element is. (Als u een upgrade uitvoert naar .NET 6 of hoger, kan er een onderbreking optreden als gevolg van deze wijziging in het gedrag. Zie Herhaalde XML-elementen bevatten index voor meer informatie.)

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

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

De toepassing schrijft de volgende voorbeelduitvoer:

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

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

INI-configuratieprovider

De IniConfigurationProvider klasse laadt de configuratie van een INI-bestand tijdens runtime. Installeer het Microsoft.Extensions.Configuration.Ini NuGet-pakket.

Met de volgende code worden alle configuratieproviders gewist en worden de IniConfigurationProvider twee INI-bestanden als bron toegevoegd:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Een voorbeeld appsettings.ini bestand met verschillende configuratie-instellingen volgt:

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Met de volgende code worden de voorgaande configuratie-instellingen weergegeven door ze naar het consolevenster te schrijven:

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

De toepassing schrijft de volgende voorbeelduitvoer:

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

Configuratieprovider voor omgevingsvariabelen

Met behulp van de standaardconfiguratie laadt de EnvironmentVariablesConfigurationProvider configuratie van sleutel-waardeparen van de omgevingsvariabele na het lezen van appsettings.json, appsettings.Environment. json en Secret Manager. Daarom overschrijven sleutelwaarden uit de omgeving waarden die worden gelezen uit appsettings.json, appsettings.Environment. json en Secret Manager.

Het : scheidingsteken werkt niet met hiërarchische sleutels van de omgevingsvariabele op alle platforms. Het scheidingsteken wordt bijvoorbeeld : niet ondersteund door Bash. Het dubbele onderstrepingsteken (__), dat op alle platforms wordt ondersteund, vervangt automatisch eventuele : scheidingstekens in omgevingsvariabelen.

Houd rekening met de TransientFaultHandlingOptions klasse:

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Met de volgende set opdrachten worden de omgevingssleutels en -waarden van SecretKey en TransientFaultHandlingOptionsingesteld.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

Deze omgevingsinstellingen worden alleen ingesteld in processen die worden gestart vanuit het opdrachtvenster waarin ze zijn ingesteld. Ze worden niet gelezen door web-apps die zijn gestart met Visual Studio.

Met Visual Studio 2019 en hoger kunt u omgevingsvariabelen opgeven met behulp van het dialoogvenster Profielen starten.

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 SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Als u wilt testen of de voorgaande opdrachten alle appsettings.json en appsettings overschrijven.Environment json-instellingen:

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

Voorvoegsels

Als u een voorvoegsel voor omgevingsvariabelen wilt opgeven, roept AddEnvironmentVariables u een tekenreeks aan:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

In de voorgaande code:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") wordt toegevoegd na de standaardconfiguratieproviders. Zie de XML-configuratieprovider voor een voorbeeld van het ordenen van de configuratieprovider.
• Omgevingsvariabelen die zijn ingesteld met het CustomPrefix_ voorvoegsel overschrijven de standaardconfiguratieproviders. Dit omvat omgevingsvariabelen zonder het voorvoegsel.

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

De standaardconfiguratie laadt omgevingsvariabelen en opdrachtregelargumenten voorafgegaan door DOTNET_. Het DOTNET_ voorvoegsel wordt gebruikt door .NET voor host - en app-configuratie, maar niet voor gebruikersconfiguratie.

Zie .NET Generic Host voor meer informatie over host- en app-configuratie.

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

Verbindingsreeksvoorvoegsel	Provider
CUSTOMCONNSTR_	Aangepaste provider
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

Belangrijk

Microsoft raadt u aan de veiligste verificatiestroom te gebruiken die beschikbaar is. Als u verbinding maakt met Azure SQL, is Managed Identities voor Azure-resources de aanbevolen verificatiemethode.

Omgevingsvariabelen ingesteld in launchSettings.json

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

Azure-app Service-instellingen

Selecteer op Azure-app Service de optie Nieuwe toepassingsinstelling op de pagina Instellingenconfiguratie>. Azure-app servicetoepassingsinstellingen zijn:

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

Opdrachtregelconfiguratieprovider

Met behulp van de standaardconfiguratie wordt de configuratie van de CommandLineConfigurationProvider opdrachtregelargumentsleutel-waardeparen na de volgende configuratiebronnen geladen:

• appsettings.json en appsettings.Environment.json-bestanden.
• App-geheimen (Secret Manager) in de Development omgeving.
• Omgevingsvariabelen.

Standaard overschrijven configuratiewaarden die zijn ingesteld op de opdrachtregel configuratiewaarden die zijn ingesteld met alle andere configuratieproviders.

Met Visual Studio 2019 en hoger kunt u opdrachtregelargumenten opgeven met behulp van het dialoogvenster Profielen starten.

Opdrachtregelargumenten

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

dotnet run SecretKey="Secret key from command line"

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

dotnet run /SecretKey "Secret key set from forward slash"

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

dotnet run --SecretKey "Secret key set from double hyphen"

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: SomeKey=.

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

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 is 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((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.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:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

In de voorgaande code MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) voegt u de geheugenprovider toe na de standaardconfiguratieproviders. Zie de XML-configuratieprovider voor een voorbeeld van het ordenen van de configuratieprovider.

Zie ook

• Configuratie in .NET
• .NET Generic Host
• Een aangepaste configuratieprovider implementeren