Konfiguráció a .NET-ben

A .NET-ben a konfiguráció egy vagy több konfigurációszolgáltatóval történik. A konfigurációszolgáltatók különböző konfigurációs források használatával olvassák be a kulcs-érték párok konfigurációs adatait:

• Gépház fájlok, például appsettings.json
• Környezeti változók
• Azure Key Vault
• Azure-alkalmazás konfigurációja
• Parancssori argumentumok
• Telepített vagy létrehozott egyéni szolgáltatók
• Címtárfájlok
• Memóriabeli .NET-objektumok
• Külső szolgáltatók

Fogalmak és absztrakciók

Egy vagy több konfigurációs forrás esetén a IConfiguration típus egységes nézetet biztosít a konfigurációs adatokról. A konfiguráció írásvédett, és a konfigurációs minta nem programozott módon írható. Az IConfiguration interfész az összes konfigurációs forrás egyetlen ábrázolása, ahogyan az az alábbi ábrán is látható:

Konzolalkalmazások konfigurálása

A dotnet új parancssablonjával vagy a Visual Studióval létrehozott .NET-konzolalkalmazások alapértelmezés szerint nem teszik elérhetővé a konfigurációs képességeket. Ha új .NET-konzolalkalmazásban szeretne konfigurációt hozzáadni, adjon hozzá egy csomaghivatkozást a Microsoft.Extensions.Configuration fájlhoz. Ez a csomag a .NET-alkalmazások konfigurációjának alapja. Ez biztosítja a kapcsolódó és a ConfigurationBuilder kapcsolódó típusokat.

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

A fenti kód a következőket végzi el:

• Létrehoz egy új ConfigurationBuilder példányt.
• Kulcs-érték párok memóriabeli gyűjteményét adja hozzá a konfigurációszerkesztőhöz.
• Meghívja a Build() metódust egy IConfiguration példány létrehozásához.
• A kulcs értékét SomeKey a konzolra írja.

Bár ez a példa memórián belüli konfigurációt használ, számos konfigurációszolgáltató érhető el, amelyek a fájlalapú, a környezeti változók, a parancssori argumentumok és más konfigurációs források funkcióit tárják fel. További információ: Konfigurációszolgáltatók a .NET-ben.

Alternatív üzemeltetési megközelítés

Az alkalmazások gyakran nem csak olvasási konfigurációt végeznek. Valószínűleg függőséginjektálást, naplózást és egyéb szolgáltatásokat fognak használni. A .NET Generic Host megközelítés ajánlott az ezeket a szolgáltatásokat használó alkalmazások számára. Ehelyett fontolja meg egy csomaghivatkozás hozzáadását a Microsoft.Extensions.Hosting szolgáltatáshoz. Módosítsa a Program.cs fájlt a következő kódnak megfelelően:

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

A Host.CreateApplicationBuilder(String[]) metódus az alkalmazás alapértelmezett konfigurációját a következő sorrendben biztosítja, a legmagasabbtól a legalacsonyabb prioritásig:

1. Parancssori argumentumok a parancssori konfigurációszolgáltató használatával.
2. Környezeti változók a Környezeti változók konfigurációszolgáltató használatával.
3. Alkalmazás titkos kódjai , amikor az alkalmazás a Development környezetben fut.
4. appsettings.json a JSON-konfigurációszolgáltató használatával.
5. appsettings.Environment. json a JSON-konfigurációszolgáltatóval. Például appsettings.Éles környezetben.json és appsettings.Fejlesztés.json.
6. ChainedConfigurationProvider : Meglévőt ad IConfiguration hozzá forrásként.

A konfigurációszolgáltató hozzáadása felülírja a korábbi konfigurációs értékeket. A parancssori konfigurációszolgáltató például felülbírálja a többi szolgáltató összes értékét, mert az utolsóként van hozzáadva. Ha SomeKey mind a appsettings.json, mind a környezetben be van állítva, a rendszer a környezeti értéket használja, mert appsettings.json után lett hozzáadva.

Kötés

A .NET-konfiguráció absztrakcióinak egyik fő előnye, hogy a konfigurációs értékeket a .NET-objektumok példányaihoz köti. A JSON-konfigurációszolgáltató segítségével például leképezhetők appsettings.json fájlok .NET-objektumokra, és függőséginjektálással használhatók. Ez lehetővé teszi a beállítási mintát, amely osztályok használatával biztosít erős hozzáférést a kapcsolódó beállítások csoportjaihoz. A .NET-konfiguráció különböző absztrakciókat biztosít. Vegye figyelembe a következő felületeket:

• IConfiguration: Kulcs/érték alkalmazáskonfigurációs tulajdonságok készletét jelöli.
• IConfigurationRoot: Egy IConfiguration hierarchia gyökerét jelöli.
• IConfigurationSection: Az alkalmazáskonfigurációs értékek egy szakaszát jelöli.

Ezek az absztrakciók a mögöttes konfigurációszolgáltatóIConfigurationProvider () számára agnosztikusak. Más szóval egy IConfiguration példány használatával több szolgáltató bármely konfigurációs értékét elérheti.

A kötőanyag különböző módszerekkel dolgozhatja fel a konfigurációs értékeket:

• Közvetlen deszerializálás (beépített konverterek használatával) primitív típusokhoz.
• Összetett TypeConverter típus esetén, ha a típus rendelkezik ilyen típussal.
• Önkifejezés tulajdonságokat tartalmazó összetett típushoz.

Kötési hierarchiák

A konfigurációs értékek hierarchikus adatokat tartalmazhatnak. A hierarchikus objektumok a határoló használatával : jelennek meg a konfigurációs kulcsokban. A konfigurációs érték eléréséhez használja a : karaktert egy hierarchia elválasztásához. Vegyük például a következő konfigurációs értékeket:

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

Az alábbi táblázat az előző JSON-példához tartozó példakulcsokat és azok megfelelő értékeit jelöli:

Egyszerű példa

Ha alapszintű konfigurációs értékeket szeretne elérni az általános gazdagép-megközelítés segítsége nélkül, használja közvetlenül a típustConfigurationBuilder.

Fontolja meg a következő C#-projektet:

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

Az előző projektfájl több konfigurációs NuGet-csomagra hivatkozik:

• Microsoft.Extensions.Configuration.Binder: Az objektumoknak a konfigurációszolgáltatókban lévő adatokhoz való kötésének Microsoft.Extensions.Configurationfunkciója.
• Microsoft.Extensions.Configuration.Json: JSON-konfigurációszolgáltató implementálása a következőhöz Microsoft.Extensions.Configuration: .
• Microsoft.Extensions.Configuration.EnvironmentVariables: Környezeti változók konfigurációszolgáltatói implementációja a következőhöz Microsoft.Extensions.Configuration: .

Vegyünk egy példát appsettings.json fájlra:

{
    "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"
        ]
    }
}

A JSON-fájl alapján most íme egy példa fogyasztási minta a konfigurációszerkesztő közvetlen használatával:

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

Az előző C# kód:

• Példányosít egy ConfigurationBuilder.
• Hozzáadja a "appsettings.json" JSON-konfigurációszolgáltató által felismerni kívánt fájlt.
• Környezeti változókat ad hozzá a környezeti változók konfigurációszolgáltatója által felismertként.
• A példány használatával lekéri a szükséges "Settings" szakaszt és a megfelelő Settings példányt config .

Az Settings objektum a következőképpen van formázva:

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

Alapszintű példa üzemeltetéssel

Az érték eléréséhez IConfiguration ismét a Microsoft.Extensions.Hosting NuGet-csomagra támaszkodhat. Hozzon létre egy új konzolalkalmazást, és illessze be a következő projektfájl tartalmát:

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

Az előző projektfájl a következőket határozza meg:

• Az alkalmazás végrehajtható.
• A appsettings.json fájlokat a projekt fordításakor a kimeneti könyvtárba kell másolni.
• Ekkor Microsoft.Extensions.Hosting megjelenik a NuGet-csomag referenciája.

Adja hozzá a appsettings.json fájlt a projekt gyökeréhez a következő tartalommal:

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

Cserélje le a Program.cs fájl tartalmát a következő C#-kódra:

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!

Az alkalmazás futtatásakor a Host.CreateApplicationBuilder rendszer meghatározza a JSON-konfiguráció felderítésének és a példányon keresztüli elérhetővé ásának viselkedését IConfiguration . host A példányból kérheti a szolgáltatótól a IConfiguration példányt, majd kérheti az értékeket.

Egyszerű példa az indexelő API üzemeltetésére és használatára

Vegye figyelembe az előző példában szereplő appsettings.json fájl tartalmát:

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

Cserélje le a Program.cs fájl tartalmát a következő C#-kódra:

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

Az értékek az indexelő API-val érhetők el, ahol minden kulcs egy sztring, az érték pedig egy sztring. A konfiguráció támogatja a tulajdonságokat, objektumokat, tömböket és szótárakat.

Konfigurációszolgáltatók

Az alábbi táblázat a .NET Core-alkalmazások számára elérhető konfigurációszolgáltatókat mutatja be.

A különböző konfigurációszolgáltatókról további információt a .NET konfigurációs szolgáltatói című témakörben talál.

Lásd még

• Konfigurációszolgáltatók a .NET-ben
• Egyéni konfigurációszolgáltató implementálása
• Konfigurációs hibákat kell létrehozni a github.com/dotnet/runtime adattárban
• Konfiguráció a ASP.NET Core-ban