Konfigurace v .NET

Konfigurace v .NET se provádí pomocí jednoho nebo více zprostředkovatelů konfigurace. Poskytovatelé konfigurace čtou konfigurační data z párů klíč-hodnota pomocí různých zdrojů konfigurace:

• Nastavení soubory, například appsettings.json
• Proměnné prostředí
• Azure Key Vault
• konfigurace Aplikace Azure
• Argumenty příkazového řádku
• Vlastní zprostředkovatelé, nainstalovaní nebo vytvoření
• Soubory adresáře
• Objekty .NET v paměti
• Poskytovatelé třetích stran

Koncepty a abstrakce

Vzhledem k jednomu nebo více zdrojům IConfiguration konfigurace poskytuje typ jednotné zobrazení konfiguračních dat. Konfigurace je jen pro čtení a vzor konfigurace není navržený tak, aby byl programově zapisovatelný. Rozhraní IConfiguration je jedinou reprezentací všech zdrojů konfigurace, jak je znázorněno v následujícím diagramu:

Konfigurace konzolových aplikací

Konzolové aplikace .NET vytvořené pomocí nové šablony příkazů dotnet nebo sady Visual Studio ve výchozím nastavení nezpřístupňují možnosti konfigurace. Chcete-li přidat konfiguraci v nové konzolové aplikaci .NET, přidejte odkaz na balíček Microsoft.Extensions.Configuration. Tento balíček je základem konfigurace v aplikacích .NET. Poskytuje typy ConfigurationBuilder a související typy.

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

Předchozí kód:

• Vytvoří novou instanci sloupce ConfigurationBuilder.
• Přidá kolekci párů klíč-hodnota v paměti do tvůrce konfigurace.
• Zavolá metodu Build() IConfiguration pro vytvoření instance.
• Zapíše hodnotu SomeKey klíče do konzoly.

I když tento příklad používá konfiguraci v paměti, je k dispozici mnoho poskytovatelů konfigurace, které zveřejňují funkce pro souborové proměnné, proměnné prostředí, argumenty příkazového řádku a další zdroje konfigurace. Další informace naleznete v tématu Poskytovatelé konfigurace v .NET.

Alternativní přístup k hostování

Vaše aplikace obvykle dělají víc než jen konfiguraci čtení. Pravděpodobně budou používat injektáž závislostí, protokolování a další služby. Pro aplikace, které tyto služby používají, se doporučuje přístup k obecnému hostiteli .NET. Místo toho zvažte přidání odkazu na balíček microsoft.Extensions.Hosting. Upravte soubor Program.cs tak, aby odpovídal následujícímu kódu:

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

Metoda Host.CreateApplicationBuilder(String[]) poskytuje výchozí konfiguraci aplikace v následujícím pořadí od nejvyšší po nejnižší prioritu:

1. Argumenty příkazového řádku používající zprostředkovatele konfigurace v příkazovém řádku.
2. Proměnné prostředí používající zprostředkovatele konfigurace pro proměnné prostředí.
3. Tajné kódy aplikací, když aplikace běží v prostředí Development.
4. appsettings.json pomocí zprostředkovatele konfigurace JSON.
5. appsettings.Environment. Json s použitím zprostředkovatele konfigurace JSON Například nastavení aplikace.Produkce.json a appsettings.Vývoj.json.
6. ChainedConfigurationProvider: Přidá existující IConfiguration jako zdroj.

Přidání zprostředkovatele konfigurace přepíše předchozí hodnoty konfigurace. Například zprostředkovatel konfigurace příkazového řádku přepíše všechny hodnoty od ostatních zprostředkovatelů, protože je přidán jako poslední. Pokud SomeKey je nastavena v appsettings.json i prostředí, použije se hodnota prostředí, protože byla přidána po appsettings.json.

Vazba

Jednou z klíčových výhod použití abstrakcí konfigurace .NET je možnost svázat konfigurační hodnoty s instancemi objektů .NET. Například zprostředkovatel konfigurace JSON lze použít k mapování appsettings.json souborů na objekty .NET a používá se s injektáží závislostí. To umožňuje vzor možností, který používá třídy k poskytování přístupu silného typu ke skupinám souvisejících nastavení. Konfigurace .NET poskytuje různé abstrakce. Zvažte následující rozhraní:

• IConfiguration: Představuje sadu vlastností konfigurace aplikace klíč/hodnota.
• IConfigurationRoot: Představuje kořen IConfiguration hierarchie.
• IConfigurationSection: Představuje část hodnot konfigurace aplikace.

Tyto abstrakce jsou nezávislé na příslušném poskytovateli konfigurace (IConfigurationProvider). Jinými slovy můžete použít IConfiguration instanci pro přístup k libovolné hodnotě konfigurace od více poskytovatelů.

Pořadač může použít různé přístupy ke zpracování hodnot konfigurace:

• Přímá deserializace (pomocí integrovaných převaděčů) pro primitivní typy
• Typ TypeConverter pro komplexní typ, pokud ho má.
• Reflexe pro komplexní typ, který má vlastnosti.

Hierarchie vazeb

Hodnoty konfigurace můžou obsahovat hierarchická data. Hierarchické objekty jsou reprezentovány použitím oddělovače v konfiguračních : klíčích. Pokud chcete získat přístup k hodnotě konfigurace, použijte : znak k oddělení hierarchie. Představte si například následující hodnoty konfigurace:

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

Následující tabulka představuje ukázkové klíče a jejich odpovídající hodnoty pro předchozí příklad JSON:

Základní příklad

Pokud chcete získat přístup k hodnotám konfigurace v jejich základní podobě bez pomoci obecného přístupu k hostiteli , použijte ConfigurationBuilder tento typ přímo.

Představte si následující projekt jazyka 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>

Předchozí soubor projektu odkazuje na několik konfiguračních balíčků NuGet:

• Microsoft.Extensions.Configuration.Binder: Funkce pro vytvoření vazby objektu k datům v zprostředkovatelích konfigurace pro Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.Json: Implementace zprostředkovatele konfigurace JSON pro Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.EnvironmentVariables: Implementace zprostředkovatele konfigurace proměnných prostředí pro Microsoft.Extensions.Configuration.

Podívejte se na příklad souboru 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"
        ]
    }
}

Vzhledem k tomuto souboru JSON je tady příklad způsobu spotřeby, který přímo používá tvůrce konfigurace:

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

Předchozí kód jazyka C#:

• ConfigurationBuilderVytvoří instanci .
• "appsettings.json" Přidá soubor, který bude rozpoznán poskytovatelem konfigurace JSON.
• Přidá proměnné prostředí jako rozpoznané zprostředkovatelem konfigurace proměnné prostředí.
• Získá požadovaný "Settings" oddíl a odpovídající Settings instanci pomocí config instance.

Objekt Settings je tvarován následujícím způsobem:

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!;
}

Základní příklad s hostování

Pokud chcete získat přístup k hodnotě IConfiguration , můžete znovu spoléhat na Microsoft.Extensions.Hosting balíček NuGet. Vytvořte novou konzolovou aplikaci a vložte do ní následující obsah souboru 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>

Předchozí soubor projektu definuje, že:

• Aplikace je spustitelný soubor.
• Při kompilaci projektu se do výstupního adresáře zkopíruje soubor appsettings.json .
• Přidá se odkaz na Microsoft.Extensions.Hosting balíček NuGet.

Do kořenového adresáře projektu přidejte soubor appsettings.json s následujícím obsahem:

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

Obsah souboru Program.cs nahraďte následujícím kódem jazyka 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!

Při spuštění této aplikace Host.CreateApplicationBuilder definuje chování zjišťování konfigurace JSON a její zveřejnění prostřednictvím IConfiguration instance. host Z instance můžete požádat poskytovatele služeb o IConfiguration instanci a pak požádat o hodnoty.

Základní příklad s hostováním a používáním rozhraní API indexeru

Vezměte v úvahu stejný obsah souboru appsettings.json z předchozího příkladu:

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

Obsah souboru Program.cs nahraďte následujícím kódem jazyka 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

K hodnotám se přistupuje pomocí rozhraní API indexeru, kde každý klíč je řetězec a hodnota je řetězec. Konfigurace podporuje vlastnosti, objekty, pole a slovníky.

Poskytovatelé konfigurace

Následující tabulka ukazuje poskytovatele konfigurace, kteří jsou k dispozici pro aplikace .NET Core.

Další informace o různých poskytovatelích konfigurace naleznete v tématu Poskytovatelé konfigurace v .NET.

Viz také

• Zprostředkovatelé konfigurace v .NET
• Implementace vlastního zprostředkovatele konfigurace
• V úložišti github.com/dotnet/runtime by se měly vytvořit chyby konfigurace.
• Konfigurace v ASP.NET Core