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
  • Azure App Configuration
  • Argumenty příkazového řádku
  • Vlastní poskytovatelé, 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řidat odkaz na balíček do Microsoft.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řidat referenci na balíček do 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. appsettings.json pomocí zprostředkovatele konfigurace JSON .
  5. nastavení aplikace.Environment.json pomocí zprostředkovatele konfigurace JSON. Například nastavení aplikace.Produkční. 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 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

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

Poskytovatel Poskytuje konfiguraci z
Azure poskytovatel konfigurace aplikace Azure App Configuration
poskytovatele konfigurace služby Azure Key Vault Azure Key Vault
Poskytovatel konfigurace příkazového řádku Parametry příkazového řádku
poskytovatel vlastního nastavení konfigurace Vlastní zdroj
Poskytovatel konfigurace proměnných prostředí Proměnné prostředí
Poskytovatel konfigurace souborů Soubory JSON, XML a INI
Poskytovatel konfigurace klíč na soubor Soubory adresářů
poskytovatel konfigurace paměti Kolekce v paměti
Tajné údaje aplikace (Správce tajných údajů) 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