Megosztás a következőn keresztül:

Konfiguráció a .NET-ben

A .NET-ben a konfigurálást egy vagy több konfigurációszolgáltatósegítségével végezzük. 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:

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

Jegyzet

A .NET-futtatókörnyezet konfigurálásával kapcsolatos információkért lásd .NET futtatókörnyezet konfigurációs beállításait.

Fogalmak és absztrakciók

Egy vagy több konfigurációs forrás miatt 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ó. A IConfiguration felület az összes konfigurációs forrás egyetlen ábrázolása, ahogyan az alábbi ábrán látható:

Az IConfiguration felület az összes konfigurációs forrás egyetlen ábrázolása.

Konzolalkalmazások konfigurálása

A dotnet új parancssablon vagy a Visual Studio használatával létrehozott .NET-konzolalkalmazások alapértelmezés szerint nem kínálnak konfigurációs lehetőségeket. Ha új .NET-konsole alkalmazásban szeretne konfigurációt hozzáadni, adjon hozzá egy csomaghivatkozástMicrosoft.Extensions.Configuration. Ez a csomag a .NET-alkalmazások konfigurációjának alapja. Ez biztosítja a ConfigurationBuilder és a 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

Az előző kód:

  • 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 SomeKey kulcs értékét írja a konzolra.

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 azoknak az alkalmazásoknak, amelyek ezeket a szolgáltatásokat használják. Ehelyett fontolja meg egy csomag hivatkozásának hozzáadását a Microsoft.Extensions.Hosting-hez. 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óval.
  2. Környezeti változók a konfigurációszolgáltatón keresztül.
  3. alkalmazás titkai, amikor az alkalmazás a Development környezetben fut.
  4. alkalmazásbeállításokat.Environment.json a JSON-konfigurációszolgáltató használatával. Például appsettings.Éles.json és appsettings.Fejlesztési.json.
  5. appsettings.json a JSON konfiguráció szolgáltatóhasználatával.
  6. ChainedConfigurationProvider: Meglévő IConfiguration-et ad hozzá forrásként.

A konfigurációszolgáltató hozzáadása felülírja a korábbi konfigurációs értékeket. Például a parancssori konfigurációszolgáltató felülbírálja a többi szolgáltató összes értékét, mert az utolsóként van hozzáadva. Ha a SomeKey be van állítva mind a appsettings.json-ben, mind a környezetben, akkor a környezeti érték kerül használatra, mert a appsettings.jsonután került hozzáadásra.

Kötelezettség

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ó például felhasználható arra, hogy appsettings.json fájlokat .NET-objektumokra képezzünk le és függőséginjektálással használják. Ez lehetővé teszi a beállításmintát, amely osztályok alkalmazásával biztosít erős típusú hozzáférést a kapcsolódó beállítások csoportjaihoz. Az alapértelmezett kötő reflexióalapú, de létezik egy forrásgenerátor alternatíva, amely könnyen engedélyezhető.

A .NET-konfiguráció különböző absztrakciókat biztosít. Vegye figyelembe a következő felületeket:

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 típusok esetén a TypeConverter, ha a típus rendelkezik ilyennel.
  • Tulajdonságokkal rendelkező összetett típus tükröződése.

Jegyzet

A kötőanyag néhány korlátozással rendelkezik:

  • A tulajdonságok figyelmen kívül lesznek hagyva, ha privát beállítóik vannak, vagy a típusuk nem konvertálható.
  • A megfelelő konfigurációs kulcsok nélküli tulajdonságok figyelmen kívül lesznek hagyva.

Kötési hierarchiák

A konfigurációs értékek hierarchikus adatokat tartalmazhatnak. A hierarchikus objektumok a : elválasztó használatával jelennek meg a konfigurációs kulcsokban. Egy konfigurációs érték eléréséhez használja a : karaktert a 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:

Kulcs Érték
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Egyszerű példa

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

Tipp

A System.Configuration.ConfigurationBuilder típus eltér a Microsoft.Extensions.Configuration.ConfigurationBuilder típustól. Minden tartalom a Microsoft.Extensions.* NuGet-csomagokra és névterekre vonatkozik.

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

</Project>

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

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 JSON-konfigurációszolgáltató által felismerendő "appsettings.json" fájlt.
  • Környezeti változókat ad hozzá, amelyeket a környezeti változók konfigurációszolgáltatója felismer.
  • Megkapja a szükséges "Settings" szakaszt és a megfelelő Settings példányt a config-példány használatával.

A 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

A IConfiguration érték eléréséhez újra támaszkodhat a Microsoft.Extensions.Hosting NuGet-csomagra. 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="10.0.0" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.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.
  • A rendszer hozzáadja a Microsoft.Extensions.Hosting NuGet-csomaghivatkozást.

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 határozza meg a JSON-konfiguráció felderítésének és a IConfiguration-példányon keresztüli elérhetővé ciójának viselkedését. A host példányból kérheti a szolgáltatótól a IConfiguration-példányt, majd kérheti az értékeket.

Tipp

Ha így használja a nyers IConfiguration-példányt, bár kényelmes, nem skálázható túl jól. Amikor az alkalmazások összetettebbé válnak, és a hozzájuk tartozó konfigurációk összetettebbé válnak, javasoljuk, hogy alternatívaként használja a beállításmintát.

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ájltartalmat:

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

Szolgáltató Konfigurációt biztosít a
Azure-alkalmazáskonfigurációs szolgáltató Azure App Configuration
Azure Key Vault konfiguráció szolgáltató Azure Key Vault
parancssori konfigurációszolgáltató Parancssori paraméterek
egyéni konfiguráció szolgáltató Egyéni forrás
Környezeti változók konfigurációs szolgáltatója Környezeti változók
fájlkonfigurációs szolgáltató JSON-, XML- és INI-fájlok
fájlonkénti kulcskonfigurációs szolgáltató Címtárfájlok
memóriakonfigurációs szolgáltató Memóriában tárolt gyűjtemények
alkalmazástitkok (Secret Manager) Fájl a felhasználói profil könyvtárában

Tipp

A konfigurációszolgáltatók hozzáadásának sorrendje számít. Ha több konfigurációszolgáltatót használ, és egynél több szolgáltató adja meg ugyanazt a kulcsot, a rendszer az utolsó hozzáadott kulcsot használja.

További információ a különböző konfigurációszolgáltatókról: .NET-konfigurációs szolgáltatók.

Lásd még:

  • Last updated on