Udostępnij za pośrednictwem

Konfiguracja na platformie .NET

Konfiguracja na platformie .NET jest wykonywana przy użyciu co najmniej jednego dostawcy konfiguracji . Configuration providers read configuration data from key-value pairs using various configuration sources:

  • Pliki ustawień, takie jak appsettings.json
  • Zmienne środowiskowe
  • Azure Key Vault
  • Konfiguracja aplikacji Azure
  • Command-line arguments
  • Dostawcy niestandardowi, zainstalowani lub utworzeni
  • Pliki katalogów
  • Obiekty .NET w pamięci
  • Zewnętrzni dostawcy

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, typ IConfiguration 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:

Interfejs

Konfigurowanie aplikacji konsoli

Aplikacje konsolowe platformy .NET utworzone za pomocą polecenia dotnet new lub Visual Studio domyślnie nie zapewniają możliwości konfiguracji. To add configuration in a new .NET console application, add a package reference to Microsoft.Extensions.Configuration. Ten pakiet jest podstawą konfiguracji w aplikacjach platformy .NET. It provides the ConfigurationBuilder and related types.

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:

  • Creates a new ConfigurationBuilder instance.
  • Dodaje do modułu konfiguracyjnego kolekcję par klucz-wartość przechowywaną w pamięci.
  • Wywołuje metodę Build() w celu utworzenia wystąpienia IConfiguration.
  • Zapisuje wartość klucza SomeKey do 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. For more information, see Configuration providers in .NET.

Alternatywne podejście do hostingu

Często twoje aplikacje robią więcej niż tylko odczytywanie konfiguracji. They'll likely use dependency injection, logging, and other services. The .NET Generic Host approach is recommended for apps that use these services. 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:

  1. Command-line arguments using the Command-line configuration provider.
  2. Zmienne środowiskowe przy użyciu dostawcy konfiguracji zmiennych środowiskowych .
  3. Sekrety aplikacji, gdy aplikacja działa w środowisku Development.
  4. appsettings.json using the JSON configuration provider.
  5. ustawienia aplikacji.Environment.json przy użyciu dostawcy konfiguracji JSON . Na przykład appsettings.Production.json i appsettings.Development.json.
  6. ChainedConfigurationProvider : Adds an existing IConfiguration as a source.

Dodanie dostawcy konfiguracji zastępuje poprzednie wartości konfiguracji. For example, the Command-line configuration provider overrides all values from other providers because it's added last. Jeśli SomeKey jest ustawiona zarówno w appsettings.json, jak i w środowisku, zostanie użyta wartość środowiska, ponieważ została dodana po appsettings.json.

Binding

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 wstrzykiwaniem zależności. This enables the options pattern, which uses classes to provide strongly typed access to groups of related settings. Domyślny binder jest oparty na odbiciu, ale istnieje generator źródła alternatywny, który jest łatwy do włączenia.

Konfiguracja platformy .NET zapewnia różne abstrakcje. Rozważ następujące interfejsy:

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

The binder can use different approaches to process configuration values:​

  • Deserializacja bezpośrednia (przy użyciu wbudowanych konwerterów) dla typów pierwotnych.
  • The TypeConverter for a complex type when the type has one​.
  • Reflection for a complex type that has properties.

Uwaga

The binder has a few limitations:

  • Properties are ignored if they have private setters or their type can't be converted.
  • Właściwości bez odpowiednich kluczy konfiguracji są ignorowane.

Binding hierarchies

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 metody ogólnego hosta, użyj typu ConfigurationBuilder bezpośrednio.

Tip

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

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="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.6" />
  </ItemGroup>

</Project>

Poprzedni plik projektu odwołuje się do kilku pakietów NuGet do konfiguracji.

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

  • Instantiates a ConfigurationBuilder.
  • Dodaje plik "appsettings.json" do rozpoznawania przez dostawcę konfiguracji JSON.
  • Dodaje zmienne środowiskowe rozpoznawane przez dostawcę konfiguracji zmiennych środowiskowych.
  • Gets the required "Settings" section and the corresponding Settings instance by using the config instance.

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 wartości IConfiguration, możesz ponownie opierać się 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="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.6" />
  </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 odwołanie do pakietu NuGet Microsoft.Extensions.Hosting.

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 wystąpienia IConfiguration. From the host instance, you can ask the service provider for the IConfiguration instance and then ask it for values.

Tip

Using the raw IConfiguration instance in this way, while convenient, doesn't scale very well. 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 Provides configuration from
dostawcy konfiguracji aplikacji platformy Azure Konfiguracja aplikacji Azure
dostawcy konfiguracji usługi Azure Key Vault Azure Key Vault
Command-line configuration provider Parametry wiersza polecenia
Custom configuration provider Źródło niestandardowe
dostawca konfiguracji zmiennych środowiskowych Zmienne środowiskowe
File configuration provider Pliki JSON, XML i INI
Dostawca konfiguracji typu klucz-na-plik Pliki katalogów
Dostawca konfiguracji pamięci Kolekcje przechowywane w pamięci
Tajne dane aplikacji (Secret Manager) Plik w katalogu profilu użytkownika

Tip

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ż