Udostępnij za pośrednictwem

Dostawcy konfiguracji na platformie .NET

  • Artykuł

Konfiguracja na platformie .NET jest możliwa w przypadku dostawców konfiguracji. Kilka typów dostawców polega na różnych źródłach konfiguracji. Ten artykuł zawiera szczegółowe informacje o wszystkich różnych dostawcach konfiguracji i odpowiednich źródłach.

Dostawca konfiguracji plików

FileConfigurationProvider to klasa bazowa na potrzeby ładowania konfiguracji z systemu plików. Następujący dostawcy konfiguracji pochodzą z obiektu FileConfigurationProvider:

W kluczach nie jest rozróżniana wielkość liter. Wszyscy dostawcy konfiguracji plików zgłaszają, FormatException gdy w jednym dostawcy znajdują się zduplikowane klucze.

Dostawca konfiguracji JSON

Klasa JsonConfigurationProvider ładuje konfigurację z pliku JSON. Microsoft.Extensions.Configuration.Json Zainstaluj pakiet NuGet.

Przeciążenia mogą wskazywać, czy:

  • Plik jest opcjonalny.
  • Konfiguracja zostanie ponownie załadowana, jeśli plik się zmieni.

Spójrzmy na poniższy kod:

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

Powyższy kod ma następujące działanie:

  • Czyści wszystkich istniejących dostawców konfiguracji, które zostały dodane domyślnie w metodzie CreateApplicationBuilder(String[]) .
  • Konfiguruje dostawcę konfiguracji JSON w celu załadowania appsettings.json i appsettings.Environment.Pliki json z następującymi opcjami:
    • optional: true: plik jest opcjonalny.
    • reloadOnChange: true: plik zostanie ponownie załadowany po zapisaniu zmian.

Ważne

Podczas dodawania dostawców konfiguracji za pomocą IConfigurationBuilder.Addpolecenia dodawany jest dostawca konfiguracji na końcu IConfigurationSource listy. Gdy klucze są znajdowane przez wielu dostawców, ostatni dostawca odczytuje przesłonięcia poprzednich dostawców.

Przykładowy plik appsettings.json z różnymi ustawieniami konfiguracji:

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

IConfigurationBuilder Z wystąpienia po dodaniu dostawców konfiguracji można wywołać metodę IConfigurationBuilder.Build()IConfigurationRoot w celu pobrania obiektu. Główny katalog konfiguracji reprezentuje katalog główny hierarchii konfiguracji. Sekcje z konfiguracji można powiązać z wystąpieniami obiektów platformy .NET, a później udostępniane jako IOptions<TOptions> za pomocą wstrzykiwania zależności.

Uwaga

Właściwości Akcja kompilacji i Kopiuj do katalogu wyjściowego pliku JSON muszą być ustawione odpowiednio na Zawartość i Kopiuj, jeśli nowsze (lub Kopiuj zawsze).

Rozważ klasę zdefiniowaną TransientFaultHandlingOptions w następujący sposób:

namespace ConsoleJson.Example;

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

Poniższy kod kompiluje główny katalog konfiguracji, wiąże sekcję z TransientFaultHandlingOptions typem klasy i wyświetla powiązane wartości w oknie konsoli:

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

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

Aplikacja zapisuje następujące przykładowe dane wyjściowe:

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

Dostawca konfiguracji plików XML

Klasa XmlConfigurationProvider ładuje konfigurację z pliku XML w czasie wykonywania. Microsoft.Extensions.Configuration.Xml Zainstaluj pakiet NuGet.

Poniższy kod przedstawia konfigurację plików XML przy użyciu dostawcy konfiguracji XML.

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

Powyższy kod ma następujące działanie:

  • Czyści wszystkich istniejących dostawców konfiguracji, które zostały dodane domyślnie w metodzie CreateApplicationBuilder(String[]) .
  • Konfiguruje dostawcę konfiguracji XML w celu załadowania plików appsettings.xml i repeating-example.xml przy użyciu następujących opcji:
    • optional: true: plik jest opcjonalny.
    • reloadOnChange: true: plik zostanie ponownie załadowany po zapisaniu zmian.
  • Konfiguruje dostawcę konfiguracji zmiennych środowiskowych.
  • Konfiguruje dostawcę konfiguracji wiersza polecenia, jeśli dany args zawiera argumenty.

Ustawienia XML są zastępowane przez ustawienia w dostawcy konfiguracji zmiennych środowiskowych i dostawcy konfiguracji wiersza polecenia.

Przykładowy plik appsettings.xml z różnymi ustawieniami konfiguracji:

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

Napiwek

Aby użyć IConfiguration typu w aplikacjach WinForms, dodaj odwołanie do pakietu NuGet Microsoft.Extensions.Configuration.Xml . ConfigurationBuilder Utwórz wystąpienie wywołań i łańcucha do AddXmlFile i Build(). Aby uzyskać więcej informacji, zobacz Problem z dokumentacją platformy .NET #29679.

W programie .NET 5 i starszych wersjach dodaj name atrybut , aby odróżnić powtarzające się elementy, które używają tej samej nazwy elementu. W programie .NET 6 i nowszych wersjach dostawca konfiguracji XML automatycznie indeksuje powtarzające się elementy. Oznacza to, że nie musisz określać atrybutu name , z wyjątkiem tego, czy chcesz indeksu "0" w kluczu i istnieje tylko jeden element. (W przypadku uaktualniania do platformy .NET 6 lub nowszej może wystąpić przerwa wynikająca z tej zmiany zachowania. Aby uzyskać więcej informacji, zobacz Powtarzające się elementy XML obejmują indeks.

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

Poniższy kod odczytuje poprzedni plik konfiguracji i wyświetla klucze oraz wartości:

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

Aplikacja napisze następujące przykładowe dane wyjściowe:

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

Atrybuty mogą być używane do podawania wartości:

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

Poprzedni plik konfiguracji ładuje następujące klucze za pomocą elementu value:

  • key:attribute
  • section:key:attribute

Dostawca konfiguracji plików INI

Klasa IniConfigurationProvider ładuje konfigurację z pliku INI w czasie wykonywania. Microsoft.Extensions.Configuration.Ini Zainstaluj pakiet NuGet.

Poniższy kod czyści wszystkich dostawców konfiguracji i dodaje IniConfigurationProvider element z dwoma plikami INI jako źródłem:

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

Przykładowy plik appsettings.ini z różnymi ustawieniami konfiguracji:

SecretKey="Secret key value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Poniższy kod wyświetla poprzednie ustawienia konfiguracji, zapisując je w oknie konsoli:

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

Aplikacja napisze następujące przykładowe dane wyjściowe:

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

Dostawca konfiguracji zmiennej środowiskowej

Przy użyciu konfiguracji domyślnej konfiguracja EnvironmentVariablesConfigurationProvider ładuje konfigurację z par klucz-wartość zmiennej środowiskowej po przeczytaniu appsettings.json, Environment i menedżer wpisów tajnych. W związku z tym wartości klucza odczytane ze środowiska zastępują wartości odczytane z appsettings.json, appsettings.. Environment json i menedżer wpisów tajnych.

Ogranicznik : nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. Na przykład : ogranicznik nie jest obsługiwany przez powłokę Bash. Podwójne podkreślenie (__), które jest obsługiwane na wszystkich platformach, automatycznie zastępuje wszystkie : ograniczniki w zmiennych środowiskowych.

Rozważ klasę TransientFaultHandlingOptions :

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

Następujące set polecenia ustawiają klucze środowiska i wartości SecretKey i TransientFaultHandlingOptions.

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

Te ustawienia środowiska są ustawiane tylko w procesach uruchamianych z okna poleceń, w których zostały ustawione. Nie są one odczytywane przez aplikacje internetowe uruchamiane za pomocą programu Visual Studio.

W programie Visual Studio 2019 lub nowszym można określić zmienne środowiskowe przy użyciu okna dialogowego Uruchamianie profilów .

Okno dialogowe Uruchamianie profilów z wyświetlonymi zmiennymi środowiskowymi

Następujące polecenia setx służą do ustawiania kluczy i wartości środowiska w systemie Windows. W przeciwieństwie do polecenia set, ustawienia polecenia setx są trwałe. Element /M ustawia zmienną w środowisku systemowym. Jeśli przełącznik /M nie jest używany, ustawiana jest zmienna środowiskowa użytkownika.

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

Aby sprawdzić, czy poprzednie polecenia zastępują wszystkie appsettings.json i appsettings..Environment Ustawienia w formacie JSON:

  • Przy użyciu programu Visual Studio: zamknij i uruchom ponownie program Visual Studio.
  • Za pomocą interfejsu wiersza polecenia: uruchom nowe okno polecenia i wprowadź dotnet run.

Prefiksy

Aby określić prefiks zmiennych środowiskowych, wywołaj AddEnvironmentVariables metodę z ciągiem:

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

Powyższy kod:

  • config.AddEnvironmentVariables(prefix: "CustomPrefix_") jest dodawany po domyślnym dostawcy konfiguracji. Aby zapoznać się z przykładem zamawiania dostawców konfiguracji, zobacz Dostawca konfiguracji XML.
  • Zmienne środowiskowe ustawione za pomocą prefiksu CustomPrefix_ zastępują domyślnych dostawców konfiguracji. Obejmuje to zmienne środowiskowe bez prefiksu.

Prefiks jest usuwany podczas odczytu par klucz-wartość konfiguracji.

Domyślna konfiguracja ładuje zmienne środowiskowe i argumenty wiersza polecenia poprzedzone prefiksem DOTNET_. Prefiks jest używany przez platformę DOTNET_ .NET na potrzeby konfiguracji hosta i aplikacji, ale nie konfiguracji użytkownika.

Aby uzyskać więcej informacji na temat konfiguracji hosta i aplikacji, zobacz artykuł Host ogólny platformy .NET.

Prefiksy parametrów połączenia

Interfejs API konfiguracji ma specjalne reguły przetwarzania dla czterech zmiennych środowiskowych parametrów połączenia. Te parametry połączenia są uwzględniane podczas konfigurowania parametrów połączenia platformy Azure dla środowiska aplikacji. Zmienne środowiskowe z prefiksami wyświetlanymi w tabeli są ładowane do aplikacji z konfiguracją domyślną lub gdy nie podano prefiksu .AddEnvironmentVariables

Prefiks parametrów połączenia Dostawca
CUSTOMCONNSTR_ Dostawca niestandardowy
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

Gdy zmienna środowiskowa zostanie odnaleziona i załadowana do konfiguracji z dowolnym z czterech prefiksów pokazanych w tabeli:

  • Klucz konfiguracji jest tworzony przez usunięcie prefiksu zmiennej środowiskowej i dodanie sekcji klucza konfiguracji (ConnectionStrings).
  • Tworzona jest nowa para klucz-wartość konfiguracji, która reprezentuje dostawcę połączenia z bazą danych (z wyjątkiem elementu CUSTOMCONNSTR_, który nie ma podanego dostawcy).
Klucz zmiennej środowiskowej Przekonwertowany klucz konfiguracji Wpis konfiguracji dostawcy
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Wpis konfiguracji nie został utworzony.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName:
Wartość: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName:
Wartość: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName:
Wartość: System.Data.SqlClient

Ważne

Firma Microsoft zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Jeśli łączysz się z usługą Azure SQL, tożsamości zarządzane dla zasobów platformy Azure to zalecana metoda uwierzytelniania.

Zmienne środowiskowe ustawione w launchSettings.json

Zmienne środowiskowe ustawione w launchSettings.json przesłaniają te ustawione w środowisku systemowym.

ustawienia usługi aplikacja systemu Azure

Na Azure App Servicekliknij Dodaj na stronie Ustawienia>Zmienne środowiskowe. Ustawienia aplikacji usługi Azure App Service są:

  • szyfrowane podczas przechowywania i przesyłane za pośrednictwem zaszyfrowanego kanału,
  • Uwidaczniane jako zmienne środowiskowe.

Dostawca konfiguracji wiersza polecenia

Przy użyciu konfiguracji domyślnej konfiguracja CommandLineConfigurationProvider ładuje konfigurację z par klucz-wartość argumentu wiersza polecenia po następujących źródłach konfiguracji:

  • appsettings.json i appsettings.Environment.Pliki json.
  • Wpisy tajne aplikacji (Secret Manager) w Development środowisku.
  • Zmienne środowiskowe.

Domyślnie wartości konfiguracji ustawione w wierszu polecenia zastępują wartości konfiguracji ustawione przez wszystkich innych dostawców konfiguracji.

W programie Visual Studio 2019 lub nowszym można określić argumenty wiersza polecenia przy użyciu okna dialogowego Uruchamianie profilów .

Okno dialogowe Uruchamianie profilów z argumentami wiersza polecenia

Argumenty wiersza polecenia

Następujące polecenie ustawia klucze i wartości przy użyciu =:

dotnet run SecretKey="Secret key from command line"

Następujące polecenie ustawia klucze i wartości przy użyciu /:

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

Następujące polecenie ustawia klucze i wartości przy użyciu --:

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

Wartość klucza:

  • Musi następować po = lub klucz musi mieć prefiks -- albo /, gdy wartość następuje po spacji.
  • Nie jest wymagana w przypadku użycia elementu =. Na przykład SomeKey=.

W tym samym poleceniu nie mieszaj par klucz-wartość argumentu wiersza polecenia, które używają elementu =, z parami klucz-wartość, które używają spacji.

Dostawca konfiguracji typu „klucz na plik”

Element KeyPerFileConfigurationProvider używa plików katalogu jako par klucz-wartość konfiguracji. Klucz to nazwa pliku. Wartość to zawartość pliku. Dostawca konfiguracji typu „klucz na plik” jest używany w scenariuszach hostingu platformy Docker.

Aby aktywować konfigurację typu „klucz na plik”, wywołaj metodę rozszerzenia AddKeyPerFile w wystąpieniu ConfigurationBuilder. Ścieżka directoryPath do plików musi być ścieżką bezwzględną.

Przeciążenia uniemożliwiają określanie następujących elementów:

  • Delegat Action<KeyPerFileConfigurationSource>, który konfiguruje źródło.
  • Czy katalog jest opcjonalny oraz ścieżka do tego katalogu.

Podwójne podkreślenie (__) jest używane jako ogranicznik klucza konfiguracji w nazwach plików. Na przykład nazwa pliku Logging__LogLevel__System tworzy klucz konfiguracji Logging:LogLevel:System.

Wywołaj ConfigureAppConfiguration podczas kompilowania hosta, aby określić konfigurację aplikacji:

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

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

Dostawca konfiguracji pamięci

Element MemoryConfigurationProvider używa kolekcji w pamięci jako par klucz-wartość konfiguracji.

Poniższy kod dodaje kolekcję pamięci do systemu konfiguracji:

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

W poprzednim kodzie MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) dodaje dostawcę pamięci po domyślnych dostawcach konfiguracji. Aby zapoznać się z przykładem zamawiania dostawców konfiguracji, zobacz Dostawca konfiguracji XML.

Zobacz też