Konfiguráció a ASP.NET Core-ban

Rick Anderson és Kirk Larkin

Az alkalmazáskonfiguráció a ASP.NET Core-ban egy vagy több konfigurációszolgáltató használatá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:

• Beállításfájlok, például appsettings.json
• Környezeti változók
• Azure Key Vault
• Azure App Configuration
• Parancssori argumentumok
• Telepített vagy létrehozott egyéni szolgáltatók
• Címtárfájlok
• Memóriabeli .NET-objektumok

Ez a cikk a ASP.NET Core konfigurációjáról nyújt tájékoztatást. A konfiguráció non-ASP.NET Core-alkalmazásokban való használatáról a .NET-konfiguráció című témakörben olvashat.

Az Blazor ebben a csomópontban található útmutatást hozzáadó vagy felülíró konfigurációs útmutatásért tekintse meg ASP.NET Core-konfigurációtBlazor.

Alkalmazás- és gazdagépkonfiguráció

ASP.NET Core-alkalmazások konfigurálnak és indítanak el egy gazdagépet. A kiszolgáló felelős az alkalmazás indításáért és élettartam-kezeléséért. Az ASP.NET Core-sablonok létrehoznak egy olyan WebApplicationBuilder-t, amely tartalmazza a gazdagépet. Bár bizonyos konfigurációk elvégezhetők mind a gazdagépen, mind az alkalmazáskonfigurációs szolgáltatóknál, általánosságban csak a gazdagép számára szükséges konfigurációt kell elvégezni.

Az alkalmazáskonfiguráció a legmagasabb prioritás, és a következő szakaszban található. A host konfiguráció követi az alkalmazás konfigurációját, és ebben a cikkben van ismertetve.

Alapértelmezett alkalmazáskonfigurációs források

ASP.NET Dotnet New vagy Visual Studio használatával létrehozott alapvető webalkalmazások a következő kódot hozzák létre:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder inicializálja a WebApplicationBuilder osztály új példányát előre konfigurált alapértelmezett beállításokkal. Az inicializált WebApplicationBuilder (builder) 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. Nem előtagolt környezeti változók a nem előtagos környezeti változók konfigurációszolgáltatójának használatával.
3. felhasználói titkos kódok, amikor az alkalmazás a Development környezetben fut.
4. appsettings.{Environment}.json A JSON-konfigurációszolgáltató használatával. Például: appsettings.Production.json és appsettings.Development.json.
5. appsettings.json a JSON konfiguráció szolgáltatóhasználatával.
6. A következő szakaszban ismertetett gazdagépkonfigurációra való visszalépés.

Megjegyzés: WebApplication.CreateBuilder(args) csak egyszer kell meghívni az IIS folyamatban lévő üzemeltetésre támaszkodó alkalmazásokban.

Alapértelmezett gazdagépkonfigurációs források

Az alábbi lista a host alapértelmezett konfigurációs forrásait tartalmazza a legmagasabbtól a legalacsonyabb prioritásig WebApplicationBuilder.

1. Parancssori argumentumok a parancssori konfigurációszolgáltató használatával
2. DOTNET_-előtagú környezeti változók a környezeti változók konfigurációszolgáltatójának használatával.
3. ASPNETCORE_-előtagú környezeti változók a környezeti változók konfigurációszolgáltatójának használatával.

A .NET Generikus hoszt és a webhoszt esetében az alapértelmezett hosztkonfigurációs források a legmagasabbtól a legalacsonyabb prioritásig a következő:

1. ASPNETCORE_-előtagú környezeti változók a környezeti változók konfigurációszolgáltatójának használatával.
2. Parancssori argumentumok a parancssori konfigurációszolgáltató használatával
3. DOTNET_-előtagú környezeti változók a környezeti változók konfigurációszolgáltatójának használatával.

Ha egy konfigurációs érték az állomás- és alkalmazáskonfigurációban van beállítva, a rendszer az alkalmazáskonfigurációt használja.

Gazdagépváltozók

A kiszolgálóépítők inicializálásának korai szakaszában a következő változók zárolva vannak, és az alkalmazáskonfiguráció nem befolyásolja őket:

• Alkalmazás neve
• Környezet neve, például Development, Productionés Staging
• Tartalomgyökér
• Webes gyökér
• Vizsgálja meg, hogy a hostolási indító összetevőket és mely összetevőket kell vizsgálni.
• Az alkalmazás- és könyvtárkód által a HostBuilderContext.Configuration-ből az IHostBuilder.ConfigureAppConfiguration visszahívások során beolvasott változók.

Minden más gazdagépbeállítást a rendszer az alkalmazáskonfigurációból olvas be a gazdagépkonfiguráció helyett.

URLS egyike azon gyakori gazdagépbeállításoknak, amelyek nem rendszerindítási beállítások. Mint minden más kiszolgáló beállítás, amely nem szerepel az előző listában, URLS később az alkalmazáskonfigurációból olvasható. A kiszolgálókonfiguráció az alkalmazáskonfiguráció tartalékaként működik, így a kiszolgálókonfigurációnál meg lehet adni URLS, de az alkalmazáskonfiguráció bármely forrása, például appsettings.json, felülírja azt.

További információ: A tartalomgyökér, az alkalmazásnév és a környezet módosítása,valamint a tartalomgyökér, az alkalmazásnév és a környezet módosítása környezeti változók vagy parancssor szerint

A cikk további szakaszai az alkalmazáskonfigurációra vonatkoznak.

Alkalmazáskonfiguráció-szolgáltatók

Az alábbi kód az engedélyezett konfigurációszolgáltatókat a hozzáadásuk sorrendjében jeleníti meg:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

A legmagasabb és legalacsonyabb prioritású alapértelmezett konfigurációs források előző listája azokat a szolgáltatókat jeleníti meg, amelyek ellentétes sorrendben vannak hozzáadva a sablon által létrehozott alkalmazáshoz. A JSON-konfigurációszolgáltató például a parancssori konfigurációszolgáltató előtt lesz hozzáadva.

A később hozzáadott konfigurációszolgáltatók magasabb prioritással rendelkeznek, és felülbírálják a korábbi kulcsbeállításokat. Ha például MyKey mindkettőben appsettings.json és a környezetben van beállítva, a rendszer a környezeti értéket használja. Az alapértelmezett konfigurációszolgáltatók használatával a parancssori konfigurációszolgáltató felülbírálja az összes többi szolgáltatót.

További információ: CreateBuilderAlapértelmezett szerkesztő beállításai.

appsettings.json

Fontolja meg a következő appsettings.json fájlt:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

A mintaletöltésből származó következő kód az előző konfigurációs beállítások közül többet is megjelenít:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Az alapértelmezett JsonConfigurationProvider konfiguráció a következő sorrendben töltődik be:

1. appsettings.json
2. appsettings.{Environment}.json: Például a appsettings.Production.json és a appsettings.Development.json fájlok. A fájl IHostingEnvironment.EnvironmentName környezeti verziója alapján történik a betöltés. További információ: ASP.NET Core futtatókörnyezetek.

appsettings.{Environment}.json értékek felülírják a kulcsokat a(z) appsettings.json-ben. Például alapértelmezés szerint:

• A fejlesztés során a appsettings.Development.json konfiguráció felülírja a következőben appsettings.jsontalálható értékeket: .
• Éles környezetben a appsettings.Production.json konfiguráció felülírja a appsettings.json található értékeket. Például az alkalmazás Azure-ban való üzembe helyezésekor.

Ha egy konfigurációs értéket garantálni kell, olvassa el a GetValue című témakört. Az előző példa csak sztringeket olvas be, és nem támogatja az alapértelmezett értéket.

Az alapértelmezett konfigurációval a appsettings.json paranccsal engedélyezve vannak a appsettings.{Environment}.json fájlok és a fájlok. A appsettings.json felolvassa az appsettings.{Environment}.json alkalmazás elindítása után végrehajtott módosításokat és fájlokat.

Megjegyzések a appsettings.json

A appsettings.json és appsettings.{Environment}.json fájlokban lévő megjegyzések JavaScript- vagy C#-stílusú megjegyzések használatával támogatottak.

Egyes integrált fejlesztési környezetek (IDE) hibaüzeneteket jelenítenek meg a megjegyzéseket tartalmazó JSON-fájlok szerkesztésekor. Általában figyelmen kívül hagyhatja a megjegyzéshibákat és figyelmeztetéseket, de általában letilthatja őket egy beállítással az IDE-ben. A Visual Studio Code-ban például adja hozzá a következőt a fájlhoz a settings.json hibák letiltásához:

"files.associations": {
  "appsettings*.json": "jsonc"
}

IDE-k esetén ellenőrizze az eszköz dokumentációját és más terméktámogatási csatornákat, hogy megállapíthassa, hogyan lehet elhallgattatni a hibákat.

Hierarchikus konfigurációs adatok kapcsolása a beállítási sablonnal

A kapcsolódó konfigurációs értékek olvasásának elsődleges módja a beállítási minta használata. Például a következő konfigurációs értékek olvasásához:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Hozza létre a következő PositionOptions osztályt:

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; } = String.Empty;
    public string Name { get; set; } = String.Empty;
}

Egy beállításosztály:

• Nem lehet absztrakt, és nyilvános, paraméter nélküli konstruktorral kell rendelkeznie.
• A típus összes nyilvános írási-olvasási tulajdonsága kötött.
• A mezők nincsenek megkötve. Az előző kódban a Position nincs kötés alatt. A Position mező célja, hogy ne kelljen a "Position" sztringet kézzel kódolni az alkalmazásban, amikor az osztályt egy konfigurációs szolgáltatóhoz kötjük.

A következő kód:

• A ConfigurationBinder.Bind meghívásával köti az osztályt PositionOptions a Position szakaszhoz.
• Megjeleníti a Position konfigurációs adatokat.

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

    public Test22Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Az előző kódban alapértelmezés szerint a JSON-konfigurációs fájl módosításai az alkalmazás elindítása után jelennek meg.

ConfigurationBinder.Get<T> köti és visszaadja a megadott típust. ConfigurationBinder.Get<T> lehet, hogy kényelmesebb, mint a használata ConfigurationBinder.Bind. Az alábbi kód bemutatja, hogyan használható ConfigurationBinder.Get<T> az PositionOptions osztály:

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions? positionOptions { get; private set; }

    public Test21Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

Az előző kódban alapértelmezés szerint a JSON-konfigurációs fájl módosításai az alkalmazás elindítása után jelennek meg.

A beállítási minta használatakor alternatív módszer a szakasz kötése Position és hozzáadása a függőséginjektálási szolgáltatás tárolóhoz. A következő kódban PositionOptions hozzáadásra kerül a szolgáltatástárolóhoz Configure-sel és konfigurációhoz kötve:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));

var app = builder.Build();

Az előző kód használatával a következő kód felolvassa a pozícióbeállításokat:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

Az előző kódban az alkalmazás elindítása után a JSON-konfigurációs fájl módosításai nem lesznek beolvasva. Az alkalmazás elindítása utáni módosítások olvasásához használja az IOptionsSnapshot parancsot.

Az alapértelmezett konfigurációval a appsettings.json paranccsal engedélyezve vannak a appsettings.{Environment}.json fájlok és a fájlok. A appsettings.json felolvassa az appsettings.{Environment}.json alkalmazás elindítása után végrehajtott módosításokat és fájlokat.

További JSON-konfigurációs fájlok hozzáadásáról a jelen dokumentumban található JSON-konfigurációszolgáltató nyújt tájékoztatást.

Szolgáltatásgyűjtemény kombinálása

Vegye figyelembe a következőket, amelyek regisztrálják a szolgáltatásokat, és konfigurálják a beállításokat:

using ConfigSample.Options;
using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<PositionOptions>(
    builder.Configuration.GetSection(PositionOptions.Position));
builder.Services.Configure<ColorOptions>(
    builder.Configuration.GetSection(ColorOptions.Color));

builder.Services.AddScoped<IMyDependency, MyDependency>();
builder.Services.AddScoped<IMyDependency2, MyDependency2>();

var app = builder.Build();

A kapcsolódó regisztrációs csoportok áthelyezhetők egy bővítménymetódusba a szolgáltatások regisztrálásához. A konfigurációs szolgáltatások például a következő osztályhoz lesznek hozzáadva:

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }

        public static IServiceCollection AddMyDependencyGroup(
             this IServiceCollection services)
        {
            services.AddScoped<IMyDependency, MyDependency>();
            services.AddScoped<IMyDependency2, MyDependency2>();

            return services;
        }
    }
}

A többi szolgáltatás hasonló osztályba van regisztrálva. Az alábbi kód az új bővítménymetelyeket használja a szolgáltatások regisztrálásához:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddConfig(builder.Configuration)
    .AddMyDependencyGroup();

builder.Services.AddRazorPages();

var app = builder.Build();

Megjegyzés: Minden services.Add{GROUP_NAME} bővítménymetódus szolgáltatásokat ad hozzá és konfigurál. Például AddControllersWithViews hozzáadja azokat a szolgáltatásokat, amelyekre az MVC vezérlőknek a nézetekkel szükségük van, és AddRazorPages hozzáadja azokat a szolgáltatásokat, amelyekre a Razor Lapoknak szükségük van.

Biztonsági és felhasználói titkos kódok

Konfigurációs adatokra vonatkozó irányelvek:

• Soha ne tároljon jelszavakat vagy más bizalmas adatokat konfigurációszolgáltatói kódban vagy egyszerű szöveges konfigurációs fájlokban. A Secret Manager eszközzel titkos kulcsokat tárolhat a fejlesztés során.
• Ne használj üzemi titkokat fejlesztési vagy tesztelési környezetekben.
• Adja meg a projekten kívüli érzékeny adatokat, hogy ezek véletlenül ne kerüljenek feltöltve egy forráskód-tárházba.
• A termelésben használt alkalmazásoknak az elérhető legbiztonságosabb hitelesítési folyamatot kell használniuk. További információ: Biztonságos hitelesítési folyamatok.

Alapértelmezés szerint a felhasználói titkos kódok konfigurációs forrása a JSON-konfigurációs források után lesz regisztrálva. Ezért a felhasználói titkos kulcsok elsőbbséget élveznek a appsettings.json és appsettings.{Environment}.json kulcsokkal szemben.

További információ a jelszavak vagy más bizalmas adatok tárolásáról:

• ASP.NET Core futtatókörnyezetek
• Az alkalmazás titkos kulcsainak biztonságos tárolása a fejlesztés során a ASP.NET Core-ban: Tanácsokat tartalmaz a környezeti változók bizalmas adatok tárolására való használatával kapcsolatban. A Secret Manager eszköz a Fájlkonfigurációs szolgáltatóval tárolja a felhasználói titkos kódokat egy JSON-fájlban a helyi rendszeren.
• Az Azure Key Vault biztonságosan tárolja az alkalmazás titkos kulcsait ASP.NET Core-alkalmazásokhoz. További információ: Azure Key Vault konfigurációszolgáltató a ASP.NET Core-ban.

Nem előtagolt környezeti változók

Előtag nélküli környezeti változók azok a környezeti változók, amelyek nem rendelkeznek ASPNETCORE_ vagy DOTNET_ előtaggal. Az ASP.NET Core webalkalmazás-sablonok például beállíthatók a következőképpen: "ASPNETCORE_ENVIRONMENT": "Development"launchSettings.json. További információért a ASPNETCORE_ és DOTNET_ környezeti változókról lásd:

• A legmagasabb és legalacsonyabb prioritású alapértelmezett konfigurációs források listája , beleértve a nem előtagos, ASPNETCORE_-előtagú és DOTNETCORE_-előtagú környezeti változókat.
• a DOTNET_ szolgáltatáson kívül használt környezeti változók.

A default konfiguráció használatakor a konfigurációt betöltő folyamat a környezeti változó kulcs-érték párokból tölti be, miután elolvassa a EnvironmentVariablesConfigurationProvider, appsettings.json, és appsettings.{Environment}.json. Ezért a környezetből beolvasott kulcsértékek felülbírálják a helyről appsettings.jsonappsettings.{Environment}.jsonbeolvasott értékeket és a felhasználói titkos kódokat.

A : elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. A : elválasztójel például nem elérhető a Bash-ban. A dupla aláhúzás, __, a következő:

• Minden platform támogatja.
• Automatikusan kicserélődik egy kettősponttal, :.

A következő parancsok:

• Állítsa be az előző példa környezeti kulcsait és értékeit Windows rendszeren.
• Tesztelje a beállításokat a mintaletöltés használatakor. A dotnet run parancsot a projektkönyvtárban kell futtatni.

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Az előző környezeti beállítások:

• Csak a parancsablakból indított folyamatokban vannak beállítva.
• A Visual Studióval indított böngészők nem fogják elolvasni.

A következő setx-parancsokkal állíthatja be a környezeti kulcsokat és értékeket Windows rendszeren. A setellentétben a setx beállítások megmaradnak. /M beállítja a változót a rendszerkörnyezetben. Ha nem használja a /M kapcsolót, egy felhasználói környezeti változó van beállítva.

setx MyKey "My key from setx Environment" /M
setx Position__Title Environment_Editor /M
setx Position__Name Environment_Rick /M

Annak tesztelése, hogy a megelőző parancsok felülírják-e appsettings.json és appsettings.{Environment}.json:

• A Visual Studio használata: Kilépés és újraindítás a Visual Studióval.
• A parancssori felülettel: Indítsa el az új parancsablakot, és írja be dotnet run.

Hívd meg AddEnvironmentVariables egy sztringgel a környezeti változók előtagjának megadásához:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_");

var app = builder.Build();

Az előző kódban:

• builder.Configuration.AddEnvironmentVariables(prefix: "MyCustomPrefix_") az alapértelmezett konfigurációszolgáltatók után lesz hozzáadva. A konfigurációszolgáltatók megrendelésére példa: JSON-konfigurációszolgáltató.
• Az előtaggal MyCustomPrefix_ beállított környezeti változók felülbírálják az alapértelmezett konfigurációszolgáltatókat. Ide tartoznak az előtag nélküli környezeti változók.

Az előtag a konfigurációs kulcs-érték párok olvasásakor törlődik.

Az alábbi parancsok tesztelik az egyéni előtagot:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

Az alapértelmezett konfiguráció betölti a DOTNET_ és ASPNETCORE_ előtaggal ellátott környezeti változókat és parancssori argumentumokat. Az DOTNET_ és ASPNETCORE_ előtagokat az ASP.NET Core használja a gazdagép- és alkalmazáskonfigurációhoz, a felhasználói konfigurációhoz azonban nem. A gazdagép- és alkalmazáskonfigurációval kapcsolatos további információkért lásd: .NET Generic Host.

A Azure-alkalmazás Szolgáltatásban válassza az Új alkalmazás beállítást a Beállítások > konfiguráció lapján. Az Azure App Service alkalmazás beállításai a következők:

• Inaktív állapotban titkosítva és titkosított csatornán keresztül továbbítva.
• Környezeti változókként van hozzáférhetővé téve.

További információ: Azure Apps: Alkalmazáskonfiguráció felülbírálása az Azure Portalhasználatával.

Az Azure-adatbázis kapcsolati sztringjeiről további információt a kapcsolati sztringek előtagjaiban talál.

Környezeti változók elnevezése

A környezeti változók nevei egy appsettings.json fájl szerkezetét tükrözik. A hierarchia minden elemét kettős aláhúzás (előnyösebb) vagy kettőspont választja el egymástól. Ha az elemszerkezet tartalmaz egy tömböt, a tömbindexet további elemnévként kell kezelni ebben az elérési úton. Vegye figyelembe a következő appsettings.json fájlt és annak egyenértékű értékeit környezeti változókként.

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "MySystem@example.com",
                "ToAddress": "SRE@example.com"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

környezeti változók

setx SmtpServer smtp.example.com
setx Logging__0__Name ToEmail
setx Logging__0__Level Critical
setx Logging__0__Args__FromAddress MySystem@example.com
setx Logging__0__Args__ToAddress SRE@example.com
setx Logging__1__Name ToConsole
setx Logging__1__Level Information

Beállított környezeti változók a létrehozott launchSettings.json-ban

Az launchSettings.json környezeti változók felülírják a rendszerkörnyezetben beállított értékeket. A ASP.NET Core-websablonok például létrehoznak egy launchSettings.json fájlt, amely a végpontkonfigurációt a következőre állítja be:

"applicationUrl": "https://localhost:5001;http://localhost:5000"

applicationUrl konfigurálása beállítja a ASPNETCORE_URLS környezeti változót, és felülbírálja a környezetben beállított értékeket.

Escape környezeti változók Linuxon

Linuxon az URL környezeti változók értékét escape-elni kell, hogy systemd elemezhesse. Használja a Linux-eszközt systemd-escape, amely eredményt ad http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

Környezeti változók megjelenítése

Az alábbi kód megjeleníti a környezeti változókat és értékeket az alkalmazás indításakor, ami hasznos lehet a környezeti beállítások hibakereséséhez:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

foreach (var c in builder.Configuration.AsEnumerable())
{
    Console.WriteLine(c.Key + " = " + c.Value);
}

Command-line

Az alapértelmezett konfiguráció használatával a konfiguráció a CommandLineConfigurationProvider parancssori argumentum kulcs-érték párjaiból töltődik be a következő konfigurációs források után:

• appsettings.json és appsettings.{Environment}.json fájlok.
• Alkalmazás titkos kódjai a fejlesztési környezetben.
• Környezeti változók.

Alapértelmezés szerint a parancssorban beállított konfigurációs értékek felülbírálják az összes többi konfigurációszolgáltatónál beállított konfigurációs értékeket.

Parancssori argumentumok

A következő parancs a következő paranccsal =állítja be a kulcsokat és az értékeket:

dotnet run MyKey="Using =" Position:Title=Cmd Position:Name=Cmd_Rick

A következő parancs a következő paranccsal /állítja be a kulcsokat és az értékeket:

dotnet run /MyKey "Using /" /Position:Title=Cmd /Position:Name=Cmd_Rick

A következő parancs a következő paranccsal --állítja be a kulcsokat és az értékeket:

dotnet run --MyKey "Using --" --Position:Title=Cmd --Position:Name=Cmd_Rick

A kulcs értéke:

• Követnie =kell, vagy a kulcsnak előtaggal kell rendelkeznie -- , vagy / ha az érték szóközt követ.
• Használat esetén = nincs szükség rá. Például: MySetting=.

Ugyanazon a parancson belül ne keverje össze a parancssori argumentum kulcs-érték párjait, amelyek szóközt használó kulcs-érték párokkal használhatók = .

Leképezések váltása

A kapcsolóleképezések lehetővé teszik a kulcsnév cseréjének logikáját. Adjon meg egy szótárat a kapcsolócserékhez a AddCommandLine metódus számára.

A kapcsolóleképezések szótárának használata esetén a rendszer ellenőrzi, hogy a szótár megfelel-e a parancssori argumentum által biztosított kulcsnak. Ha a parancssori kulcs megtalálható a szótárban, a rendszer visszaadja a szótár értékét, hogy a kulcs-érték párot az alkalmazás konfigurációjába állítsa. Egy kapcsolóleképezés szükséges minden olyan parancssori kulcshoz, amely egyetlen kötőjellel (-kötőjellel) rendelkezik.

A leképezések szótárkulcs-szabályainak váltása:

• A kapcsolóknak --val vagy ---vel kell kezdődniük.
• A kapcsolóleképezések szótára nem tartalmazhat ismétlődő kulcsokat.

A kapcsolóleképezések szótárának használatához adja át a hívás során AddCommandLine:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

builder.Configuration.AddCommandLine(args, switchMappings);

var app = builder.Build();

Futtassa a következő parancsot a kulcsok cseréjének teszteléséhez:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

A következő kód a lecserélt kulcsok kulcsértékét mutatja:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

Kapcsolóleképezéseket használó alkalmazások esetében a CreateDefaultBuilder hívásnak nem szabad átadnia argumentumokat. A CreateDefaultBuilder metódus AddCommandLine hívása nem tartalmaz leképezett kapcsolókat, és nincs mód a kapcsolóleképezési szótár CreateDefaultBuilder-nek való átadására. A megoldás nem az argumentumok CreateDefaultBuilder átadása, hanem annak engedélyezése, hogy a ConfigurationBuilder metódus metódusa AddCommandLine feldolgozhassa mind az argumentumokat, mind a kapcsolóleképezési szótárat.

Környezet és parancssori argumentumok beállítása a Visual Studióval

A környezet és a parancssori argumentumok az indítási profilok párbeszédpanelen állíthatók be a Visual Studióban:

• A Megoldáskezelőben kattintson a jobb gombbal a projektre, és válassza a Tulajdonságok lehetőséget.
• Válassza az Általános hibakeresés > lapot, és válassza a Hibakeresési indítási profilok felhasználói felületének megnyitása lehetőséget.

Hierarchikus konfigurációs adatok

A Configuration API a hierarchikus konfigurációs adatokat úgy olvassa be, hogy a konfigurációs kulcsokban elválasztó karakterrel lapítja el az adatokat.

A mintaletöltés a következő appsettings.json fájlt tartalmazza:

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

A mintaletöltésből származó következő kód számos konfigurációs beállítást jelenít meg:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

A hierarchikus konfigurációs adatok olvasásának elsődleges módja a beállítási minta használata. További információ: Hierarchikus konfigurációs adatok kötése ebben a dokumentumban.

GetSection és GetChildren módszerek állnak rendelkezésre a konfigurációs adatok egy szakaszának szakaszainak és gyermekeinek elkülönítésére. Ezeket a metódusokat később a GetSection, a GetChildren és a Exists ismerteti.

Konfigurációs kulcsok és értékek

Warning

Ez a cikk a kapcsolati sztringek használatát mutatja be. Helyi adatbázis esetén a felhasználót nem kell hitelesíteni, de éles környezetben a kapcsolati sztringek néha tartalmaznak jelszót a hitelesítéshez. Az erőforrás-tulajdonosi jelszóval történő hitelesítés (ROPC) olyan biztonsági kockázatot jelent, amelyet el kell kerülni a termelési adatbázisokban. A termelésben használt alkalmazásoknak az elérhető legbiztonságosabb hitelesítési folyamatot kell használniuk. A tesztelési vagy éles környezetekben üzembe helyezett alkalmazások hitelesítéséről további információt a Biztonságos hitelesítési folyamatokcímű témakörben talál.

Konfigurációs kulcsok:

• A kis- és nagybetűk érzéketlenek. A ConnectionString és a connectionstring például egyenértékű kulcsként kezelik.
• Ha egy kulcs és érték egynél több konfigurációszolgáltatóban van beállítva, a rendszer az utolsó hozzáadott szolgáltató értékét használja. További információ: Alapértelmezett konfiguráció.
• Hierarchikus kulcsok
  • A Configuration API-n belül a kettőspont-elválasztó (:) minden platformon működik.
  • Környezeti változókban előfordulhat, hogy a kettőspont-elválasztó nem minden platformon működik. A dupla aláhúzást minden platform támogatja, __és automatikusan kettősponttá :alakítja .
  • Az Azure Key Vaultban a hierarchikus kulcsok elválasztóként használhatók -- . Az Azure Key Vault konfigurációszolgáltatója automatikusan lecseréli a -- egy : helyére, amikor a titkok be vannak töltve az alkalmazás konfigurációjába.
• Támogatja ConfigurationBinder a tömbök objektumokhoz való kötését a konfigurációs kulcsokban lévő tömbindexek használatával. A tömbkötést a tömbök osztályszakaszhoz kötése című szakasz ismerteti.

Konfigurációs értékek:

• Sztringek.
• A null értékek nem tárolhatók konfigurációban vagy objektumokhoz kötve.

Konfigurációszolgáltatók

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

Provider	Konfigurációt biztosít a
Azure Key Vault konfiguráció szolgáltató	Azure Key Vault
Azure-alkalmazáskonfigurációs szolgáltató	Azure App Configuration
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ó	INI-, JSON- és XML-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
Felhasználói titkos kódok	Fájl a felhasználói profil könyvtárában

A konfigurációs források olvasása a konfigurációs szolgáltatók megadásának sorrendjében történik. A konfigurációszolgáltatókat kódban rendelheti meg, hogy megfeleljenek az alkalmazás által igényelt mögöttes konfigurációs források prioritásainak.

A konfigurációszolgáltatók jellemző sorrendje a következő:

1. appsettings.json
2. appsettings.{Environment}.json
3. Felhasználói titkos kódok
4. Környezeti változók a konfigurációszolgáltatón keresztül.
5. Parancssori argumentumok a parancssori konfigurációszolgáltatóval.

Gyakori eljárás, hogy a konfigurációs szolgáltatókat sorba rendezve a parancssori konfigurációs szolgáltatót utoljára adjuk hozzá, így a parancssori argumentumok felülírhatják a többi szolgáltató által beállított konfigurációt.

Az alapértelmezett konfiguráció a szolgáltatók előző sorozatát használja.

Kapcsolati sztring előtagok

Warning

Ez a cikk a kapcsolati sztringek használatát mutatja be. Helyi adatbázis esetén a felhasználót nem kell hitelesíteni, de éles környezetben a kapcsolati sztringek néha tartalmaznak jelszót a hitelesítéshez. Az erőforrás-tulajdonosi jelszóval történő hitelesítés (ROPC) olyan biztonsági kockázatot jelent, amelyet el kell kerülni a termelési adatbázisokban. A termelésben használt alkalmazásoknak az elérhető legbiztonságosabb hitelesítési folyamatot kell használniuk. A tesztelési vagy éles környezetekben üzembe helyezett alkalmazások hitelesítéséről további információt a Biztonságos hitelesítési folyamatokcímű témakörben talál.

A Configuration API négy kapcsolati sztring környezeti változó speciális feldolgozási szabályaival rendelkezik. Ezek a kapcsolati sztring részt vesznek az Azure-kapcsolati sztring alkalmazáskörnyezethez való konfigurálásában. A táblázatban megadott előtagokkal rendelkező környezeti változók betöltődnek az alkalmazásba az alapértelmezett konfigurációval, vagy ha nem adunk meg előtagot.AddEnvironmentVariables

Kapcsolati sztring előtagja	Provider
CUSTOMCONNSTR_	Egyéni szolgáltató
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Azure SQL-adatbázis
SQLCONNSTR_	SQL Server

Amikor felfedez egy környezeti változót, és betöltődik a konfigurációba a táblázatban látható négy előtag bármelyikével:

• A konfigurációs kulcs a környezeti változó előtagjának eltávolításával és egy konfigurációs kulcsszakasz ()ConnectionStrings hozzáadásával jön létre.
• Létrejön egy új konfigurációs kulcs-érték pár, amely az adatbázis-kapcsolat szolgáltatóját jelöli (kivéve CUSTOMCONNSTR_, amely nem rendelkezik megadott szolgáltatóval).

Környezeti változókulcs	Konvertált konfigurációs kulcs	Szolgáltató konfigurációs bejegyzése
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	A konfigurációs bejegyzés nem jött létre.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kulcs: ConnectionStrings:{KEY}_ProviderName Érték: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Kulcs: ConnectionStrings:{KEY}_ProviderName Érték: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Kulcs: ConnectionStrings:{KEY}_ProviderName Érték: System.Data.SqlClient

Fájlkonfigurációs szolgáltató

FileConfigurationProvider A konfiguráció fájlrendszerből való betöltésének alaposztálya. A következő konfigurációs szolgáltatók a következőkből származnak FileConfigurationProvider:

• INI-konfigurációszolgáltató
• JSON-konfigurációszolgáltató
• XML-konfigurációszolgáltató

INI-konfigurációszolgáltató

A IniConfigurationProvider futásidőben betölti a konfigurációt az INI-fájlból származó kulcs-érték párok alapján.

A következő kód több konfigurációszolgáltatót is hozzáad:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"MyIniConfig.{builder.Environment.EnvironmentName}.ini",
                optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Az előző kódban a MyIniConfig.ini és MyIniConfig.{Environment}.ini fájlok beállításait a következő beállítások felülírják:

• Környezeti változók konfigurációszolgáltatója
• Parancssori konfigurációszolgáltató.

A mintaletöltés a következő MyIniConfig.ini fájlt tartalmazza:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

A mintaletöltésből származó következő kód az előző konfigurációs beállítások közül többet is megjelenít:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

JSON-konfigurációszolgáltató

A JsonConfigurationProvider konfigurációt JSON-fájl kulcs-érték párokból tölt be.

A túlterhelések a következőket adhatók meg:

• A fájl megadása nem kötelező.
• Azt jelzi, hogy a konfiguráció újra betöltődik-e, ha a fájl megváltozik.

Vegye figyelembe a következő kódot:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("MyConfig.json",
        optional: true,
        reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

Az előző kód:

• A JSON-konfigurációszolgáltatót úgy konfigurálja, hogy betöltse a MyConfig.json fájlt a következő beállításokkal:
  • optional: true: A fájl nem kötelező.
  • reloadOnChange: true : A fájl újratöltődik a módosítások mentésekor.
• Beolvassa az alapértelmezett konfigurációszolgáltatókat a MyConfig.json fájl előtt. MyConfig.json Az alapértelmezett konfigurációszolgáltatók fájl felülbírálási beállításának beállításai, beleértve a környezeti változók konfigurációs szolgáltatóját és a parancssori konfigurációszolgáltatót.

A környezeti változók konfigurációs szolgáltatójában és a parancssori konfigurációszolgáltatóban általában nem szeretné, hogy egyéni JSON-fájl felülírja az értékeket.

XML-konfigurációszolgáltató

A XmlConfigurationProvider a konfigurációt futásidőben tölti be XML-fájlok kulcs-érték párjaiból.

A következő kód több konfigurációszolgáltatót is hozzáad:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
    .AddXmlFile($"MyXMLFile.{builder.Environment.EnvironmentName}.xml",
                optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

Az előző kódban a MyXMLFile.xml és MyXMLFile.{Environment}.xml fájlok beállításait a következő beállítások felülírják:

• Környezeti változók konfigurációszolgáltatója
• Parancssori konfigurációszolgáltató.

A mintaletöltés a következő MyXMLFile.xml fájlt tartalmazza:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

A mintaletöltésből származó következő kód az előző konfigurációs beállítások közül többet is megjelenít:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Az azonos elemnevet használó ismétlődő elemek akkor működnek, ha az name attribútum az elemek megkülönböztetésére szolgál:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

Az alábbi kód beolvassa az előző konfigurációs fájlt, és megjeleníti a kulcsokat és értékeket:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

    public IndexModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

Az attribútumok az értékek megadására használhatók:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

Az előző konfigurációs fájl a következő kulcsokat tölti be a következőkkel value:

• key:attribute
• section:key:attribute

Fájlonkénti kulcskonfigurációs szolgáltató

A KeyPerFileConfigurationProvider címtár fájljait használja konfigurációs kulcs-érték párként. A kulcs a fájlnév. Az érték a fájl tartalmát tartalmazza. A fájlonkénti kulcskonfigurációs szolgáltatót a Docker üzemeltetési forgatókönyvei használják.

A fájlonkénti kulcskonfiguráció aktiválásához hívja meg a AddKeyPerFile bővítménymetódust egy példányon ConfigurationBuilder. A directoryPath fájloknak abszolút elérési útnak kell lenniük.

A túlterhelések lehetővé teszik az alábbiak megadását:

• A Action<KeyPerFileConfigurationSource> forrást konfiguráló meghatalmazott.
• Nem kötelező megadni a könyvtárat és a könyvtár elérési útját.

A dupla aláhúzás (__) konfigurációs kulcs elválasztóként használatos a fájlnevekben. A fájlnév Logging__LogLevel__System például létrehozza a konfigurációs kulcsot Logging:LogLevel:System.

Hívás ConfigureAppConfiguration a gazdagép létrehozásakor az alkalmazás konfigurációjának megadásához:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Memóriakonfigurációs szolgáltató

A MemoryConfigurationProvider rendszer egy memórián belüli gyűjteményt használ konfigurációs kulcs-érték párként.

A következő kód egy memóriagyűjteményt ad hozzá a konfigurációs rendszerhez:

var builder = WebApplication.CreateBuilder(args);

var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

builder.Configuration.AddInMemoryCollection(Dict);
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddCommandLine(args);

builder.Services.AddRazorPages();

var app = builder.Build();

A mintaletöltés alábbi kódja a fenti konfigurációs beállításokat jeleníti meg:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Az előző kódban a config.AddInMemoryCollection(Dict) az alapértelmezett konfigurációszolgáltatók után van hozzáadva. A konfigurációszolgáltatók megrendelésére példa: JSON-konfigurációszolgáltató.

Lásd Tömb lekötése egy másik példát MemoryConfigurationProvider használatával.

Kestrel végpontkonfiguráció

Kestrel adott végpontkonfiguráció felülbírálja az összes kiszolgálóközi végpontkonfigurációt. A kiszolgálóközi végpontkonfigurációk a következők:

• UseUrls
• --urls a parancssorban
• A környezeti változóASPNETCORE_URLS

Fontolja meg a ASP.NET Core-webalkalmazásban használt alábbi appsettings.json fájlt:

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9999"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
} 

Ha az előző kiemelt korrektúra egy ASP.NET Core-webalkalmazásban van használatban , és az alkalmazás a parancssorban indul el a következő kiszolgálóközi végpontkonfigurációval:

dotnet run --urls="https://localhost:7777"

Kestrel a kifejezetten a Kestrel fájlban (appsettings.json) a https://localhost:9999 számára konfigurált végponthoz csatlakozik, nem pedig a https://localhost:7777-hez.

Vegye figyelembe az Kestrel adott végpontot környezeti változóként konfigurálva:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

Az előbb említett környezeti változó, Https az adott végpont neve Kestrel. Az előző appsettings.json fájl egy Kestrel adott végpontot Httpsis definiál. A környezeti változók konfigurációszolgáltatóját használó környezeti változókalapértelmezés szerint utána lesznek beolvasvaappsettings.{Environment}.json, ezért a rendszer az előző környezeti változót használja a Https végponthoz.

GetValue

ConfigurationBinder.GetValue egyetlen értéket nyer ki egy megadott kulccsal rendelkező konfigurációból, és átalakítja a megadott típusra:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

    public TestNumModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

Az előző kódban, ha NumberKey nem található a konfigurációban, a rendszer az alapértelmezett értéket 99 használja.

GetSection, GetChildren és Exists

Az alábbi példákhoz tekintse meg a következő MySubsection.json fájlt:

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

A következő kód hozzáadja a konfigurációszolgáltatókat MySubsection.json :

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddJsonFile("MySubsection.json",
                 optional: true,
                 reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

GetSection

IConfiguration.GetSection egy konfigurációs alszakaszt ad vissza a megadott alszakaszkulcsmal.

A következő kód a következő section1értékeket adja vissza:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

A következő kód a következő section2:subsection0értékeket adja vissza:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

GetSection soha nem ad nullvissza . Ha nem található egyező szakasz, a rendszer üres IConfigurationSection szakaszt ad vissza.

Ha GetSection egyező szakaszt ad vissza, Value nincs kitöltve. A Key és Path a szakasz létrehozásakor lesz visszaadva.

„GetChildren” és „Exists”

A következő kód meghívja IConfiguration.GetChildren és visszaadja a következő értékeket section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = "";
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

Az előző kódrészlet meghívja ConfigurationExtensions.Exists-t a szakasz meglétének ellenőrzésére:

Tömb összekapcsolása

Támogatja ConfigurationBinder.Bind a tömbök objektumokhoz való kötését a konfigurációs kulcsokban lévő tömbindexek használatával. A numerikus kulcsszegmenseket elérhetővé tevő tömbformátumok képesek tömbkötésre egy POCO-osztálytömbhöz .

Fontolja meg MyArray.json a mintaletöltést:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

A következő kód hozzáadja a konfigurációszolgáltatókat MyArray.json :

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddJsonFile("MyArray.json",
                 optional: true,
                 reloadOnChange: true);

builder.Services.AddRazorPages();

var app = builder.Build();

A következő kód beolvassa a konfigurációt, és megjeleníti az értékeket:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample? _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
       _array = Config.GetSection("array").Get<ArrayExample>();
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }
        string s = String.Empty;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

public class ArrayExample
{
    public string[]? Entries { get; set; } 
}

Az előző kód a következő kimenetet adja vissza:

Index: 0  Value: value00
Index: 1  Value: value10
Index: 2  Value: value20
Index: 3  Value: value40
Index: 4  Value: value50

Az előző kimenetben a 3. index értéke value40a következőnek felel meg "4": "value40",MyArray.json: A kötött tömbindexek folyamatosak, és nem kötődnek a konfigurációs kulcs indexéhez. A konfigurációs kötés nem képes null értékek kötésére vagy null értékű bejegyzések létrehozására kötött objektumokban.

Egyéni konfigurációszolgáltató

A mintaalkalmazás bemutatja, hogyan hozhat létre egy alapszintű konfigurációszolgáltatót, amely beolvassa a konfigurációs kulcs-érték párokat egy adatbázisból az Entity Framework (EF) használatával.

A szolgáltató a következő jellemzőkkel rendelkezik:

• A memóriabeli EF-adatbázist bemutató célokra használják. A kapcsolati sztringet igénylő adatbázis használatához valósítson meg egy másodlagos ConfigurationBuilder elemet, amely egy másik konfigurációs szolgáltatótól biztosítja a kapcsolati sztringet.
• A szolgáltató indításkor beolvassa az adatbázistáblát a konfigurációba. A szolgáltató nem kulcsonként kérdezi le az adatbázist.
• A módosítás újrabetöltése nincs implementálva, ezért az adatbázis frissítése az alkalmazás indítása után nincs hatással az alkalmazás konfigurációjára.

Adjon meg egy entitást EFConfigurationValue a konfigurációs értékek adatbázisban való tárolásához.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; } = String.Empty;
    public string Value { get; set; } = String.Empty;
}

Adjon hozzá egy értéket EFConfigurationContext a konfigurált értékek tárolásához és eléréséhez.

EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions<EFConfigurationContext> options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values => Set<EFConfigurationValue>();
}

Hozzon létre egy IConfigurationSourcemegvalósító osztályt.

EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction) => _optionsAction = optionsAction;

    public IConfigurationProvider Build(IConfigurationBuilder builder) => new EFConfigurationProvider(_optionsAction);
}

Hozzon létre egy egyéni konfigurációszolgáltatót úgy, hogy örököl a ConfigurationProvider osztályból. A konfigurációszolgáltató inicializálja az adatbázist, ha üres. Mivel a konfigurációs kulcsok kis- és nagybetűket nem megkülönböztetők, az adatbázis inicializálásához használt szótár a kis- és nagybetűket nem megkülönböztető összehasonlítóval (StringComparer.OrdinalIgnoreCase) jön létre.

EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            if (dbContext == null || dbContext.Values == null)
            {
                throw new Exception("Null DB context");
            }
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity-2005
        var configValues =
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                    { "quote1", "I aim to misbehave." },
                    { "quote2", "I swallowed a bug." },
                    { "quote3", "You can't stop the signal, Mal." }
            };

        if (dbContext == null || dbContext.Values == null)
        {
            throw new Exception("Null DB context");
        }

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue
            {
                Id = kvp.Key,
                Value = kvp.Value
            })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

A AddEFConfiguration bővítménymetódus lehetővé teszi egy konfigurációs forrás hozzáadását egy ConfigurationBuilder-hoz.

Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
               this IConfigurationBuilder builder,
               Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

Az alábbi kód megmutatja, hogyan használható az egyéni EFConfigurationProvider a Program.cs-ban:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddEFConfiguration(
    opt => opt.UseInMemoryDatabase("InMemoryDb"));

var app = builder.Build();

app.Run();

Hozzáférés konfigurációja függőséginjektálással (DI)

A konfiguráció a függőséginjektálás (DI) használatával injektálható a szolgáltatásokba a IConfiguration szolgáltatás feloldásával:

public class Service
{
    private readonly IConfiguration _config;

    public Service(IConfiguration config) =>
        _config = config;

    public void DoSomething()
    {
        var configSettingValue = _config["ConfigSetting"];

        // ...
    }
}

Az értékek IConfigurationeléréséről ebben a cikkben a GetValue és a GetSection, a GetChildren és a Exists című témakörben olvashat bővebben.

Hozzáférés konfigurációja a Pagesben Razor

A következő kód egy lapon jeleníti meg a Razor konfigurációs adatokat:

@page
@model Test5Model
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

A következő kódban MyOptions hozzáadásra kerül a szolgáltatástárolóhoz Configure-sel és konfigurációhoz kötve:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

var app = builder.Build();

Az alábbi korrektúra az @injectRazor irányelv használatával oldja fel és jeleníti meg a beállítások értékeit:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@using SampleApp.Models
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Hozzáférés konfigurációja MVC-nézetfájlban

Az alábbi kód A konfigurációs adatokat MVC nézetben jeleníti meg:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Hozzáférés konfigurációja a következőben: Program.cs

Az alábbi kód a konfigurációt a Program.cs fájlban éri el.

var builder = WebApplication.CreateBuilder(args);

var key1 = builder.Configuration.GetValue<string>("KeyOne");

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

var key2 = app.Configuration.GetValue<int>("KeyTwo");
var key3 = app.Configuration.GetValue<bool>("KeyThree");

app.Logger.LogInformation("KeyOne: {KeyOne}", key1);
app.Logger.LogInformation("KeyTwo: {KeyTwo}", key2);
app.Logger.LogInformation("KeyThree: {KeyThree}", key3);

app.Run();

A fenti példában: appsettings.json

{
  ...
  "KeyOne": "Key One Value",
  "KeyTwo": 1999,
  "KeyThree": true
}

Beállítások konfigurálása meghatalmazottal

A konfigurációszolgáltatókban beállított delegált felülbírálási értékekben konfigurált beállítások.

A következő kódban egy IConfigureOptions<TOptions> szolgáltatás lesz hozzáadva a szolgáltatástárolóhoz. Ez egy delegáltat használ a következő értékek konfigurálásához MyOptions:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "Value configured in delegate";
    myOptions.Option2 = 500;
});

var app = builder.Build();

A következő kód a beállítások értékeit jeleníti meg:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

Az előző példában a Option1 és Option2 értékeket a appsettings.json-ben adjuk meg, majd a konfigurált meghatalmazott felülbírálja őket.

Gazdagép kontra alkalmazáskonfiguráció

Az alkalmazás konfigurálása és elindítása előtt egy gazdagépet konfigurálnak és indítanak el. A kiszolgáló felelős az alkalmazás indításáért és élettartam-kezeléséért. Az alkalmazás és a gazdagép is a jelen témakörben ismertetett konfigurációszolgáltatók használatával van konfigurálva. A gazdagépkonfigurációs kulcs-érték párok az alkalmazás konfigurációjában is szerepelnek. A gazdagép létrehozásakor használt konfigurációs szolgáltatókról és a konfigurációs források gazdagépkonfigurációra gyakorolt hatásáról további információt ASP.NET Alapvető alapismeretek áttekintése című témakörben talál.

Alapértelmezett host konfiguráció

A webes gazdagép használatakor az alapértelmezett konfigurációval kapcsolatos részletekért tekintse meg a jelen témakör ASP.NET Core 2.2-es verzióját.

• A gazdagép konfigurációja a következő forrásból érhető el:
  • Környezeti változók előtaggal DOTNET_ (például DOTNET_ENVIRONMENT) a Környezeti változók konfigurációszolgáltatót használva. A rendszer eltávolítja az előtagot (DOTNET_) a konfigurációs kulcs-érték párok betöltésekor.
  • Parancssori argumentumok a parancssori konfigurációszolgáltatóval.
• A webgazda alapértelmezett konfigurációja létrejött (ConfigureWebHostDefaults):
  • Kestrel webkiszolgálóként van használva, és az alkalmazás konfigurációs szolgáltatóinak használatával van konfigurálva.
  • Host szűrési middleware hozzáadása.
  • Adja hozzá a továbbított fejlécek middleware-t, ha a ASPNETCORE_FORWARDEDHEADERS_ENABLED környezeti változó értéke true.
  • IIS-integráció engedélyezése.

Egyéb konfiguráció

Ez a témakör csak az alkalmazáskonfigurációra vonatkozik. A ASP.NET Core-alkalmazások futtatásának és üzemeltetésének egyéb szempontjai a jelen témakörben nem tárgyalt konfigurációs fájlok használatával vannak konfigurálva:

• launch.json / launchSettings.json a fejlesztési környezet konfigurációs fájljainak eszközkészletét ismertetik:
  • ASP.NET Core futtatókörnyezetekben.
  • A dokumentációs csoportban, ahol a fájlok ASP.NET Core-alkalmazások fejlesztési forgatókönyvekhez való konfigurálásához használhatók.
• web.config a következő témakörökben ismertetett kiszolgálókonfigurációs fájl:
  • ASP.NET Core telepítése Windows operációs rendszeren IIS segítségével
  • ASP.NET Core modul (ANCM) IIS-hez

Az launchSettings.json környezeti változók felülírják a rendszerkörnyezetben beállított értékeket.

Az ASP.NET korábbi verzióiból történő alkalmazáskonfiguráció migrálásával kapcsolatos további információkért lásd: Konfiguráció áttelepítése ASP.NET Core-ba.

Konfiguráció hozzáadása külső szerelvényből

A IHostingStartup implementáció lehetővé teszi, hogy fejlesztéseket adjon hozzá egy alkalmazáshoz indításkor az alkalmazás Startup osztályán kívüli külső szerelvényből. További információért lásd: Hosztolási indító összetevők használata az ASP.NET Core-ban.

Konfigurációkötési forrásgenerátor

A konfigurációkötési forrásgenerátor AOT-t és vágásbarát konfigurációt biztosít. További információért lásd: Configuration-binding source generator.

További erőforrások

• Konfigurációs forráskód
• Mintakód megtekintése vagy letöltése (hogyan töltsd le)
• Beállításminta az ASP.NET Core-ban
• ASP.NET Core Blazor konfiguráció