Sdílet prostřednictvím

Konfigurace v .NET

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

  • Soubory nastavení, 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ářů
  • Objekty .NET v paměti
  • Poskytovatelé třetích stran

Poznámka

Informace o konfiguraci samotného modulu runtime .NET najdete v tématu nastavení konfigurace modulu runtime .NET.

Koncepty a abstrakce

Vzhledem k jednomu nebo více zdrojům konfigurace poskytuje typ IConfiguration 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:

rozhraní IConfiguration je jediné znázornění všech zdrojů konfigurace.

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íčekMicrosoft.Extensions.Configuration📦. Tento balíček je základem konfigurace v aplikacích .NET. Poskytuje 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 ConfigurationBuilder.
  • Přidá do konfigurátoru kolekci párů klíč-hodnota uloženou v paměti.
  • Zavolá metodu Build() k vytvoření instance IConfiguration.
  • Zapíše hodnotu klíče SomeKey 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 rozhraní .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í, logování a další služby. Pro aplikace, které používají tyto služby, se doporučuje .NET Generic Host. 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žitím zprostředkovatele konfigurace příkazového řádku.
  2. Proměnné prostředí využívající konfiguračního zprostředkovatele proměnných prostředí .
  3. tajemství aplikace, když aplikace běží v prostředí Development.
  4. nastavení aplikace.Environment.json pomocí zprostředkovatele konfigurace JSON. Například nastavení aplikace.Produkční. json a appsettings.vývoj.json.
  5. appsettings.json pomocí zprostředkovatele konfigurace 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 poskytovatel konfigurace příkazového řádku přepíše všechny ostatní hodnoty, jelikož byl přidán jako poslední. Pokud je SomeKey nastaven v appsettings.json i v prostředí, použije se hodnota prostředí, protože byla přidána po appsettings.json.

Závazný

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 poskytovatel konfigurace JSON lze použít k mapování appsettings.json souborů na objekty .NET a používá se s vkládáním závislostí. Toto umožňuje vzorec možností , který používá třídy pro zajištění typově silného přístupu ke skupinám souvisejících nastavení. Výchozí pořadač je založený na reflexi, ale existuje alternativa generátoru zdroje, který se dá snadno povolit.

Konfigurace .NET poskytuje různé abstrakce. Zvažte následující rozhraní:

Tyto abstrakce jsou nezávislé na příslušném poskytovateli konfigurace (IConfigurationProvider). Jinými slovy, můžete použít instanci IConfiguration 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
  • TypeConverter pro komplexní typ, když má typ jeden.
  • Odraz komplexního typu, který má vlastnosti.

Poznámka

Pořadač má několik omezení:

  • Vlastnosti jsou ignorovány, pokud mají soukromý nastavovač nebo jejich typ nelze převést.
  • Vlastnosti bez odpovídajících konfiguračních klíčů se ignorují.

Hierarchické vazby

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:

Klíč Hodnota
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Pokročilé scénáře vazeb

Při práci s určitými typy má konfigurační vazba specifické chování a omezení. Tato část obsahuje následující pododdíly:

Vytvoření vazby ke slovníkům

Když vytvoříte vazbu konfigurace na Dictionary<TKey,TValue>, kde je hodnota proměnlivým typem kolekce (jako jsou pole nebo seznamy), opakované vazby na stejný klíč rozšiřují hodnoty kolekce, namísto aby je nahradily.

Následující příklad ukazuje toto chování:

IConfiguration config = new ConfigurationBuilder()
    .AddInMemoryCollection()
    .Build();

config["Queue:0"] = "Value1";
var dict = new Dictionary<string, string[]>() { { "Queue", new[] { "InitialValue" } } };

Console.WriteLine("=== Dictionary Binding with Collection Values ===");
Console.WriteLine($"Initially: {string.Join(", ", dict["Queue"])}");

// In .NET 7+, binding extends the collection instead of replacing it.
config.Bind(dict);
Console.WriteLine($"After Bind: {string.Join(", ", dict["Queue"])}");

config["Queue:1"] = "Value2";
config.Bind(dict);
Console.WriteLine($"After 2nd Bind: {string.Join(", ", dict["Queue"])}");

Další informace naleznete v tématu Konfigurace vazby na slovník rozšiřuje hodnoty.

Klíče slovníku s dvojtečkami

Dvojtečka (:) je vyhrazena jako oddělovač hierarchie v konfiguračních klíčích. To znamená, že při konfiguraci vazby nemůžete použít dvojtečky v klíčích slovníku. Pokud klíče obsahují dvojtečky (například adresy URL nebo jiné formátované identifikátory), konfigurační systém je interpretuje jako cesty hierarchie místo literálových znaků. Zvažte následující alternativní řešení:

  • V konfiguračních klíčích __použijte alternativní znaky oddělovače (například dvojité podtržítka) a v případě potřeby je transformujte programově.
  • Ručně deserializujte konfiguraci jako surový JSON pomocí System.Text.Json nebo podobné knihovny, která podporuje dvojtečky v klíčích.
  • Vytvořte vlastní vrstvu mapování, která přeloží bezpečné klíče na požadované klíče s dvojtečkami.

Vytvoření vazby k typům IReadOnly*

Pořadač konfigurace nepodporuje vazbu přímo na IReadOnlyList<T>, IReadOnlyDictionary<TKey, TValue> nebo jiné rozhraní kolekcí pouze pro čtení. Tato rozhraní nemají mechanismy, které pořadač potřebuje k naplnění kolekcí.

Pokud chcete pracovat s kolekcemi jen pro čtení, použijte pro vlastnosti, které pořadač naplní, proměnlivé typy a pak je vystavit jako rozhraní jen pro čtení pro uživatele:

Console.WriteLine("=== IReadOnly* Types (NOT Directly Supported) ===");

var readonlyConfig = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["Settings:Values:0"] = "Item1",
        ["Settings:Values:1"] = "Item2",
        ["Settings:Values:2"] = "Item3",
    })
    .Build();

// This class uses List<string> for binding, exposes as IReadOnlyList<string>.
var settings = new SettingsWithReadOnly();
readonlyConfig.GetSection("Settings").Bind(settings);

Console.WriteLine("Values bound to mutable List, exposed as IReadOnlyList:");
foreach (var value in settings.ValuesReadOnly)
{
    Console.WriteLine($"  {value}");
}

Implementace třídy konfigurace:

class SettingsWithReadOnly
{
    // Use mutable type for binding
    public List<string> Values { get; set; } = [];

    // Expose as read-only for consumers
    public IReadOnlyList<string> ValuesReadOnly => Values;
}

Tento přístup umožňuje vazači naplnit proměnné List<string> zatímco prezentuje neměnné rozhraní příjemcům prostřednictvím IReadOnlyList<string>.

Vytvoření vazby s parametrizovanými konstruktory

Počínaje rozhraním .NET 7 podporuje binder konfigurace vazby na typy s jedním veřejně parametrizovaným konstruktorem. To umožňuje naplnit neměnné typy a záznamy přímo z konfigurace:

Console.WriteLine("=== Parameterized Constructor Binding ===");

var ctorConfig = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["AppSettings:Name"] = "MyApp",
        ["AppSettings:MaxConnections"] = "100",
        ["AppSettings:Timeout"] = "30"
    })
    .Build();

// Binding to a type with a single parameterized constructor
var appSettings = ctorConfig.GetSection("AppSettings").Get<AppSettings>();
if (appSettings != null)
{
    Console.WriteLine($"Name: {appSettings.Name}");
    Console.WriteLine($"MaxConnections: {appSettings.MaxConnections}");
    Console.WriteLine($"Timeout: {appSettings.Timeout}");
}

Neměnná třída nastavení:

// Immutable type with single parameterized constructor.
class AppSettings
{
    public string Name { get; }
    public int MaxConnections { get; }
    public int Timeout { get; }

    public AppSettings(string name, int maxConnections, int timeout)
    {
        Name = name;
        MaxConnections = maxConnections;
        Timeout = timeout;
    }
}

Důležité

Vazač podporuje pouze typy s jedním veřejným parametrizovaným konstruktorem. Pokud má typ více veřejných parametrizovaných konstruktorů, binder nemůže určit, který z nich se má použít, a vazba selže. Použijte buď jediný parametrizovaný konstruktor, nebo konstruktor bez parametrů s nastavovači vlastností.

Základní příklad

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

Spropitné

Typ System.Configuration.ConfigurationBuilder se liší od typu Microsoft.Extensions.Configuration.ConfigurationBuilder. Tento obsah se týká balíčků NuGet a oborů názvů specifických pro Microsoft.Extensions.*.

Představte si následující projekt jazyka C#:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.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="10.0.3" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.3" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.3" />
  </ItemGroup>

</Project>

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

Představte si 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#:

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

Objekt Settings má tvar 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 balíček NuGet Microsoft.Extensions.Hosting. 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>net10.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="10.0.3" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.3" />
  </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 balíček NuGet Microsoft.Extensions.Hosting.

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 jeho zveřejnění prostřednictvím instance IConfiguration. Z instance host můžete požádat poskytovatele služeb o instanci IConfiguration a pak ji požádat o hodnoty.

Spropitné

Použití nezpracované instance IConfiguration tímto způsobem, i když je to pohodlné, se neškáluje příliš dobře. Když se aplikace zvětšují a jejich odpovídající konfigurace jsou složitější, doporučujeme použít vzor možností jako alternativu.

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.

Zprostředkovatelé konfigurace

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

Zprostředkovatel konfigurace Poskytuje konfiguraci z
konfigurace Aplikace Azure Azure App Configuration
Azure Key Vault Azure Key Vault
příkazového řádku Parametry příkazového řádku
na míru Vlastní zdroj
Proměnné prostředí Proměnné prostředí
File Soubory JSON, XML a INI
Klíč na soubor Soubory adresářů
Paměť Kolekce v paměti
Tajné kódy aplikací (správce tajných kódů) Soubor v adresáři profilu uživatele

Spropitné

Záleží na pořadí, ve kterém jsou poskytovatelé konfigurace přidáni. Pokud se používá více zprostředkovatelů konfigurace a více než jeden zprostředkovatel určuje stejný klíč, použije se poslední přidaný klíč.

Další informace o různých poskytovatelích konfigurace naleznete v tématu Konfigurační zprostředkovatelé v rozhraní .NET.

Viz také

  • Last updated on