Konfiguracja na platformie .NET

Artykuł
03/01/2024

Konfiguracja na platformie .NET jest wykonywana przy użyciu co najmniej jednego dostawcy konfiguracji. Dostawcy konfiguracji odczytują dane konfiguracji z par klucz-wartość przy użyciu różnych źródeł konfiguracji:

Ustawienia plików, takich jak appsettings.json
Zmienne środowiskowe
Azure Key Vault
Konfiguracja aplikacja systemu Azure
Argumenty wiersza polecenia
Dostawcy niestandardowi, zainstalowani lub utworzeni
Pliki katalogów
Obiekty platformy .NET w pamięci
Dostawcy innych firm

Uwaga

Aby uzyskać informacje na temat konfigurowania samego środowiska uruchomieniowego platformy .NET, zobacz Ustawienia konfiguracji środowiska uruchomieniowego platformy .NET.

Pojęcia i abstrakcje

Biorąc pod uwagę co najmniej jedno źródło konfiguracji, IConfiguration typ zapewnia ujednolicony widok danych konfiguracji. Konfiguracja jest tylko do odczytu, a wzorzec konfiguracji nie jest przeznaczony do programowego zapisu. Interfejs IConfiguration jest pojedynczą reprezentacją wszystkich źródeł konfiguracji, jak pokazano na poniższym diagramie:

Konfigurowanie aplikacji konsoli

Aplikacje konsolowe platformy .NET utworzone przy użyciu nowego szablonu polecenia dotnet lub programu Visual Studio domyślnie nie uwidaczniają możliwości konfiguracji. Aby dodać konfigurację w nowej aplikacji konsolowej platformy .NET, dodaj odwołanie do pakietu Microsoft.Extensions.Configuration. Ten pakiet jest podstawą konfiguracji w aplikacjach platformy .NET. Udostępnia on ConfigurationBuilder powiązane typy i .

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

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

Tworzy nowe wystąpienie klasy ConfigurationBuilder.
Dodaje do konstruktora konfiguracji kolekcję par klucz-wartość w pamięci.
Wywołuje metodę Build() w celu utworzenia IConfiguration wystąpienia.
Zapisuje wartość SomeKey klucza w konsoli.

W tym przykładzie użyto konfiguracji w pamięci, ale dostępnych jest wielu dostawców konfiguracji, udostępniając funkcje oparte na plikach, zmiennych środowiskowych, argumentów wiersza polecenia i innych źródeł konfiguracji. Aby uzyskać więcej informacji, zobacz Dostawcy konfiguracji na platformie .NET.

Alternatywne podejście do hostingu

Często aplikacje wykonują więcej niż tylko konfigurację odczytu. Prawdopodobnie będą używać wstrzykiwania zależności, rejestrowania i innych usług. Podejście do hosta ogólnego platformy .NET jest zalecane w przypadku aplikacji korzystających z tych usług. Zamiast tego rozważ dodanie odwołania do pakietu do microsoft.Extensions.Hosting. Zmodyfikuj plik Program.cs, aby był zgodny z następującym kodem:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Metoda Host.CreateApplicationBuilder(String[]) zapewnia domyślną konfigurację aplikacji w następującej kolejności, od najwyższego do najniższego priorytetu:

Argumenty wiersza polecenia, które korzystają z dostawcy konfiguracji wiersza polecenia.
Zmienne środowiskowe korzystające z dostawcy konfiguracji zmiennych środowiskowych.
Wpisy tajne aplikacji w przypadku aplikacji działającej w środowisku Development.
appsettings.json przy użyciu dostawcy konfiguracji JSON.
appsettings.Environment. json przy użyciu dostawcy konfiguracji JSON. Na przykład appsettings.Produkcja.json i appsettings. Programowanie.json.
ChainedConfigurationProvider: dodaje istniejący element IConfiguration jako źródło.

Dodanie dostawcy konfiguracji zastępuje poprzednie wartości konfiguracji. Na przykład dostawca konfiguracji wiersza polecenia zastępuje wszystkie wartości innych dostawców, ponieważ jest on dodawany ostatnio. Jeśli SomeKey wartość jest ustawiona zarówno w appsettings.json, jak i w środowisku, zostanie użyta wartość środowiska, ponieważ została dodana po appsettings.json.

Wiązanie

Jedną z kluczowych zalet korzystania z abstrakcji konfiguracji platformy .NET jest możliwość powiązania wartości konfiguracji z wystąpieniami obiektów platformy .NET. Na przykład dostawca konfiguracji JSON może służyć do mapowania plików appsettings.json na obiekty platformy .NET i jest używany z wstrzyknięciem zależności. Umożliwia to wzorzec opcji, który używa klas w celu zapewnienia silnie typizowanego dostępu do grup powiązanych ustawień. Konfiguracja platformy .NET zapewnia różne abstrakcje. Rozważ następujące interfejsy:

IConfiguration: reprezentuje zestaw właściwości konfiguracji aplikacji klucz/wartość.
IConfigurationRoot: reprezentuje katalog główny IConfiguration hierarchii.
IConfigurationSection: reprezentuje sekcję wartości konfiguracji aplikacji.

Te abstrakcje są niezależne od podstawowego dostawcy konfiguracji (IConfigurationProvider). Innymi słowy, możesz użyć IConfiguration wystąpienia, aby uzyskać dostęp do dowolnej wartości konfiguracji od wielu dostawców.

Binder może używać różnych metod przetwarzania wartości konfiguracji:

Deserializacja bezpośrednia (przy użyciu wbudowanych konwerterów) dla typów pierwotnych.
Dla TypeConverter typu złożonego, gdy typ ma jeden.
Emocje ion dla typu złożonego, który ma właściwości.

Uwaga

Powiązanie ma kilka ograniczeń:

Właściwości są ignorowane, jeśli nie można przekonwertować prywatnych zestawów lub ich typu.
Właściwości bez odpowiednich kluczy konfiguracji są ignorowane.

Hierarchie powiązań

Wartości konfiguracji mogą zawierać dane hierarchiczne. Obiekty hierarchiczne są reprezentowane przy użyciu : ogranicznika w kluczach konfiguracji. Aby uzyskać dostęp do wartości konfiguracji, użyj : znaku , aby rozdzielić hierarchię. Rozważmy na przykład następujące wartości konfiguracji:

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

W poniższej tabeli przedstawiono przykładowe klucze i odpowiadające im wartości dla poprzedniego przykładowego kodu JSON:

Key	Wartość
`"Parent:FavoriteNumber"`	`7`
`"Parent:Child:Name"`	`"Example"`
`"Parent:Child:GrandChild:Age"`	`3`

Przykład podstawowy

Aby uzyskać dostęp do wartości konfiguracji w ich podstawowej formie, bez pomocy ogólnego podejścia hosta , użyj ConfigurationBuilder typu bezpośrednio.

Napiwek

Typ System.Configuration.ConfigurationBuilder różni się od Microsoft.Extensions.Configuration.ConfigurationBuilder typu. Cała ta zawartość jest specyficzna dla Microsoft.Extensions.* pakietów NuGet i przestrzeni nazw.

Rozważmy następujący projekt w języku C#:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="8.0.2" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </ItemGroup>

</Project>

Powyższy plik projektu odwołuje się do kilku pakietów NuGet konfiguracji:

Microsoft.Extensions.Configuration.Binder: Funkcja powiązania obiektu z danymi u dostawców konfiguracji dla programu Microsoft.Extensions.Configuration.
Microsoft.Extensions.Configuration.Json: implementacja dostawcy konfiguracji JSON dla programu Microsoft.Extensions.Configuration.
Microsoft.Extensions.Configuration.EnvironmentVariables: Implementacja dostawcy konfiguracji zmiennych środowiskowych dla programu Microsoft.Extensions.Configuration.

Rozważmy przykładowy plik appsettings.json :

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

Teraz, biorąc pod uwagę ten plik JSON, oto przykładowy wzorzec zużycia bezpośrednio przy użyciu konstruktora konfiguracji:

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

Poprzedni kod języka C#:

Tworzy wystąpienie elementu ConfigurationBuilder.
"appsettings.json" Dodaje plik do rozpoznawania przez dostawcę konfiguracji JSON.
Dodaje zmienne środowiskowe jako rozpoznawane przez dostawcę konfiguracji zmiennej środowiskowej.
Pobiera wymaganą "Settings" sekcję i odpowiednie Settings wystąpienie przy użyciu config wystąpienia.

Obiekt Settings jest kształtowany w następujący sposób:

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Podstawowy przykład hostingu

Aby uzyskać dostęp do IConfiguration wartości, możesz ponownie polegać na pakiecie Microsoft.Extensions.Hosting NuGet. Utwórz nową aplikację konsolową i wklej do niej następującą zawartość pliku projektu:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="8.0.2" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>

</Project>

Powyższy plik projektu definiuje następujące elementy:

Aplikacja jest plikiem wykonywalnym.
Plik appsettings.json ma zostać skopiowany do katalogu wyjściowego podczas kompilowania projektu.
Dodano Microsoft.Extensions.Hosting odwołanie do pakietu NuGet.

Dodaj plik appsettings.json w katalogu głównym projektu z następującą zawartością:

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Zastąp zawartość pliku Program.cs następującym kodem c#:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

Po uruchomieniu tej aplikacji Host.CreateApplicationBuilder definiuje zachowanie w celu odnajdywania konfiguracji JSON i uwidaczniania jej za pośrednictwem IConfiguration wystąpienia. W wystąpieniu host możesz poprosić dostawcę usług o IConfiguration wystąpienie, a następnie poprosić go o wartości.

Napiwek

Użycie pierwotnego IConfiguration wystąpienia w ten sposób, choć wygodne, nie jest bardzo dobrze skalowane. Gdy aplikacje stają się coraz bardziej złożone, a ich odpowiednie konfiguracje stają się bardziej złożone, zalecamy użycie wzorca opcji jako alternatywy.

Podstawowy przykład hostowania i używania interfejsu API indeksatora

Rozważ tę samą zawartość pliku appsettings.json z poprzedniego przykładu:

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Zastąp zawartość pliku Program.cs następującym kodem c#:

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

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Do wartości uzyskuje się dostęp przy użyciu interfejsu API indeksatora, w którym każdy klucz jest ciągiem, a wartość jest ciągiem. Konfiguracja obsługuje właściwości, obiekty, tablice i słowniki.

Dostawcy konfiguracji

W poniższej tabeli przedstawiono dostawców konfiguracji dostępnych dla aplikacji platformy .NET Core.

Dostawca	Dostarcza konfigurację z
Dostawca konfiguracji aplikacji platformy Azure	Azure App Configuration
Dostawca konfiguracji usługi Azure Key Vault	Azure Key Vault
Dostawca konfiguracji wiersza polecenia	Parametry wiersza polecenia
Niestandardowy dostawca konfiguracji	Źródło niestandardowe
Dostawca konfiguracji zmiennych środowiskowych	Zmienne środowiskowe
Dostawca konfiguracji plików	Pliki JSON, XML i INI
Dostawca konfiguracji typu „klucz na plik”	Pliki katalogów
Dostawca konfiguracji pamięci	Kolekcje w pamięci
Wpisy tajne aplikacji (Secret Manager)	Plik w katalogu profilów użytkownika

Napiwek

Kolejność dodawania dostawców konfiguracji ma znaczenie. Jeśli jest używanych wielu dostawców konfiguracji i więcej niż jeden dostawca określa ten sam klucz, zostanie użyty ostatni dodany.

Aby uzyskać więcej informacji na temat różnych dostawców konfiguracji, zobacz Dostawcy konfiguracji na platformie .NET.

Zobacz też

Dostawcy konfiguracji na platformie .NET
Implementowanie niestandardowego dostawcy konfiguracji
Błędy konfiguracji należy utworzyć w repozytorium github.com/dotnet/runtime
Konfiguracja w programie ASP.NET Core

Udostępnij za pośrednictwem

Konfiguracja na platformie .NET

Pojęcia i abstrakcje

Konfigurowanie aplikacji konsoli

Alternatywne podejście do hostingu

Wiązanie

Hierarchie powiązań

Przykład podstawowy

Podstawowy przykład hostingu

Podstawowy przykład hostowania i używania interfejsu API indeksatora

Dostawcy konfiguracji

Zobacz też

Dodatkowe zasoby