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
Feljegyzés
A .NET-futtatókörnyezet konfigurálásával kapcsolatos információkért lásd a .NET futtatókörnyezet konfigurációs beállításait.
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:
- Parancssori argumentumok a parancssori konfigurációszolgáltató használatával.
- Környezeti változók a Környezeti változók konfigurációszolgáltató használatával.
- Alkalmazás titkos kódjai , amikor az alkalmazás a
Development
környezetben fut. - appsettings.json a JSON-konfigurációszolgáltató használatával.
- appsettings.
Environment
. json a JSON-konfigurációszolgáltatóval. Például appsettings.Éles környezetben.json és appsettings.Fejlesztés.json. - 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.
Feljegyzés
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 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:
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és segítsége nélkül, használja közvetlenül a típustConfigurationBuilder.
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="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.Configuration
funkció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ánytconfig
.
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.
Tipp.
A nyers IConfiguration
példány ily módon történő használata, bár kényelmes, nem skálázható túl jól. Ha az alkalmazások összetettebbé válnak, és a hozzájuk tartozó konfigurációk összetettebbé válnak, javasoljuk, hogy a beállítási mintát használja alternatívaként.
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.
Szolgáltató | Konfigurációt biztosít a |
---|---|
Azure-alkalmazás konfigurációszolgáltató | Azure App Configuration |
Az Azure Key Vault konfigurációszolgáltatója | 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ó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óriabeli gyűjtemények |
Alkalmazás titkos kódjai (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.
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