Dela via

Konfigurationsprovidrar i .NET

  • Artikel

Konfiguration i .NET är möjlig med konfigurationsprovidrar. Flera typer av leverantörer förlitar sig på olika konfigurationskällor. Den här artikeln beskriver alla de olika konfigurationsprovidrar och deras motsvarande källor.

Filkonfigurationsprovider

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

Nycklar är skiftlägesokänsliga. Alla filkonfigurationsprovidrar genererar när FormatException dubbletter av nycklar hittas i en enda provider.

JSON-konfigurationsprovider

Klassen JsonConfigurationProvider läser in konfigurationen från en JSON-fil. Installera NuGet-paketet Microsoft.Extensions.Configuration.Json .

Överlagringar kan ange:

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

Ta följande kod som exempel:

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

Koden ovan:

  • Rensar alla befintliga konfigurationsprovidrar som har lagts till som standard i CreateApplicationBuilder(String[]) -metoden.
  • Konfigurerar JSON-konfigurationsprovidern för att läsa in appsettings.json och apparinställningar.Environment.json-filer med följande alternativ:
    • optional: true: Filen är valfri.
    • reloadOnChange: true: Filen laddas om när ändringar sparas.

Viktigt!

När du lägger till konfigurationsproviders med IConfigurationBuilder.Addläggs den tillagda konfigurationsprovidern till i slutet av IConfigurationSource listan. När nycklar hittas av flera leverantörer åsidosätter den senaste providern som läste nyckeln tidigare leverantörer.

Ett exempel appsettings.json fil med olika konfigurationsinställningar följer:

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

När konfigurationsprovidrar har lagts till från instansen IConfigurationBuilderIConfigurationBuilder.Build() kan du anropa IConfigurationRoot för att hämta objektet. Konfigurationsroten representerar roten i en konfigurationshierarki. Avsnitt från konfigurationen kan bindas till instanser av .NET-objekt och senare tillhandahållas via IOptions<TOptions> beroendeinmatning.

Kommentar

Egenskaperna Skapa åtgärd och Kopiera till utdatakatalog för JSON-filen måste anges till Innehåll och Kopiera om det är nyare (eller Kopiera alltid).

Överväg klassen TransientFaultHandlingOptions som definierats på följande sätt:

namespace ConsoleJson.Example;

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

Följande kod skapar konfigurationsroten, binder ett avsnitt till TransientFaultHandlingOptions klasstypen och skriver ut de bundna värdena till konsolfönstret:

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

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

Programmet skriver följande exempelutdata:

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

XML-konfigurationsprovider

Klassen XmlConfigurationProvider läser in konfigurationen från en XML-fil vid körning. Installera NuGet-paketet Microsoft.Extensions.Configuration.Xml .

Följande kod visar konfigurationen av XML-filer med hjälp av XML-konfigurationsprovidern.

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

Koden ovan:

  • Rensar alla befintliga konfigurationsprovidrar som har lagts till som standard i CreateApplicationBuilder(String[]) -metoden.
  • Konfigurerar XML-konfigurationsprovidern för att läsa in appsettings.xml - och repeating-example.xml-filerna med följande alternativ:
    • optional: true: Filen är valfri.
    • reloadOnChange: true: Filen laddas om när ändringar sparas.
  • Konfigurerar konfigurationsprovidern för miljövariabler.
  • Konfigurerar kommandoradskonfigurationsprovidern om den angivna args innehåller argument.

XML-inställningarna åsidosättas av inställningar i konfigurationsprovidern Miljövariabler och kommandoradskonfigurationsprovidern.

Ett exempel appsettings.xml fil med olika konfigurationsinställningar följer:

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

Dricks

Om du vill använda IConfiguration typen i WinForms-appar lägger du till en referens till NuGet-paketet Microsoft.Extensions.Configuration.Xml . Instansiera anropen ConfigurationBuilder och kedjan till AddXmlFile och Build(). Mer information finns i .NET Docs Issue #29679.

I .NET 5 och tidigare versioner lägger du till name attributet för att särskilja upprepande element som använder samma elementnamn. I .NET 6 och senare versioner indexerar XML-konfigurationsprovidern automatiskt upprepade element. Det innebär att du inte behöver ange name attributet, förutom om du vill ha indexet "0" i nyckeln och det bara finns ett element. (Om du uppgraderar till .NET 6 eller senare kan det uppstå en paus till följd av den här ändringen av beteendet. Mer information finns i Upprepade XML-element inkluderar index.)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

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

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

Programmet skulle skriva följande exempelutdata:

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

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

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

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

  • key:attribute
  • section:key:attribute

INI-konfigurationsprovider

Klassen IniConfigurationProvider läser in konfigurationen från en INI-fil vid körning. Installera NuGet-paketet Microsoft.Extensions.Configuration.Ini .

Följande kod rensar alla konfigurationsprovidrar och lägger till IniConfigurationProvider med två INI-filer som källa:

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

Ett exempel appsettings.ini fil med olika konfigurationsinställningar följer:

SecretKey="Secret key value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Följande kod visar de föregående konfigurationsinställningarna genom att skriva dem till konsolfönstret:

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

Programmet skulle skriva följande exempelutdata:

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

Konfigurationsprovider för miljövariabler

Med standardkonfigurationen läser konfigurationen EnvironmentVariablesConfigurationProvider in från nyckel/värde-par för miljövariabeln efter att ha läst appsettings.json, Environment. json och secret manager. Därför åsidosätter nyckelvärden som läss från miljön värden som läss från appsettings.json, appsettings.. Environment json och secret manager.

Avgränsare : fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Avgränsare : stöds till exempel inte av Bash. Det dubbla understrecket (__), som stöds på alla plattformar, ersätter automatiskt alla : avgränsare i miljövariabler.

Överväg klassen TransientFaultHandlingOptions :

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

Följande set kommandon anger miljönycklarna och värdena SecretKey för och TransientFaultHandlingOptions.

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

De här miljöinställningarna anges endast i processer som startas från kommandofönstret som de angavs i. De läses inte av webbappar som startas med Visual Studio.

Med Visual Studio 2019 och senare kan du ange miljövariabler med hjälp av dialogrutan Starta profiler .

Dialogrutan Starta profiler med miljövariabler

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

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Testa att föregående kommandon åsidosätter alla appsettings.json och apparinställningar..Environment json-inställningar:

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

Prefix

Om du vill ange ett prefix för miljövariabler anropar du AddEnvironmentVariables med en sträng:

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

I koden ovan:

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

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

Standardkonfigurationen läser in miljövariabler och kommandoradsargument med prefixet DOTNET_. Prefixet DOTNET_ används av .NET för värd - och appkonfiguration, men inte för användarkonfiguration.

Mer information om värd- och appkonfiguration finns i .NET Generic Host.

Anslutningssträngsprefix

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

Anslutningssträngsprefix Provider
CUSTOMCONNSTR_ Anpassad provider
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

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

  • Konfigurationsnyckeln skapas genom att miljövariabelprefixet tas bort och ett konfigurationsnyckelavsnitt läggs till (ConnectionStrings).
  • Ett nytt nyckel/värde-par för konfiguration skapas som representerar databasanslutningsprovidern (förutom CUSTOMCONNSTR_, som inte har någon angiven provider).
Miljövariabelnyckel Konverterad konfigurationsnyckel Providerkonfigurationspost
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Konfigurationsposten har inte skapats.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Nyckel: ConnectionStrings:{KEY}_ProviderName:
Värde: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Nyckel: ConnectionStrings:{KEY}_ProviderName:
Värde: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Nyckel: ConnectionStrings:{KEY}_ProviderName:
Värde: System.Data.SqlClient

Viktigt!

Microsoft rekommenderar att du använder det säkraste tillgängliga autentiseringsflödet. Om du ansluter till Azure SQL är hanterade identiteter för Azure-resurser den rekommenderade autentiseringsmetoden.

Miljövariabler som anges i launchSettings.json

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

Inställningar för Azure App Service

På Azure App Serviceväljer du Lägg till på sidan Inställningar>miljövariabler. Azure App Service-programinställningar är:

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

Konfigurationsprovider för kommandorad

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

  • appsettings.json och apparinställningar.Environment.json-filer.
  • Apphemligheter (Secret Manager) i Development miljön.
  • Miljövariabler.

Som standard åsidosätter konfigurationsvärden som angetts på kommandoraden konfigurationsvärden som angetts med alla andra konfigurationsproviders.

Med Visual Studio 2019 och senare kan du ange kommandoradsargument med hjälp av dialogrutan Starta profiler .

Dialogrutan Starta profiler med kommandoradsargument

Kommandoradsargument

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

dotnet run SecretKey="Secret key from command line"

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

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

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

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

Nyckelvärdet:

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

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

Konfigurationsprovider för nyckel per fil

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

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

Överlagringar tillåter att du anger:

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

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

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

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

Minneskonfigurationsprovider

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

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

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

I föregående kod MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) lägger du till minnesprovidern efter standardkonfigurationsprovidrar. Ett exempel på hur du beställer konfigurationsprovidrar finns i XML-konfigurationsprovidern.

Se även