Konfiguracja w ASP.NET Core

A także Rick Anderson i Larkin

Konfiguracja w ASP.NET Core jest wykonywana przy użyciu jednego lub większej liczby dostawców konfiguracji. Dostawcy konfiguracji odczytuje dane konfiguracji z par klucz-wartość przy użyciu różnych źródeł konfiguracji:

  • Ustawienia plików, takich jak appsettings.json
  • Zmienne środowiskowe
  • Azure Key Vault
  • Azure App Configuration
  • Argumenty wiersza polecenia
  • Dostawcy niestandardowi, zainstalowani lub utworzeni
  • Pliki katalogu
  • Obiekty .NET w pamięci

Ten temat zawiera informacje na temat konfiguracji w ASP.NET Core. Aby uzyskać informacje na temat używania konfiguracji w aplikacjach konsolowych, zobacz Konfiguracja programu .NET.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Konfiguracja domyślna

ASP.NET Core aplikacje internetowe utworzone za pomocą programu dotnet new Visual Studio wygeneruj następujący kod:

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder inicjuje nowe wystąpienie klasy WebApplicationBuilder ze wstępnie skonfigurowanymi wartościami domyślnymi. Zainicjowane WebApplicationBuilder ( builder ) zapewnia domyślną konfigurację aplikacji w następującej kolejności:

  1. ChainedConfigurationProvider: dodaje istniejący IConfiguration element jako źródło. W domyślnym przypadku konfiguracji program dodaje konfigurację hosta i ustawia ją jako pierwsze źródło konfiguracji aplikacji.
  2. appsettings.jsonprzy użyciu dostawcy konfiguracji JSON.
  3. appsettings. Environment Plik json przy użyciu dostawcy konfiguracji JSON. Na przykład appsettings. Produkcja_._json i appsettings.°Development** _._json*.
  4. Wpisy tajne aplikacji, gdy aplikacja działa w Development środowisku.
  5. Zmienne środowiskowe korzystające z dostawcy konfiguracji zmiennych środowiskowych.
  6. Argumenty wiersza polecenia przy użyciu dostawcy konfiguracji wiersza polecenia.

Dostawcy konfiguracji, którzy zostaną dodani później, przesłaniają poprzednie ustawienia klucza. Jeśli na przykład wartość jest ustawiona zarówno w środowisku, jak i MyKey , używana jest wartość appsettings.json środowiska. Przy użyciu domyślnych dostawców konfiguracji dostawca konfiguracji wiersza polecenia zastępuje wszystkich innych dostawców.

Aby uzyskać więcej informacji na temat CreateBuilder programu , zobacz Domyślne ustawienia konstruktora.

Poniższy kod wyświetla włączonych dostawców konfiguracji w kolejności, w których zostali dodani:

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

appsettings.json

Rozważmy następujący appsettings.json plik:

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

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Domyślna JsonConfigurationProvider konfiguracja ładowania jest następująca:

  1. appsettings.json
  2. appsettings. Environment .json: na przykład appsettings. Production_._json i appsettings.•Development** _._json* files. Wersja środowiska pliku jest ładowana na podstawie wartości IHostingEnvironment.EnvironmentName. Aby uzyskać więcej informacji, zobacz Używanie wielu środowisk na platformie ASP.NET Core.

appsettings Environment . Wartości JSON przesłaniają klucze appsettings.json w . Na przykład domyślnie:

  • Podczas opracowywania konfiguracji appsettings.Development _._json zastępuje wartości znalezione w pliku appsettings.json .
  • W środowisku produkcyjnym konfiguracja ustawień aplikacji .Production _._json zastępuje wartości znalezione w pliku appsettings.json . Na przykład podczas wdrażania aplikacji na platformie Azure.

Jeśli wartość konfiguracji musi być gwarantowana, zobacz GetValue. Poprzedni przykład tylko odczytuje ciągi i nie obsługuje wartości domyślnej.

Przy użyciu konfiguracji domyślnej wartości appsettings.json i appsettings. Environment Pliki json są włączane przy użyciu funkcji reloadOnChange: true. Zmiany wprowadzone w appsettings.json i appsettings. Environment Plik JSON po uruchamianiu aplikacji jest odczytywany przez dostawcę konfiguracji JSON.

Wiązanie danych konfiguracji hierarchicznej przy użyciu wzorca opcji

Preferowanym sposobem odczytywania powiązanych wartości konfiguracji jest użycie wzorca opcji. Na przykład, aby odczytać następujące wartości konfiguracji:

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

Utwórz następującą PositionOptions klasę:

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

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

Klasa opcji:

  • Musi być nie abstrakcyjny z publicznym konstruktorem bez parametrów.
  • Wszystkie publiczne właściwości typu do odczytu i zapisu są powiązane.
  • Pola nie powiązane. W poprzednim kodzie nie Position jest powiązana. Właściwość jest używana, aby nie trzeba było kodować ciągu w aplikacji podczas wiązania klasy Position "Position" z dostawcą konfiguracji.

Następujący kod:

  • Wywołuje ConfigurationBinder.Bind, aby powiązać PositionOptions klasę z Position sekcją .
  • Wyświetla Position dane konfiguracji.
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}");
    }
}

W poprzednim kodzie domyślnie są odczytywane zmiany w pliku konfiguracji JSON po jej zakończeniu.

ConfigurationBinder.Get<T> Powiązywa i zwraca określony typ. ConfigurationBinder.Get<T> może być wygodniejszy niż ConfigurationBinder.Bind użycie . Poniższy kod pokazuje, jak używać klasy ConfigurationBinder.Get<T> PositionOptions z klasą :

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}");
    }
}

W poprzednim kodzie domyślnie są odczytywane zmiany w pliku konfiguracji JSON po jej zakończeniu.

Alternatywnym podejściem w przypadku używania wzorca* opcji _ jest powiązanie sekcji i dodanie jej do kontenera usługi Position wstrzykiwania zależności. Poniższy kod jest dodawany do kontenera usługi za pomocą i PositionOptions <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> powiązany z konfiguracją:

using ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Korzystając z poprzedniego kodu, poniższy kod odczytuje opcje pozycji:

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}");
    }
}

W poprzednim kodzie zmiany w pliku konfiguracji JSON po jej uruchomieniu nie są odczytywane. Aby odczytać zmiany po jej uruchomiona, użyj IOptionsSnapshot.

Przy użyciu konfiguracji domyślnej wartości appsettings.json i appsettings. Environment Pliki json są włączane przy użyciu funkcji reloadOnChange: true. Zmiany wprowadzone w appsettings.json i appsettings. Environment Plik JSON po uruchamianiu aplikacji jest odczytywany przez dostawcę konfiguracji JSON.

Zobacz dostawca konfiguracji JSON w tym dokumencie, aby uzyskać informacje na temat dodawania dodatkowych plików konfiguracji JSON.

Łączenie kolekcji usług

Należy wziąć pod uwagę następujące kwestie, które rejestrowały usługi i konfigurowały opcje:

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();

Powiązane grupy rejestracji można przenieść do metody rozszerzenia w celu zarejestrowania usług. Na przykład usługi konfiguracji są dodawane do następującej klasy:

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

Pozostałe usługi są rejestrowane w podobnej klasie. Poniższy kod używa nowych metod rozszerzenia do rejestrowania usług:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddRazorPages();

var app = builder.Build();

Uwaga: Każda services.Add{GROUP_NAME} metoda rozszerzenia dodaje i potencjalnie konfiguruje usługi. Na przykład program AddControllersWithViews dodaje wymagane kontrolery MVC usług z widokami i AddRazorPages dodaje usługi wymagane przez Razor usługę Pages. Zalecamy, aby aplikacje postępowały zgodnie z konwencją nazewnictwa tworzenia metod rozszerzeń w przestrzeni Microsoft.Extensions.DependencyInjection nazw . Tworzenie metod rozszerzeń w przestrzeni Microsoft.Extensions.DependencyInjection nazw :

Zabezpieczenia i wpisy tajne użytkowników

Wytyczne dotyczące danych konfiguracji:

  • Nigdy nie przechowuj haseł ani innych poufnych danych w kodzie dostawcy konfiguracji ani w plikach konfiguracji w postaci zwykłego tekstu. Narzędzie Secret Manager może służyć do przechowywania wpisów tajnych w programie.
  • Nie używaj wpisów tajnych produkcji w środowiskach deweloperskich ani testowych.
  • Określ wpisy tajne poza projektem, aby nie można było ich przypadkowo zatwierdzona w repozytorium kodu źródłowego.

Domyślnie źródłokonfiguracji wpisów tajnych użytkownika jest rejestrowane po źródłach konfiguracji JSON. W związku z tym klucze wpisów tajnych użytkowników mają pierwszeństwo przed kluczami w ustawieniach appsettings.json i appsettings. Environment .json.

Aby uzyskać więcej informacji na temat przechowywania haseł lub innych poufnych danych:

Azure Key Vault bezpiecznie przechowuje wpisy tajne aplikacji dla ASP.NET Core aplikacji. Aby uzyskać więcej informacji, zobacz Azure Key Vault konfiguracji w programie ASP.NET Core.

Zmienne środowiskowe

Przy użyciu konfiguracji domyślnej ładuje konfigurację z par klucz-wartość zmiennej środowiskowej EnvironmentVariablesConfigurationProvider po odczytaniu wartości , appsettings.json appsettings. Environment .json i wpisy tajne użytkownika. W związku z tym wartości kluczy odczytane ze środowiska zastępują wartości odczytane z appsettings.json metody , appsettings. Environment .json i wpisy tajne użytkownika.

Separator : nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. __, podwójny podkreślenie, to:

  • Obsługiwane przez wszystkie platformy. Na przykład separator : nie jest obsługiwany przez powłokę Bash, ale __ jest.
  • Automatycznie zastępowane przez :

Następujące set polecenia:

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

Powyższe ustawienia środowiska:

  • Są ustawiane tylko w procesach uruchomionych z okna poleceń, w których zostały ustawione.
  • Nie będą odczytywane przez przeglądarki uruchomione z Visual Studio.

Następujące polecenia setx mogą służyć do ustawienia kluczy i wartości środowiska na Windows. W set przeciwieństwie do , ustawienia są setx utrwalane. /M Ustawia zmienną w środowisku systemowym. Jeśli przełącznik /M nie jest używany, ustawiana jest zmienna środowiskowa użytkownika.

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

Aby sprawdzić, czy poprzednie polecenia appsettings.json przesłaniają ustawienia i appsettings. Environment .json:

  • W Visual Studio: Zamknij i uruchom ponownie Visual Studio.
  • Za pomocą interfejsu wiersza polecenia: uruchom nowe okno polecenia i wprowadź dotnet run polecenie .

Wywołaj AddEnvironmentVariables z ciągiem , aby określić prefiks dla zmiennych środowiskowych:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Powyższy kod ma następujące działanie:

Prefiks jest wyłączany podczas odczytywania par klucz-wartość konfiguracji.

Następujące polecenia testuje niestandardowy prefiks:

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

Domyślna konfiguracja ładuje zmienne środowiskowe i argumenty wiersza polecenia poprzedzone prefiksami DOTNET_ i ASPNETCORE_ . Prefiksy i są używane przez ASP.NET Core konfiguracji hosta i DOTNET_ ASPNETCORE_ aplikacji,ale nie w przypadku konfiguracji użytkownika. Aby uzyskać więcej informacji na temat konfiguracji hosta i aplikacji, zobacz .NET Generic Host.

Na Azure App Servicewybierz pozycję Nowe ustawienie aplikacji na stronie Ustawienia > Konfiguracji aplikacji. Azure App Service aplikacji są:

  • Szyfrowane w spoczynku i przesyłane za pośrednictwem szyfrowanego kanału.
  • Widoczne jako zmienne środowiskowe.

Aby uzyskać więcej informacji, zobacz Azure Apps: Override app configuration using the Azure Portal (Azure Apps: przesłanianie konfiguracji aplikacji przy użyciu witryny Azure Portal).

Aby uzyskać informacje na temat parametrów połączenia bazy danych platformy Azure, zobacz Prefiksy parametrów połączenia.

Nazewnictwo zmiennych środowiskowych

Nazwy zmiennych środowiskowych odzwierciedlają strukturę appsettings.json pliku. Każdy element w hierarchii jest oddzielony podwójnym podkreśleniem (preferowanym) lub dwukropkiem. Gdy struktura elementów zawiera tablicę, indeks tablicy powinien być traktowany jako dodatkowa nazwa elementu w tej ścieżce. Rozważmy następujący appsettings.json plik i jego równoważne wartości reprezentowane jako zmienne środowiskowe.

appsettings.json

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

zmienne środowiskowe

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

Zmienne środowiskowe ustawione w wygenerowanym launchSettings.json

Zmienne środowiskowe ustawione w launchSettings.json zastępują te ustawione w środowisku systemowym. Na przykład szablony ASP.NET Core generują plik launchSettings.json, który ustawia konfigurację punktu końcowego na:

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

Skonfigurowanie applicationUrl ustawia zmienną ASPNETCORE_URLS środowiskową i zastępuje wartości ustawione w środowisku.

Zmienne środowiskowe ucieczki w systemie Linux

W systemie Linux należy zmienić wartość zmiennych środowiskowych adresu URL, aby systemd można było ją analizujeć. Korzystanie z narzędzia systemu systemd-escape Linux, które daje http:--localhost:5001

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

Wyświetlanie zmiennych środowiskowych

Poniższy kod wyświetla zmienne środowiskowe i wartości podczas uruchamiania aplikacji, co może być przydatne podczas debugowania ustawień środowiska:

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

var config = app.Services.GetRequiredService<IConfiguration>();

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

Wiersz polecenia

Przy użyciu konfiguracji domyślnej ładuje konfigurację z wiersza polecenia CommandLineConfigurationProvider pary klucz-wartość argumentu po następujących źródłach konfiguracji:

  • appsettings.json i appsettings Environment . pliki json.
  • Wpisy tajne aplikacji w środowisku dewelopera.
  • Zmienne środowiskowe.

Domyślnie wartościkonfiguracji ustawione w wierszu polecenia zastępują wartości konfiguracji ustawione dla wszystkich innych dostawców konfiguracji.

Argumenty wiersza polecenia

Następujące polecenie ustawia klucze i wartości przy użyciu = polecenia :

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

Następujące polecenie ustawia klucze i wartości przy użyciu / polecenia :

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

Następujące polecenie ustawia klucze i wartości przy użyciu -- polecenia :

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

Wartość klucza:

  • Musi być zgodna z wartością , lub klucz musi = mieć prefiks lub , gdy wartość następuje po -- / spacji.
  • Nie jest wymagane, jeśli = jest używany. Na przykład MySetting=.

W ramach tego samego polecenia nie mieszaj par klucz-wartość argumentu wiersza polecenia, które używają z = parami klucz-wartość, które używają spacji.

Mapowania przełączników

Mapowania przełączników zezwalają na logikę zastępowania nazw kluczy. Podaj słownik zastąpień przełącznika dla AddCommandLine metody .

Gdy słownik mapowań przełącznika jest używany, słownik jest sprawdzany pod kątem klucza zgodnego z kluczem dostarczonym przez argument wiersza polecenia. Jeśli klucz wiersza polecenia zostanie znaleziony w słowniku, wartość słownika zostanie przekazana z powrotem, aby ustawić parę klucz-wartość w konfiguracji aplikacji. Mapowanie przełącznika jest wymagane dla dowolnego klucza wiersza polecenia poprzedzonego pojedynczym łącznikiem ( - ).

Reguły kluczy słownika mapowania przełączników:

  • Przełączniki muszą zaczynać się od - lub -- .
  • Słownik mapowań przełącznika nie może zawierać zduplikowanych kluczy.

Aby użyć słownika mapowań przełącznika, przekaż go do wywołania 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();

Uruchom następujące polecenie, aby przetestować zastąpienie klucza:

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

Poniższy kod przedstawia wartości kluczy dla zastąpionych kluczy:

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"]}'");
    }
}

W przypadku aplikacji, które używają mapowań przełączników, wywołanie funkcji nie CreateDefaultBuilder powinno przekazywać argumentów. Wywołanie metody nie zawiera zamapowanych przełączników i nie ma możliwości przekazania słownika mapowania przełączników CreateDefaultBuilder AddCommandLine do metody CreateDefaultBuilder . Rozwiązanie nie służy do przekazania argumentów do metody , ale umożliwia metodzie przetwarzanie zarówno argumentów, jak i CreateDefaultBuilder ConfigurationBuilder AddCommandLine słownika mapowania przełączników.

Ustawianie argumentów środowiska i wiersza polecenia za pomocą Visual Studio

Argumenty środowiska i wiersza polecenia można ustawić w Visual Studio w oknie dialogowym profilów uruchamiania:

  • W Eksplorator rozwiązań prawym przyciskiem kliknij projekt i wybierz pozycję Właściwości.
  • Wybierz kartę Debuguj > Ogólne i wybierz pozycję Otwórz interfejs użytkownika profilów uruchamiania debugowania.

Hierarchiczne dane konfiguracji

Interfejs API konfiguracji odczytuje dane konfiguracji hierarchicznej, spłaszczając dane hierarchiczne przy użyciu ogranicznika w kluczach konfiguracji.

Przykładowy plik do pobrania zawiera następujący appsettings.json plik:

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

Poniższy kod z przykładowego pobierania zawiera kilka ustawień konfiguracji:

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}");
    }
}

Preferowanym sposobem odczytywania danych konfiguracji hierarchicznej jest użycie wzorca opcji. Aby uzyskać więcej informacji, zobacz Wiązanie hierarchicznych danych konfiguracji w tym dokumencie.

GetSection Metody i są dostępne do izolowania sekcji i poszczególnych GetChildren części sekcji w danych konfiguracji. Te metody zostały opisane w dalszej części sekcji GetSection, Get Wyliczy i Istnieje.

Klucze i wartości konfiguracji

Klucze konfiguracji:

  • Bez uwzględniania liter. Na przykład i ConnectionString są traktowane jako klucze connectionstring równoważne.
  • Jeśli klucz i wartość są ustawione dla więcej niż jednego dostawcy konfiguracji, używana jest wartość z ostatniego dodanego dostawcy. Aby uzyskać więcej informacji, zobacz Konfiguracja domyślna.
  • Klucze hierarchiczne
    • W interfejsie API konfiguracji separator dwukropka ( : ) działa na wszystkich platformach.
    • W zmiennych środowiskowych separator dwukropka może nie działać na wszystkich platformach. Podwójny podkreślenia, __ , jest obsługiwany przez wszystkie platformy i jest automatycznie konwertowany na dwukropek : .
    • W Azure Key Vault jako separatora są -- używać klucze hierarchiczne. Dostawca Azure Key Vault automatycznie zastępuje plik , gdy wpisy tajne zostaną załadowane do konfiguracji -- : aplikacji.
  • Obiekt ConfigurationBinder obsługuje powiązanie tablic z obiektami przy użyciu indeksów tablic w kluczach konfiguracji. Powiązanie tablicy jest opisane w sekcji Wiązanie tablicy z klasą.

Wartości konfiguracji:

  • Są ciągami.
  • Wartości null nie mogą być przechowywane w konfiguracji ani powiązane z obiektami.

Dostawcy konfiguracji

W poniższej tabeli przedstawiono dostawców konfiguracji dostępnych dla ASP.NET Core aplikacji.

Dostawca Zapewnia konfigurację z
Azure Key Vault konfiguracji Azure Key Vault
Dostawca konfiguracji aplikacji platformy Azure Azure App Configuration
Dostawca konfiguracji wiersza polecenia Parametry wiersza polecenia
Niestandardowy dostawca konfiguracji Źródło niestandardowe
Dostawca konfiguracji zmiennych środowiskowych Zmienne środowiskowe
Dostawca konfiguracji plików Pliki INI, JSON i XML
Dostawca konfiguracji klucza na plik Pliki katalogu
Dostawca konfiguracji pamięci Kolekcje w pamięci
Wpisy tajne użytkowników Plik w katalogu profilu użytkownika

Źródła konfiguracji są odczytywane w kolejności, w których określono ich dostawców konfiguracji. Zamów dostawców konfiguracji w kodzie, aby dopasować je do priorytetów bazowych źródeł konfiguracji wymaganych przez aplikację.

Typowa sekwencja dostawców konfiguracji to:

  1. appsettings.json
  2. appsettings Environment . json
  3. Wpisy tajne użytkowników
  4. Zmienne środowiskowe korzystające z dostawcy konfiguracji zmiennych środowiskowych.
  5. Argumenty wiersza polecenia przy użyciu dostawcy konfiguracji wiersza polecenia.

Powszechną praktyką jest dodanie dostawcy konfiguracji wiersza polecenia jako ostatniego z serii dostawców, aby umożliwić argumentom wiersza polecenia przesłonięcie konfiguracji ustawionej przez innych dostawców.

Poprzednia sekwencja dostawców jest używana w konfiguracji domyślnej.

Prefiksy parametrów połączenia

Interfejs API konfiguracji ma specjalne reguły przetwarzania dla czterech zmiennych środowiskowych parametrów połączenia. Te parametry połączenia są związane z konfigurowaniem ciągów połączeń platformy Azure dla środowiska aplikacji. Zmienne środowiskowe z prefiksami wyświetlanymi w tabeli są ładowane do aplikacji z konfiguracją domyślną lub gdy prefiks nie jest podany w pliku AddEnvironmentVariables .

Prefiks parametrów połączenia Dostawca
CUSTOMCONNSTR_ Dostawca niestandardowy
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

Gdy zmienna środowiskowa zostanie odnaleziona i załadowana do konfiguracji z dowolnym z czterech prefiksów pokazanych w tabeli:

  • Klucz konfiguracji jest tworzony przez usunięcie prefiksu zmiennej środowiskowej i dodanie sekcji klucza konfiguracji ( ConnectionStrings ).
  • Tworzona jest nowa para klucz-wartość konfiguracji, która reprezentuje dostawcę połączenia z bazą danych (z wyjątkiem , który CUSTOMCONNSTR_ nie ma podanego dostawcy).
Klucz zmiennej środowiskowej Przekonwertowany klucz konfiguracji Wpis konfiguracji dostawcy
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Nie utworzono wpisu konfiguracji.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName :
Wartość: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName :
Wartość: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName :
Wartość: System.Data.SqlClient

Dostawca konfiguracji plików

FileConfigurationProvider to klasa bazowa do ładowania konfiguracji z systemu plików. Następujący dostawcy konfiguracji pochodzą z FileConfigurationProvider programu :

Dostawca konfiguracji INI

Konfiguracja IniConfigurationProvider ładuje z pary klucz-wartość pliku INI w czasie wykonywania.

Poniższy kod powoduje wyczyszczenie wszystkich dostawców konfiguracji i dodanie kilku dostawców konfiguracji: [!code-csharp]

W poprzednim kodzie ustawienia w plikachMyIniConfig.ini MyIniConfig Environment . Pliki ini są zastępowany przez ustawienia w:

Przykładowy plik do pobrania zawiera następującyMyIniConfig.ini plików:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Dostawca konfiguracji JSON

Konfiguracja JsonConfigurationProvider ładuje z par klucz-wartość pliku JSON.

Przeciążenia mogą określać:

  • Czy plik jest opcjonalny.
  • Określa, czy konfiguracja zostanie ponownie załadowana, jeśli plik się zmieni.

Spójrzmy na poniższy kod:

using Microsoft.Extensions.DependencyInjection.ConfigSample.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyConfig.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Powyższy kod ma następujące działanie:

  • Konfiguruje dostawcę konfiguracji JSON do ładowania pliku MyConfig.json przy użyciu następujących opcji:
    • optional: true: plik jest opcjonalny.
    • reloadOnChange: true : plik jest ponownie ładowany po zapisaniu zmian.
  • Odczytuje domyślnych dostawców konfiguracji przed plikiem MyConfig.json. Ustawienia w ustawieniu przesłonięcia pliku MyConfig.json w domyślnych dostawcach konfiguracji, w tym dostawcy konfiguracji zmiennych środowiskowych i dostawcy konfiguracji wiersza polecenia.

Zazwyczaj nie chcesz, aby niestandardowy plik JSON przesłaniał wartości ustawione w dostawcy konfiguracji zmiennych środowiskowych i dostawcy konfiguracji wiersza polecenia.

Dostawca konfiguracji XML

Konfiguracja XmlConfigurationProvider ładuje z pary klucz-wartość pliku XML w czasie wykonywania.

Poniższy kod powoduje wyczyszczenie wszystkich dostawców konfiguracji i dodanie kilku dostawców konfiguracji:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    var env = hostingContext.HostingEnvironment;

    config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
          .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                         optional: true, reloadOnChange: true);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

W poprzednim kodzie ustawienia w plikach MyXMLFile.xml MyXMLFile Environment . Pliki xml są zastępowany przez ustawienia w:

Przykładowy plik do pobrania zawiera następującyMyXMLFile.xml plików:

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

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Powtarzanie elementów, które używają tej samej nazwy elementu, działa, jeśli name atrybut jest używany do odróżnienia elementów:

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

Poniższy kod odczytuje poprzedni plik konfiguracji i wyświetla klucze i wartości:

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"
                       );
    }
}

Atrybuty mogą służyć do dostarczania wartości:

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

Poprzedni plik konfiguracji ładuje następujące klucze za value pomocą :

  • key:attribute
  • section:key:attribute

Dostawca konfiguracji klucza na plik

Element KeyPerFileConfigurationProvider używa plików katalogu jako par klucz-wartość konfiguracji. Klucz jest nazwą pliku. Wartość zawiera zawartość pliku. Dostawca konfiguracji klucza na plik jest używany w scenariuszach hostingu platformy Docker.

Aby aktywować konfigurację klucza dla pliku, AddKeyPerFile wywołaj metodę rozszerzenia w wystąpieniu klasy ConfigurationBuilder . Element directoryPath do plików musi być ścieżką bezwzględną.

Przeciążenia umożliwiają określenie:

  • Delegat Action<KeyPerFileConfigurationSource> konfigurujący źródło.
  • Czy katalog jest opcjonalny i czy ścieżka do katalogu.

Podwójny znak podkreślenia ( ) jest używany jako ogranicznik klucza __ konfiguracji w nazwach plików. Na przykład nazwa pliku generuje Logging__LogLevel__System klucz konfiguracji Logging:LogLevel:System .

Wywołaj ConfigureAppConfiguration wywołanie podczas budowania hosta, aby określić konfigurację aplikacji:

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

Dostawca konfiguracji pamięci

Element MemoryConfigurationProvider używa kolekcji w pamięci jako par klucz-wartość konfiguracji.

Poniższy kod dodaje kolekcję pamięci do systemu konfiguracji:

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.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();

    config.AddInMemoryCollection(Dict);

    config.AddEnvironmentVariables();

    if (args != null)
    {
        config.AddCommandLine(args);
    }
});

builder.Services.AddRazorPages();

var app = builder.Build();

Poniższy kod z przykładowego pobierania wyświetla poprzednie ustawienia konfiguracji:

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}");
    }
}

W poprzednim kodzie jest config.AddInMemoryCollection(Dict) dodawany po domyślnych dostawcach konfiguracji. Aby uzyskać przykład zamawiania dostawców konfiguracji, zobacz JSON configuration provider (Dostawca konfiguracji JSON).

Zobacz Bind an array for another example using (Powiązycie tablicy z innym przykładem przy użyciu funkcji MemoryConfigurationProvider ).

Kestrel konfiguracja punktu końcowego

Kestrel Konfiguracja określonego punktu końcowego zastępuje wszystkie konfiguracje punktów końcowych między serwerami. Konfiguracje punktów końcowych między serwerami obejmują:

Rozważmy następujący appsettings.json plik używany w ASP.NET Core internetowej:

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

Gdy poprzedni wyróżniony znacznik jest używany w aplikacji ASP.NET Core internetowej, a aplikacja jest uruchomiona w wierszu polecenia z następującą konfiguracją punktu końcowego między serwerami:

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

Kestrel wiąże się z punktem końcowym skonfigurowanym specjalnie dla Kestrel programu w pliku ( ), a nie appsettings.json https://localhost:9999 https://localhost:7777 .

Rozważ konkretny Kestrel punkt końcowy skonfigurowany jako zmienna środowiskowa:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

W poprzedniej zmiennej środowiskowej Https jest nazwą określonego punktu Kestrel końcowego. Powyższy plik appsettings.json definiuje również określony punkt końcowy o nazwie Kestrel Https . Domyślnie zmienneśrodowiskowe używające dostawcy konfiguracji Zmienne środowiskowe są odczytywane po ustawieniach appsettings. Environment W związku z tym dla punktu końcowego jest używana wcześniejsza zmienna Https środowiskowa .json.

GetValue

ConfigurationBinder.GetValue<T> wyodrębnia pojedynczą wartość z konfiguracji przy użyciu określonego klucza i konwertuje ją na określony typ:

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}");
    }
}

W poprzednim kodzie, jeśli nie NumberKey zostanie odnaleziony w konfiguracji, używana jest wartość 99 domyślna .

GetSection, Get Exists i GetSection

W poniższych przykładach rozważ następujący plik MySubsection.json:

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

Poniższy kod dodaje plik MySubsection.json do dostawców konfiguracji:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MySubsection.json",
                       optional: true,
                       reloadOnChange: true);
});

builder.Services.AddRazorPages();

var app = builder.Build();

Getsection

IConfiguration.GetSection zwraca podsekcję konfiguracji z określonym kluczem podsekcji.

Poniższy kod zwraca wartości dla section1 :

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"]}'");
    }
}

Poniższy kod zwraca wartości dla section2:subsection0 :

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 nigdy nie null zwraca . Jeśli nie znaleziono pasującej sekcji, zwracana IConfigurationSection jest pusta.

W GetSection przypadku zwracania pasującej sekcji Value wartość nie jest wypełniana. I Key Path są zwracane, gdy sekcja istnieje.

Get Nie można uzyskać informacji i istnieje

Poniższy kod wywołuje IConfiguration.Get Wyliczek i zwraca wartości dla 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);
    }
}

Powyższy kod wywołuje plik ConfigurationExtensions.Exists, aby sprawdzić, czy sekcja istnieje:

Wiązanie tablicy

ConfigurationBinder.Bind obsługuje powiązanie tablic z obiektami przy użyciu indeksów tablic w kluczach konfiguracji. Każdy format tablicy, który uwidacznia segment klucza liczbowego, jest w stanie powiązań tablicy z tablicą klas POCO.

Rozważmy plik MyArray.json z przykładowego pliku do pobrania:

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

Poniższy kod dodaje plik MyArray.json do dostawców konfiguracji:

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile("MyArray.json",
                        optional: true,
                        reloadOnChange: true); ;
});

builder.Services.AddRazorPages();

var app = builder.Build();

Poniższy kod odczytuje konfigurację i wyświetla wartości:

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

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

    public ContentResult OnGet()
    {
        if (_array == null)
        {
            throw new ArgumentNullException(nameof(_array));
        }

        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = String.Empty;

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

        return Content(s);
    }
}

Powyższy kod zwraca następujące dane wyjściowe:

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

W poprzednich danych wyjściowych indeks 3 ma wartość value40 , odpowiadającą wartości "4": "value40", w myArray.json. Powiązane indeksy tablicowe są ciągłe i nie są powiązane z indeksem kluczy konfiguracji. Konfigurator nie może powiązać wartości null ani tworzyć wpisów null w powiązanych obiektach.

Niestandardowy dostawca konfiguracji

Przykładowa aplikacja pokazuje, jak utworzyć podstawowego dostawcę konfiguracji, który odczytuje pary klucz-wartość konfiguracji z bazy danych przy użyciu Entity Framework (EF).

Dostawca ma następujące cechy:

  • Baza danych EF w pamięci jest używana w celach demonstracyjnych. Aby użyć bazy danych, która wymaga parametrów połączenia, należy zaimplementować pomocniczą bazę danych w celu ConfigurationBuilder dostarczania parametrów połączenia od innego dostawcy konfiguracji.
  • Dostawca odczytuje tabelę bazy danych do konfiguracji podczas uruchamiania. Dostawca nie odpytuje bazy danych na podstawie klucza.
  • Ponowne ładowanie przy zmianie nie jest zaimplementowane, dlatego zaktualizowanie bazy danych po jej uruchamianiu nie ma wpływu na konfigurację aplikacji.

EFConfigurationValueZdefiniuj jednostkę do przechowywania wartości konfiguracji w bazie danych.

Models/EFConfigurationValue.cs:

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

Dodaj element EFConfigurationContext do przechowywania skonfigurowanych wartości i uzyskiwania do nich dostępu.

EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Utwórz klasę, która implementuje IConfigurationSource klasę .

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

Utwórz niestandardowego dostawcę konfiguracji, dziedzicząc ConfigurationProvider z . Dostawca konfiguracji inicjuje bazę danych, gdy jest pusta. Ponieważ w kluczach konfiguracji nie jest roz rozsyłana litera, słownik używany do inicjowania bazy danych jest tworzony za pomocą porównującego bez uwzględniania liter(StringComparer.OrdinalIgnoreCase).

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

Metoda AddEFConfiguration rozszerzenia umożliwia dodawanie źródła konfiguracji do pliku ConfigurationBuilder .

Extensions/EntityFrameworkExtensions.cs:

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

Poniższy kod pokazuje, jak używać niestandardowego w EFConfigurationProvider program.cs:

//using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.Run();

Konfiguracja dostępu na Razor stronach

Poniższy kod wyświetla dane konfiguracji na Razor stronie:

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

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

Poniższy kod jest dodawany do kontenera usługi za pomocą i MyOptions Configure powiązany z konfiguracją:

using SampleApp.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

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

var app = builder.Build();

Następujący kod używa dyrektywy @inject Razor do rozpoznawania i wyświetlania wartości opcji:

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

Konfiguracja dostępu w pliku widoku MVC

Poniższy kod wyświetla dane konfiguracji w widoku MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Konfigurowanie opcji przy użyciu delegata

Opcje skonfigurowane w delegacie przesłaniają wartości ustawione w dostawcach konfiguracji.

W poniższym kodzie usługa IConfigureOptions<TOptions> jest dodawana do kontenera usługi. Używa delegata do skonfigurowania wartości MyOptions dla :

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();

Poniższy kod wyświetla wartości opcji:

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}");
    }
}

W poprzednim przykładzie wartości i są określone w , a następnie zastąpione przez Option1 Option2 appsettings.json skonfigurowanego delegata.

Konfiguracja hosta a aplikacji

Przed skonfigurowaniem i rozpoczęciem konfigurowania i uruchomiania aplikacji host jest konfigurowany i uruchomiony. Host jest odpowiedzialny za uruchamianie aplikacji i zarządzanie okresem istnienia. Zarówno aplikacja, jak i host są konfigurowane przy użyciu dostawców konfiguracji opisanych w tym temacie. Pary klucz-wartość konfiguracji hosta są również uwzględniane w konfiguracji aplikacji. Aby uzyskać więcej informacji na temat sposobu korzystania z dostawców konfiguracji podczas budów hosta i wpływu źródeł konfiguracji na konfigurację hosta, zobacz Platforma ASP.NET Core — podstawy .

Domyślna konfiguracja hosta

Aby uzyskać szczegółowe informacje na temat konfiguracji domyślnej podczas korzystania z hosta sieci Web,zobacz ASP.NET Core 2.2 wersji tego tematu.

  • Konfiguracja hosta jest zapewniana z:
    • Zmienne środowiskowe poprzedzone DOTNET_ prefiksem (na przykład DOTNET_ENVIRONMENT ) przy użyciu dostawcy konfiguracji zmiennych środowiskowych. Prefiks ( DOTNET_ ) jest usuwania podczas ładowania par klucz-wartość konfiguracji.
    • Argumenty wiersza polecenia przy użyciu dostawcy konfiguracji wiersza polecenia.
  • Domyślną konfigurację hosta sieci Web jest ustanowiona ( ConfigureWebHostDefaults ):
    • Kestrel jest używany jako serwer internetowy i konfigurowany przy użyciu dostawców konfiguracji aplikacji.
    • Dodaj oprogramowanie pośredniczące filtrowania hosta.
    • Dodaj oprogramowanie pośredniczące Nagłówki dalej, jeśli ASPNETCORE_FORWARDEDHEADERS_ENABLED zmienna środowiskowa jest ustawiona na true .
    • Włączanie integracji usług IIS.

Inna konfiguracja

Ten temat dotyczy tylko konfiguracji aplikacji. Inne aspekty uruchamiania i hostowania aplikacji ASP.NET Core są konfigurowane przy użyciu plików konfiguracji, które nie zostały uwzględnione w tym temacie:

Zmienne środowiskowe ustawione w launchSettings.json zastępują te ustawione w środowisku systemowym.

Aby uzyskać więcej informacji na temat migrowania konfiguracji aplikacji ze starszych wersji ASP.NET, zobacz Migrowanie z ASP.NET do ASP.NET Core .

Dodawanie konfiguracji z zestawu zewnętrznego

Implementacja umożliwia dodawanie ulepszeń do aplikacji podczas uruchamiania z zewnętrznego zestawu IHostingStartup poza klasą Startup aplikacji. Aby uzyskać więcej informacji, zobacz Używanie hostowania zestawów startowych w programie ASP.NET Core.

Dodatkowe zasoby

Konfiguracja w ASP.NET Core jest wykonywana przy użyciu jednego lub większej liczby dostawców konfiguracji. Dostawcy konfiguracji odczytuje dane konfiguracji z par klucz-wartość przy użyciu różnych źródeł konfiguracji:

  • Ustawienia plików, takich jak appsettings.json
  • Zmienne środowiskowe
  • Azure Key Vault
  • Azure App Configuration
  • Argumenty wiersza polecenia
  • Dostawcy niestandardowi, zainstalowani lub utworzeni
  • Pliki katalogu
  • Obiekty .NET w pamięci

Ten temat zawiera informacje na temat konfiguracji w ASP.NET Core. Aby uzyskać informacje na temat używania konfiguracji w aplikacjach konsolowych, zobacz Konfiguracja programu .NET.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Konfiguracja domyślna

ASP.NET Core aplikacje internetowe utworzone za pomocą programu dotnet new Visual Studio wygeneruj następujący kod:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder Udostępnia domyślną konfigurację aplikacji w następującej kolejności:

  1. ChainedConfigurationProvider: dodaje istniejący IConfiguration element jako źródło. W domyślnym przypadku konfiguracji program dodaje konfigurację hosta i ustawia ją jako pierwsze źródło konfiguracji aplikacji.
  2. appsettings.jsonprzy użyciu dostawcy konfiguracji JSON.
  3. appsettings. Environment Plik json przy użyciu dostawcy konfiguracji JSON. Na przykład appsettings. *Produkcja _._json i appsettings.].Development _._json.
  4. Wpisy tajne aplikacji, gdy aplikacja działa w Development środowisku.
  5. Zmienne środowiskowe korzystające z dostawcy konfiguracji zmiennych środowiskowych.
  6. Argumenty wiersza polecenia używające dostawcy konfiguracji wiersza polecenia.

Dostawcy konfiguracji, którzy zostaną dodani później, przesłaniają poprzednie ustawienia klucza. Jeśli na przykład wartość jest ustawiona zarówno w środowisku, jak i MyKey w appsettings.json środowisku, używana jest wartość środowiska. Przy użyciu domyślnych dostawców konfiguracji dostawca konfiguracji wiersza polecenia zastępuje wszystkich innych dostawców.

Aby uzyskać więcej informacji na temat CreateDefaultBuilder programu , zobacz Domyślne ustawienia konstruktora.

Poniższy kod wyświetla włączonych dostawców konfiguracji w kolejności, w których zostali dodani:

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

appsettings.json

Rozważmy następujący appsettings.json plik:

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

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Domyślna JsonConfigurationProvider konfiguracja ładowania jest następująca:

  1. appsettings.json
  2. appsettings. Environment .json: na przykład appsettings. Production_._json i appsettings.•Development** _._json* files. Wersja środowiska pliku jest ładowana na podstawie wartości IHostingEnvironment.EnvironmentName. Aby uzyskać więcej informacji, zobacz Używanie wielu środowisk na platformie ASP.NET Core.

appsettings Environment . Wartości JSON przesłaniają klucze appsettings.json w . Na przykład domyślnie:

  • Podczas opracowywania konfiguracji appsettings.Development _._json zastępuje wartości znalezione w pliku appsettings.json .
  • W środowisku produkcyjnym konfiguracja appsettings.Production _._json zastępuje wartości znalezione w pliku appsettings.json . Na przykład podczas wdrażania aplikacji na platformie Azure.

Jeśli wartość konfiguracji musi być gwarantowana, zobacz GetValue. Poprzedni przykład tylko odczytuje ciągi i nie obsługuje wartości domyślnej.

Przy użyciu konfiguracji domyślnej wartości appsettings.json i appsettings. Environment Pliki json są włączone z reloadOnChange: true. Zmiany wprowadzone w appsettings.json i appsettings. Environment Plik JSON po uruchamianiu aplikacji jest odczytywany przez dostawcę konfiguracji JSON.

Wiązanie danych konfiguracji hierarchicznej przy użyciu wzorca opcji

Preferowanym sposobem odczytywania powiązanych wartości konfiguracji jest użycie wzorca opcji. Na przykład aby odczytać następujące wartości konfiguracji:

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

Utwórz następującą PositionOptions klasę:

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

    public string Title { get; set; }
    public string Name { get; set; }
}

Klasa opcji:

  • Musi być nie abstrakcyjny z publicznym konstruktorem bez parametrów.
  • Wszystkie publiczne właściwości typu do odczytu i zapisu są powiązane.
  • Pola nie powiązane. W poprzednim kodzie nie Position jest powiązana. Właściwość jest używana, aby nie trzeba było zakodować ciągu w aplikacji podczas wiązania klasy Position "Position" z dostawcą konfiguracji.

Następujący kod:

  • Wywołuje ConfigurationBinder.Bind, aby powiązać PositionOptions klasę z Position sekcją .
  • Wyświetla Position dane konfiguracji.
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}");
    }
}

W poprzednim kodzie domyślnie są odczytywane zmiany w pliku konfiguracji JSON po jej zakończeniu.

ConfigurationBinder.Get<T> powiązywa i zwraca określony typ. ConfigurationBinder.Get<T> Może być wygodniejszy niż ConfigurationBinder.Bind użycie . Poniższy kod pokazuje, jak używać klasy ConfigurationBinder.Get<T> PositionOptions z klasą :

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}");
    }
}

W poprzednim kodzie domyślnie są odczytywane zmiany w pliku konfiguracji JSON po jej zakończeniu.

Alternatywnym podejściem w przypadku korzystania ze wzorca ***** opcji _ jest powiązanie sekcji i dodanie jej do kontenera usługi Position wstrzykiwania zależności. W poniższym kodzie do kontenera usługi dodano wartość i powiązano PositionOptions <xref:Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions.Configure_> z konfiguracją:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

Korzystając z poprzedniego kodu, następujący kod odczytuje opcje pozycji:

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}");
    }
}

W poprzednim kodzie zmiany w pliku konfiguracji JSON po jej zakończeniu nie są odczytywane. Aby odczytać zmiany po zakończeniu pracy aplikacji, użyj funkcji IOptionsSnapshot.

Przy użyciu konfiguracji domyślnej wartości appsettings.json i appsettings. Environment Pliki json są włączone z reloadOnChange: true. Zmiany wprowadzone w appsettings.json i appsettings. Environment Plik JSON po uruchamianiu aplikacji jest odczytywany przez dostawcę konfiguracji JSON.

Zobacz dostawca konfiguracji JSON w tym dokumencie, aby uzyskać informacje na temat dodawania dodatkowych plików konfiguracji JSON.

Łączenie kolekcji usług

Rozważmy ConfigureServices następującą metodę, która rejestruje usługi i konfiguruje opcje:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

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

    services.AddRazorPages();
}

Powiązane grupy rejestracji można przenieść do metody rozszerzenia w celu zarejestrowania usług. Na przykład usługi konfiguracji są dodawane do następującej klasy:

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

Pozostałe usługi są rejestrowane w podobnej klasie. Następująca ConfigureServices metoda używa nowych metod rozszerzenia do rejestrowania usług:

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

Uwaga: Każda services.Add{GROUP_NAME} metoda rozszerzenia dodaje i potencjalnie konfiguruje usługi. Na przykład program AddControllersWithViews dodaje wymagane kontrolery MVC usług z widokami i AddRazorPages dodaje usługi wymagane przez Razor usługę Pages. Zalecamy, aby aplikacje postępowały zgodnie z konwencją nazewnictwa tworzenia metod rozszerzeń w przestrzeni Microsoft.Extensions.DependencyInjection nazw . Tworzenie metod rozszerzeń w przestrzeni Microsoft.Extensions.DependencyInjection nazw :

Zabezpieczenia i wpisy tajne użytkowników

Wytyczne dotyczące danych konfiguracji:

  • Nigdy nie przechowuj haseł ani innych poufnych danych w kodzie dostawcy konfiguracji ani w plikach konfiguracji w postaci zwykłego tekstu. Narzędzie Secret Manager może służyć do przechowywania wpisów tajnych w programie.
  • Nie używaj wpisów tajnych produkcji w środowiskach deweloperskich ani testowych.
  • Określ wpisy tajne poza projektem, aby nie można było ich przypadkowo zatwierdzona w repozytorium kodu źródłowego.

Domyślnie źródłokonfiguracji wpisów tajnych użytkownika jest rejestrowane po źródłach konfiguracji JSON. W związku z tym klucze wpisów tajnych użytkowników mają pierwszeństwo przed kluczami w ustawieniach i appsettings.json appsettings. Environment .json.

Aby uzyskać więcej informacji na temat przechowywania haseł lub innych poufnych danych:

Azure Key Vault bezpiecznie przechowuje wpisy tajne aplikacji dla ASP.NET Core aplikacji. Aby uzyskać więcej informacji, zobacz Azure Key Vault konfiguracji w programie ASP.NET Core.

Zmienne środowiskowe

Przy użyciu konfiguracji domyślnej ładuje konfigurację z par klucz-wartość zmiennej środowiskowej EnvironmentVariablesConfigurationProvider po odczytaniu wartości , appsettings.json appsettings. Environment .json i wpisy tajne użytkownika. W związku z tym wartości kluczy odczytane ze środowiska zastępują wartości odczytane z appsettings.json metody , appsettings. Environment .json i wpisy tajne użytkownika.

Separator : nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. __, podwójny podkreślenie, to:

  • Obsługiwane przez wszystkie platformy. Na przykład separator : nie jest obsługiwany przez powłokę Bash, ale __ jest.
  • Automatycznie zastępowane przez :

Następujące set polecenia:

  • Ustaw klucze środowiska i wartości poprzedniego przykładu na Windows.
  • Przetestuj ustawienia podczas korzystania z przykładowego pobierania. Polecenie dotnet run musi zostać uruchomione w katalogu projektu.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

Powyższe ustawienia środowiska:

  • Są ustawiane tylko w procesach uruchomionych z okna poleceń, w których zostały ustawione.
  • Nie będą odczytywane przez przeglądarki uruchomione z Visual Studio.

Następujące polecenia setx mogą służyć do ustawienia kluczy i wartości środowiska na Windows. W set przeciwieństwie do , ustawienia są setx utrwalane. /M Ustawia zmienną w środowisku systemowym. Jeśli przełącznik /M nie jest używany, ustawiana jest zmienna środowiskowa użytkownika.

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

Aby sprawdzić, czy poprzednie polecenia zastępują appsettings.json ustawienia i appsettings. Environment .json:

  • W Visual Studio: Zamknij i uruchom ponownie Visual Studio.
  • Za pomocą interfejsu wiersza polecenia: uruchom nowe okno polecenia i wprowadź dotnet run polecenie .

Wywołaj AddEnvironmentVariables z ciągiem , aby określić prefiks dla zmiennych środowiskowych:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Powyższy kod ma następujące działanie:

Prefiks jest wyłączany podczas odczytywania par klucz-wartość konfiguracji.

Następujące polecenia testuje niestandardowy prefiks:

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

Domyślna konfiguracja ładuje zmienne środowiskowe i argumenty wiersza polecenia poprzedzone prefiksami DOTNET_ i ASPNETCORE_ . Prefiksy i są używane przez ASP.NET Core konfiguracji hosta i DOTNET_ ASPNETCORE_ aplikacji,ale nie w przypadku konfiguracji użytkownika. Aby uzyskać więcej informacji na temat konfiguracji hosta i aplikacji, zobacz .NET Generic Host.

Na Azure App Servicewybierz pozycję Nowe ustawienie aplikacji na stronie Ustawienia > Konfiguracji aplikacji. Azure App Service aplikacji są:

  • Szyfrowane w spoczynku i przesyłane za pośrednictwem szyfrowanego kanału.
  • Widoczne jako zmienne środowiskowe.

Aby uzyskać więcej informacji, zobacz Azure Apps: Override app configuration using the Azure Portal (Azure Apps: przesłanianie konfiguracji aplikacji przy użyciu witryny Azure Portal).

Aby uzyskać informacje na temat parametrów połączenia bazy danych platformy Azure, zobacz Prefiksy parametrów połączenia.

Nazewnictwo zmiennych środowiskowych

Nazwy zmiennych środowiskowych odzwierciedlają strukturę appsettings.json pliku. Każdy element w hierarchii jest oddzielony podwójnym podkreśleniem (preferowanym) lub dwukropkiem. Gdy struktura elementów zawiera tablicę, indeks tablicy powinien być traktowany jako dodatkowa nazwa elementu w tej ścieżce. Rozważmy następujący appsettings.json plik i jego równoważne wartości reprezentowane jako zmienne środowiskowe.

appsettings.json

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

zmienne środowiskowe

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

Zmienne środowiskowe ustawione w wygenerowanym launchSettings.json

Zmienne środowiskowe ustawione w launchSettings.json zastępują zmienne ustawione w środowisku systemowym. Na przykład szablony ASP.NET Core generują plik launchSettings.json, który ustawia konfigurację punktu końcowego na:

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

Skonfigurowanie applicationUrl ustawia zmienną ASPNETCORE_URLS środowiskową i zastępuje wartości ustawione w środowisku.

Zmienne środowiskowe ucieczki w systemie Linux

W systemie Linux należy zmienić wartość zmiennych środowiskowych adresu URL, aby systemd można było je ująć. Korzystanie z narzędzia systemu systemd-escape Linux, które daje http:--localhost:5001

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

Wyświetlanie zmiennych środowiskowych

Poniższy kod wyświetla zmienne środowiskowe i wartości podczas uruchamiania aplikacji, co może być przydatne podczas debugowania ustawień środowiska:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var config = host.Services.GetRequiredService<IConfiguration>();

    foreach (var c in config.AsEnumerable())
    {
        Console.WriteLine(c.Key + " = " + c.Value);
    }
    host.Run();
}

Wiersz polecenia

Przy użyciu konfiguracji domyślnej ładuje konfigurację z wiersza polecenia CommandLineConfigurationProvider pary klucz-wartość argumentu po następujących źródłach konfiguracji:

  • appsettings.json i appsettings Environment . pliki json.
  • Wpisy tajne aplikacji w środowisku dewelopera.
  • Zmienne środowiskowe.

Domyślnie wartościkonfiguracji ustawione w wierszu polecenia zastępują wartości konfiguracji ustawione dla wszystkich innych dostawców konfiguracji.

Argumenty wiersza polecenia

Następujące polecenie ustawia klucze i wartości przy użyciu = polecenia :

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

Następujące polecenie ustawia klucze i wartości przy użyciu / polecenia :

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

Następujące polecenie ustawia klucze i wartości przy użyciu -- polecenia :

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

Wartość klucza:

  • Musi być zgodna z wartością , lub klucz musi = mieć prefiks lub , gdy wartość następuje po -- / spacji.
  • Nie jest wymagane, jeśli = jest używany. Na przykład MySetting=.

W ramach tego samego polecenia nie mieszaj par klucz-wartość argumentu wiersza polecenia, które używają z = parami klucz-wartość, które używają spacji.

Mapowania przełączników

Mapowania przełączników zezwalają na logikę zastępowania nazw kluczy. Podaj słownik zastąpień przełącznika dla AddCommandLine metody .

Gdy słownik mapowań przełącznika jest używany, słownik jest sprawdzany pod kątem klucza zgodnego z kluczem dostarczonym przez argument wiersza polecenia. Jeśli klucz wiersza polecenia zostanie znaleziony w słowniku, wartość słownika zostanie przekazana z powrotem, aby ustawić parę klucz-wartość w konfiguracji aplikacji. Mapowanie przełącznika jest wymagane dla dowolnego klucza wiersza polecenia poprzedzonego pojedynczym łącznikiem ( - ).

Reguły kluczy słownika mapowania przełączników:

  • Przełączniki muszą zaczynać się od - lub -- .
  • Słownik mapowań przełącznika nie może zawierać zduplikowanych kluczy.

Aby użyć słownika mapowań przełącznika, przekaż go do wywołania AddCommandLine :

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Poniższy kod przedstawia wartości kluczy dla zastąpionych kluczy:

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"]}'");
    }
}

Następujące polecenie działa w celu przetestowania zastępowania klucza:

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

W przypadku aplikacji, które używają mapowań przełączników, wywołanie funkcji nie CreateDefaultBuilder powinno przekazywać argumentów. Wywołanie metody nie zawiera zamapowanych przełączników i nie ma możliwości przekazania słownika CreateDefaultBuilder AddCommandLine mapowania przełączników do metody CreateDefaultBuilder . Rozwiązanie nie służy do przekazania argumentów, ale zamiast tego, aby umożliwić metodzie metody przetwarzanie zarówno argumentów, jak i CreateDefaultBuilder ConfigurationBuilder AddCommandLine słownika mapowania przełączników.

Ustawianie argumentów środowiska i wiersza polecenia za pomocą Visual Studio

Na poniższej ilustracji przedstawiono ustawianie środowiska i argumentów wiersza polecenia za pomocą Visual Studio:

Karta Debugowanie programu VS

W Visual Studio 2019 r. w wersji 16.10 (wersja zapoznawcza 4) i nowszych ustawienia argumentów środowiska i wiersza polecenia są wykonywane z interfejsu użytkownika profilów uruchamiania:

interfejs użytkownika uruchamiania profilów

Hierarchiczne dane konfiguracji

Interfejs API konfiguracji odczytuje dane konfiguracji hierarchicznej, spłaszczając dane hierarchiczne przy użyciu ogranicznika w kluczach konfiguracji.

Przykładowy plik do pobrania zawiera następujący appsettings.json plik:

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

Poniższy kod z przykładowego pobierania zawiera kilka ustawień konfiguracji:

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}");
    }
}

Preferowanym sposobem odczytywania danych konfiguracji hierarchicznej jest użycie wzorca opcji. Aby uzyskać więcej informacji, zobacz Wiązanie danych konfiguracji hierarchicznej w tym dokumencie.

GetSection Metody i są dostępne do izolowania sekcji i poszczególnych GetChildren części sekcji w danych konfiguracji. Te metody zostały opisane w dalszej części sekcji GetSection, Get Wyliczy i Istnieje.

Klucze i wartości konfiguracji

Klucze konfiguracji:

  • Bez uwzględniania liter. Na przykład i ConnectionString są traktowane jako klucze connectionstring równoważne.
  • Jeśli klucz i wartość są ustawione w więcej niż jednego dostawcę konfiguracji, używana jest wartość od ostatniego dodanego dostawcy. Aby uzyskać więcej informacji, zobacz Konfiguracja domyślna.
  • Klucze hierarchiczne
    • W interfejsie API konfiguracji separator dwukropka ( : ) działa na wszystkich platformach.
    • W zmiennych środowiskowych separator dwukropka może nie działać na wszystkich platformach. Podwójny podkreślenia, __ , jest obsługiwany przez wszystkie platformy i jest automatycznie konwertowany na dwukropek : .
    • W Azure Key Vault jako separatora są -- używać klucze hierarchiczne. Dostawca Azure Key Vault automatycznie zastępuje plik , gdy wpisy tajne są ładowane do konfiguracji -- : aplikacji.
  • Obiekt ConfigurationBinder obsługuje powiązanie tablic z obiektami przy użyciu indeksów tablic w kluczach konfiguracji. Powiązanie tablicy jest opisane w sekcji Wiązanie tablicy z klasą.

Wartości konfiguracji:

  • Są ciągami.
  • Wartości null nie mogą być przechowywane w konfiguracji ani powiązane z obiektami.

Dostawcy konfiguracji

W poniższej tabeli przedstawiono dostawców konfiguracji dostępnych dla ASP.NET Core aplikacji.

Dostawca Zapewnia konfigurację z
Azure Key Vault konfiguracji Azure Key Vault
Dostawca konfiguracji aplikacji platformy Azure Azure App Configuration
Dostawca konfiguracji wiersza polecenia Parametry wiersza polecenia
Niestandardowy dostawca konfiguracji Źródło niestandardowe
Dostawca konfiguracji zmiennych środowiskowych Zmienne środowiskowe
Dostawca konfiguracji plików Pliki INI, JSON i XML
Dostawca konfiguracji klucza na plik Pliki katalogu
Dostawca konfiguracji pamięci Kolekcje w pamięci
Wpisy tajne użytkowników Plik w katalogu profilu użytkownika

Źródła konfiguracji są odczytywane w kolejności, w których określono ich dostawców konfiguracji. Zamów dostawców konfiguracji w kodzie, aby dopasować je do priorytetów bazowych źródeł konfiguracji wymaganych przez aplikację.

Typowa sekwencja dostawców konfiguracji to:

  1. appsettings.json
  2. appsettings Environment . json
  3. Wpisy tajne użytkowników
  4. Zmienne środowiskowe korzystające z dostawcy konfiguracji zmiennych środowiskowych.
  5. Argumenty wiersza polecenia używające dostawcy konfiguracji wiersza polecenia.

Powszechną praktyką jest dodanie dostawcy konfiguracji wiersza polecenia jako ostatniego z serii dostawców, aby umożliwić argumentom wiersza polecenia przesłonięcie konfiguracji ustawionej przez innych dostawców.

Poprzednia sekwencja dostawców jest używana w konfiguracji domyślnej.

Prefiksy parametrów połączenia

Interfejs API konfiguracji ma specjalne reguły przetwarzania dla czterech zmiennych środowiskowych parametrów połączenia. Te parametry połączenia są związane z konfigurowaniem ciągów połączeń platformy Azure dla środowiska aplikacji. Zmienne środowiskowe z prefiksami wyświetlanymi w tabeli są ładowane do aplikacji z konfiguracją domyślną lub gdy do elementu nie pokazano prefiksu AddEnvironmentVariables .

Prefiks parametrów połączenia Dostawca
CUSTOMCONNSTR_ Dostawca niestandardowy
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server

Gdy zmienna środowiskowa zostanie odnaleziona i załadowana do konfiguracji z dowolnym z czterech prefiksów pokazanych w tabeli:

  • Klucz konfiguracji jest tworzony przez usunięcie prefiksu zmiennej środowiskowej i dodanie sekcji klucza konfiguracji ( ConnectionStrings ).
  • Tworzona jest nowa para klucz-wartość konfiguracji, która reprezentuje dostawcę połączenia z bazą danych (z wyjątkiem , który CUSTOMCONNSTR_ nie ma podanego dostawcy).
Klucz zmiennej środowiskowej Przekonwertowany klucz konfiguracji Wpis konfiguracji dostawcy
CUSTOMCONNSTR_{KEY} ConnectionStrings:{KEY} Wpis konfiguracji nie został utworzony.
MYSQLCONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName :
Wartość: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName :
Wartość: System.Data.SqlClient
SQLCONNSTR_{KEY} ConnectionStrings:{KEY} Klucz: ConnectionStrings:{KEY}_ProviderName :
Wartość: System.Data.SqlClient

Dostawca konfiguracji plików

FileConfigurationProvider to klasa podstawowa do ładowania konfiguracji z systemu plików. Następujący dostawcy konfiguracji pochodzą z FileConfigurationProvider programu :

Dostawca konfiguracji INI

Konfiguracja IniConfigurationProvider ładuje z pary klucz-wartość pliku INI w czasie wykonywania.

Poniższy kod powoduje wyczyszczenie wszystkich dostawców konfiguracji i dodanie kilku dostawców konfiguracji:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

W poprzednim kodzie ustawienia w pliku MyIniConfig.ini MyIniConfig Environment . Pliki ini są zastępowany przez ustawienia w:

Przykładowy plik do pobrania zawiera następującyMyIniConfig.ini plik:

MyKey="MyIniConfig.ini Value"

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

[Logging:LogLevel]
Default=Information
Microsoft=Warning

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Dostawca konfiguracji JSON

Konfiguracja JsonConfigurationProvider jest ładowana z par klucz-wartość pliku JSON.

Przeciążenia mogą określać:

  • Czy plik jest opcjonalny.
  • Określa, czy konfiguracja zostanie ponownie załadowana, jeśli plik się zmieni.

Spójrzmy na poniższy kod:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Powyższy kod ma następujące działanie:

  • Konfiguruje dostawcę konfiguracji JSON do ładowania pliku MyConfig.json przy użyciu następujących opcji:
    • optional: true: plik jest opcjonalny.
    • reloadOnChange: true : plik jest ponownie ładowany po zapisaniu zmian.
  • Odczytuje domyślnych dostawców konfiguracji przed plikiem MyConfig.json. Ustawienia w ustawieniu przesłaniania pliku MyConfig.json w domyślnych dostawcach konfiguracji, w tym dostawcy konfiguracji zmiennych środowiskowych i dostawcy konfiguracji wiersza polecenia.

Zazwyczaj nie chcesz, aby niestandardowy plik JSON przesłaniał wartości ustawione w dostawcy konfiguracji zmiennych środowiskowych i dostawcy konfiguracji wiersza polecenia.

Poniższy kod powoduje wyczyszczenie wszystkich dostawców konfiguracji i dodanie kilku dostawców konfiguracji:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                                     optional: true, reloadOnChange: true);

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

W poprzednim kodzie ustawienia w plikach MyConfig.json i MyConfig Environment . Pliki JSON:

Przykładowy plik do pobrania zawiera następujący plik MyConfig.json:

{
    "Position": {
        "Title": "Mój tytuł konfiguracji",
        "Name": "My Config Smith"
    },
    "MyKey": "MyConfig.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Dostawca konfiguracji XML

Konfiguracja XmlConfigurationProvider ładuje z pary klucz-wartość pliku XML w czasie wykonywania.

Poniższy kod powoduje wyczyszczenie wszystkich dostawców konfiguracji i dodanie kilku dostawców konfiguracji:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

W poprzednim kodzie ustawienia w plikach MyXMLFile.xml MyXMLFile Environment . Pliki xml są zastępowany przez ustawienia w:

Przykładowy plik do pobrania zawiera następującyMyXMLFile.xml plik:

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

Poniższy kod z przykładowego pobierania zawiera kilka poprzednich ustawień konfiguracji:

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}");
    }
}

Powtarzanie elementów, które używają tej samej nazwy elementu, działa, jeśli name atrybut jest używany do odróżnienia elementów:

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

Poniższy kod odczytuje poprzedni plik konfiguracji i wyświetla klucze i wartości:

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"
                       );
    }
}

Atrybuty mogą służyć do dostarczania wartości:

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

Poprzedni plik konfiguracji ładuje następujące klucze za pomocą programu value :

  • key:attribute
  • section:key:attribute

Dostawca konfiguracji klucza dla pliku

Element KeyPerFileConfigurationProvider używa plików katalogu jako par klucz-wartość konfiguracji. Klucz to nazwa pliku. Wartość zawiera zawartość pliku. Dostawca konfiguracji klucz-plik jest używany w scenariuszach hostingu platformy Docker.

Aby aktywować konfigurację klucza dla pliku, AddKeyPerFile wywołaj metodę rozszerzenia w wystąpieniu klasy ConfigurationBuilder . Element directoryPath do plików musi być ścieżką bezwzględną.

Przeciążenia umożliwiają określanie:

  • Delegat Action<KeyPerFileConfigurationSource> konfigurujący źródło.
  • Czy katalog jest opcjonalny i czy ścieżka do katalogu.

Podwójny znak podkreślenia ( __ ) jest używany jako ogranicznik klucza konfiguracji w nazwach plików. Na przykład nazwa pliku tworzy Logging__LogLevel__System klucz konfiguracji Logging:LogLevel:System .

Wywołaj ConfigureAppConfiguration podczas budowania hosta, aby określić konfigurację aplikacji:

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

Dostawca konfiguracji pamięci

Element MemoryConfigurationProvider używa kolekcji w pamięci jako par klucz-wartość konfiguracji.

Poniższy kod dodaje kolekcję pamięci do systemu konfiguracji:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Poniższy kod z przykładowego pobierania wyświetla poprzednie ustawienia konfiguracji:

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}");
    }
}

W poprzednim kodzie jest config.AddInMemoryCollection(Dict) dodawany po domyślnych dostawcach konfiguracji. Aby uzyskać przykład zamawiania dostawców konfiguracji, zobacz JSON configuration provider (Dostawca konfiguracji JSON).

Zobacz Wiązanie tablicy, aby uzyskać inny przykład przy użyciu funkcji MemoryConfigurationProvider .

Kestrel konfiguracja punktu końcowego

Kestrel Konfiguracja określonego punktu końcowego zastępuje wszystkie konfiguracje punktu końcowego między serwerami. Konfiguracje punktów końcowych między serwerami obejmują:

Rozważmy następujący appsettings.json plik używany w ASP.NET Core internetowej:

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

Gdy poprzedni wyróżniony znacznik jest używany w aplikacji internetowej usługi ASP.NET Core, a aplikacja jest uruchomiona w wierszu polecenia z następującą konfiguracją punktu końcowego między serwerami:

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

Kestrel wiąże się z punktem końcowym skonfigurowanym specjalnie dla Kestrel parametru w appsettings.json pliku ( ), a nie https://localhost:9999 https://localhost:7777 .

Rozważ konkretny Kestrel punkt końcowy skonfigurowany jako zmienna środowiskowa:

set Kestrel__Endpoints__Https__Url=https://localhost:8888

W poprzedniej zmiennej środowiskowej Https jest nazwą określonego punktu Kestrel końcowego. Powyższy plik appsettings.json definiuje również określony punkt końcowy o nazwie Kestrel Https . Domyślnie zmienneśrodowiskowe używające dostawcy konfiguracji Zmienne środowiskowe są odczytywane po ustawieniach appsettings. Environment W związku z tym dla punktu końcowego jest używana wcześniejsza zmienna Https środowiskowa .json.

GetValue

ConfigurationBinder.GetValue<T> wyodrębnia pojedynczą wartość z konfiguracji przy użyciu określonego klucza i konwertuje ją na określony typ:

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}");
    }
}

W poprzednim kodzie, jeśli nie NumberKey zostanie odnaleziony w konfiguracji, używana jest wartość 99 domyślna .

GetSection, Get Należy i istnieje

W poniższych przykładach rozważ następujący plik MySubsection.json:

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

Poniższy kod dodaje plik MySubsection.json do dostawców konfiguracji:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MySubsection.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Getsection

IConfiguration.GetSection zwraca podsekcję konfiguracji z określonym kluczem podsekcji.

Poniższy kod zwraca wartości dla section1 :

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"]}'");
    }
}

Poniższy kod zwraca wartości dla section2:subsection0 :

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"]}'");
    }
}

GetSectionnigdy nie zwraca . null Jeśli nie znaleziono pasującej sekcji, IConfigurationSection zwracana jest pusta sekcja.

W GetSection przypadku zwracania pasującej sekcji Value wartość nie jest wypełniana. A Key i Path są zwracane, gdy sekcja istnieje.

Get Wymusz i istnieje

Poniższy kod wywołuje IConfiguration.Get Należywyjąć i zwraca wartości section2:subsection0 dla :

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

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

    public ContentResult OnGet()
    {
        string s = null;
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new System.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);
    }
}

Powyższy kod wywołuje plik ConfigurationExtensions.Exists, aby sprawdzić, czy sekcja istnieje:

Wiązanie tablicy

ConfigurationBinder.Bind obsługuje powiązanie tablic z obiektami przy użyciu indeksów tablic w kluczach konfiguracji. Każdy format tablicy, który uwidacznia segment klucza liczbowego, może być w stanie powiązań tablicy z tablicą klas POCO.

Rozważmy plik MyArray.json z przykładowego pliku do pobrania:

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

Poniższy kod dodaje plik MyArray.json do dostawców konfiguracji:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyArray.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Poniższy kod odczytuje konfigurację i wyświetla wartości:

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>();
        string s = null;

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

        return Content(s);
    }
}

Powyższy kod zwraca następujące dane wyjściowe:

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

W poprzednich danych wyjściowych indeks 3 ma wartość value40 , odpowiadającą w "4": "value40", myArray.json. Indeksy tablicy powiązanej są ciągłe i nie są powiązane z indeksem kluczy konfiguracji. Konfigurator nie może powiązać wartości null ani tworzyć wpisów null w powiązanych obiektach

Poniższy kod ładuje array:entries konfigurację za pomocą AddInMemoryCollection metody rozszerzenia:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Poniższy kod odczytuje konfigurację w pliku arrayDict Dictionary i wyświetla wartości:

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>();
        string s = null;

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

        return Content(s);
    }
}

Powyższy kod zwraca następujące dane wyjściowe:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value4
Index: 4  Value: value5

Indeks # 3 w powiązanym obiekcie przechowuje dane konfiguracji klucza konfiguracji i array:4 jego wartość value4 . Gdy dane konfiguracji zawierające tablicę są powiązane, indeksy tablic w kluczach konfiguracji są używane do iterowania danych konfiguracji podczas tworzenia obiektu. Wartości null nie można zachować w danych konfiguracji, a wpis o wartości null nie jest tworzony w obiekcie powiązanym, gdy tablica w kluczach konfiguracji pomija co najmniej jeden indeks.

Brakujący element konfiguracji dla indeksu 3 może zostać dostarczony przed powiązaniem z wystąpieniem przez dowolnego dostawcę konfiguracji, który odczytuje parę # ArrayExample # klucz/wartość indeksu 3. Rozważmy następujący plik Value3.json z przykładowego pobrania:

{
  "array:entries:3": "value3"
}

Poniższy kod zawiera konfigurację pliku Value3.json i arrayDict Dictionary pliku :

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile("Value3.json",
                                    optional: false, reloadOnChange: false);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

Poniższy kod odczytuje poprzednią konfigurację i wyświetla wartości:

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>();
        string s = null;

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

        return Content(s);
    }
}

Powyższy kod zwraca następujące dane wyjściowe:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value3
Index: 4  Value: value4
Index: 5  Value: value5

Niestandardowi dostawcy konfiguracji nie są wymagani do zaimplementowania powiązania tablicy.

Niestandardowy dostawca konfiguracji

Przykładowa aplikacja pokazuje, jak utworzyć podstawowego dostawcę konfiguracji, który odczytuje pary klucz-wartość konfiguracji z bazy danych przy użyciu programu Entity Framework (EF).

Dostawca ma następujące cechy:

  • Baza danych EF w pamięci jest używana w celach demonstracyjnych. Aby użyć bazy danych, która wymaga parametrów połączenia, należy zaimplementować pomocniczą bazę danych w celu ConfigurationBuilder dostarczania parametrów połączenia od innego dostawcy konfiguracji.
  • Dostawca odczytuje tabelę bazy danych do konfiguracji podczas uruchamiania. Dostawca nie odpytuje bazy danych według klucza.
  • Ponowne ładowanie przy zmianie nie jest zaimplementowane, dlatego aktualizacja bazy danych po jej uruchamianiu nie ma wpływu na konfigurację aplikacji.

EFConfigurationValueZdefiniuj jednostkę do przechowywania wartości konfiguracji w bazie danych.

Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Dodaj element EFConfigurationContext do przechowywania skonfigurowanych wartości i uzyskiwania do nich dostępu.

EFConfigurationProvider/EFConfigurationContext.cs:

// using Microsoft.EntityFrameworkCore;

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

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Utwórz klasę, która implementuje IConfigurationSource klasę .

EFConfigurationProvider/EFConfigurationSource.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

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

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

Utwórz niestandardowego dostawcę konfiguracji, dziedzicząc z ConfigurationProvider . Dostawca konfiguracji inicjuje bazę danych, gdy jest pusta. Ponieważ w kluczach konfiguracji nie jest roz rozsyłana litera, słownik używany do inicjowania bazy danych jest tworzony za pomocą porównującego bez uwzględniania liter(StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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))
        {
            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
        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." }
            };

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

        dbContext.SaveChanges();

        return configValues;
    }
}

Metoda AddEFConfiguration rozszerzenia umożliwia dodanie źródła konfiguracji do pliku ConfigurationBuilder .

Extensions/EntityFrameworkExtensions.cs:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

Poniższy kod pokazuje, jak używać niestandardowego kodu EFConfigurationProvider w programie Program.cs:

// using Microsoft.EntityFrameworkCore;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddEFConfiguration(
                options => options.UseInMemoryDatabase("InMemoryDb"));
        })

Konfiguracja dostępu przy uruchamianiu

Poniższy kod wyświetla dane konfiguracji w Startup metodach:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Aby uzyskać przykład uzyskiwania dostępu do konfiguracji przy użyciu wygodnych metod uruchamiania, zobacz App startup: Convenience methods (Uruchamianie aplikacji: metody wygodne).

Konfiguracja dostępu na Razor stronach

Poniższy kod wyświetla dane konfiguracji na Razor stronie:

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

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

W poniższym kodzie do kontenera usługi dodano wartość i powiązano MyOptions Configure z konfiguracją:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));

    services.AddRazorPages();
}

W następujących znacznikach użyto dyrektywy @inject Razor , aby rozwiązać i wyświetlić wartości opcji:

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


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

Konfiguracja dostępu w pliku widoku MVC

Poniższy kod wyświetla dane konfiguracji w widoku MVC:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

Konfigurowanie opcji za pomocą delegata

Opcje skonfigurowane w delegacie zastępują wartości ustawione w dostawcach konfiguracji.

Konfigurowanie opcji za pomocą delegata jest demonstrowane jako przykład 2 w przykładowej aplikacji.

W poniższym kodzie usługa IConfigureOptions<TOptions> jest dodawana do kontenera usługi. Używa delegata do konfigurowania wartości MyOptions dla :

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "Value configured in delegate";
        myOptions.Option2 = 500;
    });

    services.AddRazorPages();
}

Poniższy kod wyświetla wartości opcji:

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}");
    }
}

W poprzednim przykładzie wartości i są określone w , a następnie zastąpione przez Option1 Option2 appsettings.json skonfigurowanego delegata.

Konfiguracja hosta a aplikacji

Przed skonfigurowaniem i rozpoczęciem konfigurowania aplikacji host jest konfigurowany i uruchomiony. Host jest odpowiedzialny za uruchamianie aplikacji i zarządzanie okresem istnienia. Zarówno aplikacja, jak i host są konfigurowane przy użyciu dostawców konfiguracji opisanych w tym temacie. Pary klucz-wartość konfiguracji hosta są również uwzględniane w konfiguracji aplikacji. Aby uzyskać więcej informacji na temat sposobu korzystania z dostawców konfiguracji podczas budów hosta i wpływu źródeł konfiguracji na konfigurację hosta, zobacz Platforma ASP.NET Core — podstawy .

Domyślna konfiguracja hosta

Aby uzyskać szczegółowe informacje na temat konfiguracji domyślnej podczas korzystania z hosta sieci Web,zobacz ASP.NET Core w wersji 2.2 tego tematu.

  • Konfiguracja hosta jest zapewniana z:
    • Zmienne środowiskowe poprzedzone DOTNET_ prefiksem (na przykład ) przy użyciu dostawcy konfiguracji DOTNET_ENVIRONMENT zmiennych środowiskowych. Prefiks ( DOTNET_ ) jest usuwania podczas ładowania par klucz-wartość konfiguracji.
    • Argumenty wiersza polecenia przy użyciu dostawcy konfiguracji wiersza polecenia.
  • Zostanie ustanowiona domyślna konfiguracja hosta sieci Web ( ConfigureWebHostDefaults ):
    • Kestrel jest używany jako serwer internetowy i konfigurowany przy użyciu dostawców konfiguracji aplikacji.
    • Dodaj oprogramowanie pośredniczące filtrowania hosta.
    • Dodaj oprogramowanie pośredniczące Przekazane nagłówki, jeśli ASPNETCORE_FORWARDEDHEADERS_ENABLED zmienna środowiskowa jest ustawiona na true .
    • Włączanie integracji usług IIS.

Inna konfiguracja

Ten temat dotyczy tylko konfiguracji aplikacji. Inne aspekty uruchamiania i hostowania aplikacji ASP.NET Core są konfigurowane przy użyciu plików konfiguracji, które nie zostały uwzględnione w tym temacie:

Zmienne środowiskowe ustawione w launchSettings.json zastępują zmienne ustawione w środowisku systemowym.

Aby uzyskać więcej informacji na temat migrowania konfiguracji aplikacji ze starszych wersji ASP.NET, zobacz Migrowanie z ASP.NET do ASP.NET Core .

Dodawanie konfiguracji z zestawu zewnętrznego

Implementacja umożliwia dodawanie ulepszeń do aplikacji podczas uruchamiania z zestawu zewnętrznego IHostingStartup poza klasą Startup aplikacji. Aby uzyskać więcej informacji, zobacz Używanie hostowania zestawów startowych w programie ASP.NET Core.

Dodatkowe zasoby