Konfigurace v .NET

  • Článek

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

Poznámka:

Informace o konfiguraci samotného modulu runtime .NET naleznete v tématu Nastavení konfigurace modulu runtime .NET.

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:

The `IConfiguration` interface is a single representation of all the configuration sources.

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

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.

Poznámka:

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

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

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:

Key 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 obecného přístupu k hostiteli , použijte ConfigurationBuilder tento typ přímo.

Tip

Typ System.Configuration.ConfigurationBuilder se liší od Microsoft.Extensions.Configuration.ConfigurationBuilder typu. Veškerý tento obsah je specifický pro Microsoft.Extensions.* balíčky NuGet a obory názvů.

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.1" />
    <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:

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

Tip

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

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.

Poskytovatel Poskytuje konfiguraci z
Zprostředkovatel konfigurace Azure App Azure App Configuration
Zprostředkovatel konfigurace služby Azure Key Vault Azure Key Vault
Zprostředkovatel konfigurace v příkazovém řádku Parametry příkazového řádku
Vlastní zprostředkovatel konfigurace Vlastní zdroj
Zprostředkovatel konfigurace pro proměnné prostředí Proměnné prostředí
Zprostředkovatel konfigurace v souboru Soubory JSON, XML a INI
Zprostředkovatele konfigurace „klíč na soubor“ Soubory adresáře
Zprostředkovatel konfigurace v paměti Kolekce v paměti
Tajné kódy aplikací (Secret Manager) Soubor v adresáři profilu uživatele

Tip

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 Poskytovatelé konfigurace v .NET.

Viz také