Конфигурация в .NET CoreConfiguration in ASP.NET Core

Автор Люк Латэм (Luke Latham)By Luke Latham

Конфигурация приложения в ASP.NET Core основана на парах "ключ — значение", установленных поставщиками конфигурации.App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. Поставщики конфигурации получают данные конфигурации в парах "ключ — значение" из различных источников:Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Хранилище ключей Azure;Azure Key Vault
  • Конфигурация приложений AzureAzure App Configuration
  • аргументов командной строки;Command-line arguments
  • а также пользовательские поставщики (устанавливаемые или создаваемые).Custom providers (installed or created)
  • Справочные файлыDirectory files
  • Переменные средыEnvironment variables
  • объектов .NET в памяти;In-memory .NET objects
  • файлов параметров;Settings files

Пакеты конфигурации для распространенных вариантов провайдеров конфигурации (Microsoft.Extensions.Configuration) включаются платформой неявным образом.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included implicitly by the framework.

Пакеты конфигурации для распространенных вариантов провайдеров конфигурации (Microsoft.Extensions.Configuration) включаются в метапакет Microsoft.AspNetCore.App.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.

В приведенных ниже и представленных в образце приложения примерах кода используется пространство имен Microsoft.Extensions.Configuration:Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

Шаблон параметров является расширением конфигурации основных понятий, описанных в этом разделе.The options pattern is an extension of the configuration concepts described in this topic. Параметры используют классы для представления групп связанных настроек.Options use classes to represent groups of related settings. Дополнительные сведения можно найти по адресу: Шаблон параметров в ASP.NET Core.For more information, see Шаблон параметров в ASP.NET Core.

Просмотреть или скачать образец кода (как скачивать)View or download sample code (how to download)

Конфигурация узла и приложенияHost versus app configuration

Перед настройкой и запуском приложения настройте и запустите узел.Before the app is configured and started, a host is configured and launched. Узел отвечает за запуск приложения и управление временем существования.The host is responsible for app startup and lifetime management. Как приложение, так и узел настраиваются с использованием поставщиков конфигурации, описанных в этом разделе.Both the app and the host are configured using the configuration providers described in this topic. Пары "ключ — значение" конфигурации узлов также включаются в конфигурацию приложения.Host configuration key-value pairs are also included in the app's configuration. Дополнительные сведения о том, как используются поставщики конфигурации при создании узла и как влияют источники конфигурации на узел, см. в разделе Основы ASP.NET Core.For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see Основы ASP.NET Core.

Конфигурация по умолчаниюDefault configuration

Веб-приложения на основе шаблонов dotnet new ASP.NET Core вызывают CreateDefaultBuilder при создании узла.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder предоставляет конфигурацию по умолчанию для приложения в следующем порядке:CreateDefaultBuilder provides default configuration for the app in the following order:

Приведенные ниже сведения относятся к приложениям, использующим универсальный узел.The following applies to apps using the Generic Host. Подробные сведения о конфигурации по умолчанию при использовании веб-узла см. в разделе о версии ASP.NET Core 2.2 в этой статье.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

Веб-приложения на основе шаблонов dotnet new ASP.NET Core вызывают CreateDefaultBuilder при создании узла.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder предоставляет конфигурацию по умолчанию для приложения в следующем порядке:CreateDefaultBuilder provides default configuration for the app in the following order:

Приведенные ниже сведения относятся к приложениям, использующим веб-узел.The following applies to apps using the Web Host. Подробные сведения о конфигурации по умолчанию при использовании универсального узла см. в последней версии этой статьи.For details on the default configuration when using the Generic Host, see the latest version of this topic.

БезопасностьSecurity

Применяйте описанные ниже методики для защиты конфиденциальных данных конфигурации.Adopt the following practices to secure sensitive configuration data:

  • Никогда не храните пароли или другие конфиденциальные данные в коде поставщика конфигурации или в файлах конфигурации обычного текста.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • Не используйте секреты рабочей среды в средах разработки и тестирования.Don't use production secrets in development or test environments.
  • Указывайте секреты вне проекта, чтобы их нельзя было случайно зафиксировать в репозитории с исходным кодом.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

Дополнительные сведения см. в следующих разделах:For more information, see the following topics:

В Azure Key Vault безопасно хранятся секреты приложений ASP.NET Core.Azure Key Vault safely stores app secrets for ASP.NET Core apps. Дополнительные сведения можно найти по адресу: Поставщик конфигурации Azure Key Vault в ASP.NET Core.For more information, see Поставщик конфигурации Azure Key Vault в ASP.NET Core.

Иерархическая модель конфигурацииHierarchical configuration data

API конфигурации способен поддерживать иерархические данные конфигурации, выполняя преобразование в плоскую структуру иерархических данных с использованием разделителя в ключах конфигурации.The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

В следующем файле JSON существуют четыре ключа в структурированной иерархии двух разделов.In the following JSON file, four keys exist in a structured hierarchy of two sections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

При считывании файла в конфигурацию для сохранения исходной иерархической структуры данных источника конфигурации создаются уникальные ключи.When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. Разделы и ключи преобразовываются в плоскую структуру с использованием двоеточия (:) для сохранения исходной структуры.The sections and keys are flattened with the use of a colon (:) to maintain the original structure:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

Методы GetSection и GetChildren доступны для изолирования разделов и дочерних элементов раздела в данных конфигурации.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. Эти методы описаны далее в разделе GetSection, GetChildren и Exists.These methods are described later in GetSection, GetChildren, and Exists.

СоглашенияConventions

Источники и поставщикиSources and providers

При запуске приложения источники конфигурации считываются в порядке, в котором были указаны их поставщики конфигурации.At app startup, configuration sources are read in the order that their configuration providers are specified.

Поставщики конфигурации, которые реализуют обнаружение изменений, имеют возможность перезагрузить конфигурацию при изменении базовых параметров.Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. Так, поставщик файла конфигурации (подробнее о нем далее в этой статье) и поставщик конфигурации Azure Key Vault реализуют обнаружение изменений.For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

Объект IConfiguration доступен в контейнере внедрения зависимостей приложения.IConfiguration is available in the app's dependency injection (DI) container. IConfiguration можно внедрить в PageModel Razor Pages, чтобы получить конфигурацию для класса:IConfiguration can be injected into a Razor Pages PageModel to obtain configuration for the class:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    // The _config local variable is used to obtain configuration 
    // throughout the class.
}

Поставщики конфигурации не могут использовать контейнер DI, так как он недоступен при настройке узла.Configuration providers can't utilize DI, as it's not available when they're set up by the host.

КлавишиKeys

В ключах конфигурации приняты следующие соглашения.Configuration keys adopt the following conventions:

  • В ключах не учитывается регистр символов.Keys are case-insensitive. Например ConnectionString и connectionstring обрабатываются как эквивалентные ключи.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Если значение для одного и того же ключа установлено одним и тем же или разными поставщиками конфигурации, последним значением, установленным на ключе, является используемое значение.If a value for the same key is set by the same or different configuration providers, the last value set on the key is the value used.
  • Иерархические ключиHierarchical keys
    • При взаимодействии с API конфигурации разделитель-двоеточие (:) поддерживается на всех платформах.Within the Configuration API, a colon separator (:) works on all platforms.
    • В переменных среды разделитель-двоеточие может не работать на всех платформах.In environment variables, a colon separator may not work on all platforms. Двойной знак подчеркивания (__) поддерживается на всех платформах и автоматически преобразовывается в двоеточие.A double underscore (__) is supported by all platforms and is automatically converted into a colon.
    • В хранилище ключей Azure иерархические ключи используют -- (два дефиса) в качестве разделителя.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. Чтобы заменить дефисы двоеточием, при загрузке секретов в конфигурацию приложения необходимо указать код.You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • ConfigurationBinder поддерживает массивы привязки к объектам с помощью массива индексов в ключах конфигурации.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. Привязка массива описана в разделе Привязка массива к классу.Array binding is described in the Bind an array to a class section.

ЗначенияValues

В значениях конфигурации учитываются следующие соглашения.Configuration values adopt the following conventions:

  • Значения являются строками.Values are strings.
  • Значение NULL не может храниться в конфигурации или быть привязанным к объектам.Null values can't be stored in configuration or bound to objects.

ПоставщикиProviders

В следующей таблице показаны поставщики конфигурации, доступные для приложений ASP.NET Core.The following table shows the configuration providers available to ASP.NET Core apps.

ПоставщикProvider Предоставляет конфигурацию из …Provides configuration from…
Поставщик конфигурации хранилища ключей Azure (раздел Безопасность)Azure Key Vault Configuration Provider (Security topics) Хранилище ключей Azure;Azure Key Vault
Поставщик конфигурации приложений Azure (документация Azure)Azure App Configuration Provider (Azure documentation) Конфигурация приложений AzureAzure App Configuration
Поставщик конфигурации командной строкиCommand-line Configuration Provider Параметры командной строкиCommand-line parameters
Поставщик пользовательской конфигурацииCustom configuration provider Источник пользователяCustom source
Поставщик конфигурации переменных средыEnvironment Variables Configuration Provider Переменные средыEnvironment variables
Поставщик пользовательской конфигурацииFile Configuration Provider Файлы (INI, JSON, XML)Files (INI, JSON, XML)
Поставщик конфигурации ключа для каждого файлаKey-per-file Configuration Provider Справочные файлыDirectory files
Поставщик конфигурации памятиMemory Configuration Provider Коллекции оперативной памятиIn-memory collections
Секреты пользователей (Менеджер секретов) (раздел Безопасность)User secrets (Secret Manager) (Security topics) Файл в каталоге профиля пользователяFile in the user profile directory

Источники конфигурации считываются в том порядке, в котором при запуске указываются их поставщики конфигурации.Configuration sources are read in the order that their configuration providers are specified at startup. Поставщики конфигурации в этом разделе описаны в алфавитном порядке, а не в необходимом вам порядке в коде.The configuration providers described in this topic are described in alphabetical order, not in the order that your code may arrange them. Порядок поставщиков конфигурации в коде соответствует приоритетам ваших основных источников конфигурации.Order configuration providers in your code to suit your priorities for the underlying configuration sources.

Типичная последовательность поставщиков конфигурации.A typical sequence of configuration providers is:

  1. Файлы (appsettings.json, appsettings.{Environment}.json, где {Environment} — это текущая среда размещения приложения)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure Key Vault;Azure Key Vault
  3. Секреты пользователя (Менеджер секретов) (только в среде разработки)User secrets (Secret Manager) (Development environment only)
  4. Переменные средыEnvironment variables
  5. аргументов командной строки;Command-line arguments

Общепринятой практикой является размещение поставщика конфигурации командной строки последним в ряду поставщиков, чтобы аргументы командной строки могли переопределять конфигурацию, установленную другими поставщиками.A common practice is to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

Предыдущая последовательность поставщиков используется при инициализации нового построителя узла с помощью CreateDefaultBuilder.The preceding sequence of providers is used when you initialize a new host builder with CreateDefaultBuilder. Дополнительные сведения см. в разделе Конфигурация по умолчанию.For more information, see the Default configuration section.

Настройка построителя узла с помощью ConfigureHostConfigurationConfigure the host builder with ConfigureHostConfiguration

Чтобы настроить построитель узла, вызовите ConfigureHostConfiguration и укажите конфигурацию.To configure the host builder, call ConfigureHostConfiguration and supply the configuration. ConfigureHostConfiguration используется для инициализации IHostEnvironment для дальнейшего использования в процессе сборки.ConfigureHostConfiguration is used to initialize the IHostEnvironment for use later in the build process. Метод ConfigureHostConfiguration может вызываться несколько раз с накоплением результатов.ConfigureHostConfiguration can be called multiple times with additive results.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureHostConfiguration((hostingContext, config) =>
        {
            var dict = new Dictionary<string, string>
            {
                {"MemoryCollectionKey1", "value1"},
                {"MemoryCollectionKey2", "value2"}
            };

            config.AddInMemoryCollection(dict);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Настройка построителя узла с помощью UseConfigurationConfigure the host builder with UseConfiguration

Чтобы настроить построитель узла, вызовите UseConfiguration в построителе узла с конфигурацией.To configure the host builder, call UseConfiguration on the host builder with the configuration.

public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
    var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

    var config = new ConfigurationBuilder()
        .AddInMemoryCollection(dict)
        .Build();

    return WebHost.CreateDefaultBuilder(args)
        .UseConfiguration(config)
        .UseStartup<Startup>();
}

ConfigureAppConfigurationConfigureAppConfiguration

Вызовите ConfigureAppConfiguration при сборке узла, чтобы указать поставщики конфигурации приложения в дополнение к тем, которые автоматически добавлены CreateDefaultBuilder.Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Переопределение предыдущей конфигурации с помощью аргументов командной строкиOverride previous configuration with command-line arguments

Чтобы предоставить конфигурацию приложения, которую можно переопределить с помощью аргументов командной строки, вызовите метод AddCommandLine последним:To provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

Использование конфигурации во время запуска приложенияConsume configuration during app startup

Конфигурация, предоставленная приложению в ConfigureAppConfiguration, доступна во время запуска приложения, включая Startup.ConfigureServices.Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. Дополнительные сведения см. в разделе Доступ к конфигурации во время запуска.For more information, see the Access configuration during startup section.

Поставщик конфигурации командной строкиCommand-line Configuration Provider

CommandLineConfigurationProvider загружает конфигурацию из пары "ключ — значение" аргумента командной строки в среде выполнения.The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

Чтобы активировать конфигурацию командной строки, вызывается метод расширения AddCommandLine для экземпляра ConfigurationBuilder.To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

AddCommandLine вызывается автоматически при вызове CreateDefaultBuilder(string []).AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. Дополнительные сведения см. в разделе Конфигурация по умолчанию.For more information, see the Default configuration section.

CreateDefaultBuilder также загружает следующее:CreateDefaultBuilder also loads:

CreateDefaultBuilder добавляет последним поставщика конфигурации командной строки.CreateDefaultBuilder adds the Command-line Configuration Provider last. Аргументы командной строки передаются в набор конфигурации переопределения среды выполнения, установленной другими поставщиками.Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder действует, когда создается узел.CreateDefaultBuilder acts when the host is constructed. Поэтому конфигурация командной строки, активированная с помощью CreateDefaultBuilder, может повлиять на настройку узла.Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

Для приложений на основе шаблонов ASP.NET Core метод AddCommandLine уже был вызван методом CreateDefaultBuilder.For apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. Чтобы добавить дополнительные поставщики конфигурации и обеспечить возможность переопределения конфигурации от этих поставщиков с помощью аргументов командной строки, вызовите дополнительные поставщики приложения в ConfigureAppConfiguration и вызовите AddCommandLine в последнюю очередь.To add additional configuration providers and maintain the ability to override configuration from those providers with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

ПримерExample

Пример приложения использует преимущества статически удобного метода CreateDefaultBuilder для создания узла, который включает вызов AddCommandLine.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. Откройте командную строку в каталоге проекта.Open a command prompt in the project's directory.
  2. Поставьте аргумент командной строки в команду dotnet run: dotnet run CommandLineKey=CommandLineValue.Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. После запуска приложения откройте браузер в приложении по адресу http://localhost:5000.After the app is running, open a browser to the app at http://localhost:5000.
  4. Обратите внимание, что вывод содержит пару "ключ — значение" для аргумента командной строки конфигурации, предоставленного для dotnet run.Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

АргументыArguments

Значение должно соответствовать знаку равенства (=), или ключ должен иметь префикс (-- или /), когда значение следует за пробелом.The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. Значение не требуется, если используется знак равенства (например, CommandLineKey=).The value isn't required if an equals sign is used (for example, CommandLineKey=).

Префикс ключаKey prefix ПримерExample
Без префиксаNo prefix CommandLineKey1=value1
Два дефиса (--)Two dashes (--) --CommandLineKey2=value2, --CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
Прямая косая черта (/)Forward slash (/) /CommandLineKey3=value3, /CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

В рамках одной и той же команды не смешивайте пары "ключ — значение" аргумента командной строки, которые используют знак равенства, с парами "ключ — значение", которые используют пробел.Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-value pairs that use a space.

Примеры команд.Example commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

Сопоставления переключенийSwitch mappings

Сопоставление параметров позволяет указать логику замены имен ключей.Switch mappings allow key name replacement logic. Когда вручную создается конфигурация с помощью ConfigurationBuilder, методу AddCommandLine можно предоставить словарь сопоставления переключений.When you manually build configuration with a ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.

В словаре сопоставлений переключений выполняется поиск ключа, который совпадает с ключом, предоставляемым аргументом командной строки.When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. Если ключ в командной строке находится в словаре, значение словаря (замена ключа) передается обратно, чтобы установить пару "ключ — значение" в конфигурацию приложения.If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the key-value pair into the app's configuration. Сопоставление переключений необходимо для любого ключа командной строки с префиксом из одного дефиса (-).A switch mapping is required for any command-line key prefixed with a single dash (-).

Правила ключей из словаря сопоставления переключений:Switch mappings dictionary key rules:

  • Переключения должны начинаться с дефиса (-) или двойного дефиса (--).Switches must start with a dash (-) or double-dash (--).
  • Словарь сопоставлений переключений не должен содержать повторяющиеся ключи.The switch mappings dictionary must not contain duplicate keys.

Создайте словарь сопоставления переключений.Create a switch mappings dictionary. В следующем примере создаются два сопоставления переключений:In the following example, two switch mappings are created:

public static readonly Dictionary<string, string> _switchMappings = 
    new Dictionary<string, string>
    {
        { "-CLKey1", "CommandLineKey1" },
        { "-CLKey2", "CommandLineKey2" }
    };

При сборке узла вызовите AddCommandLine со словарем сопоставлений переключений:When the host is built, call AddCommandLine with the switch mappings dictionary:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddCommandLine(args, _switchMappings);
})

Для приложений, использующих сопоставления переключений, в вызове CreateDefaultBuilder аргументы передаваться не должны.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. Вызов команды AddCommandLine метода CreateDefaultBuilder не включает сопоставленные переключения, и нет возможности передать словарь сопоставления переключений в CreateDefaultBuilder.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Чтобы решить эту проблему, нужно не передавать аргументы команде CreateDefaultBuilder, а позволить методу AddCommandLine метода ConfigurationBuilder обрабатывать как аргументы, так и словарь сопоставления параметров.The solution isn't to pass the arguments to CreateDefaultBuilder but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch mapping dictionary.

Созданный словарь сопоставлений переключений содержит данные, показанные в следующей таблице.After the switch mappings dictionary is created, it contains the data shown in the following table.

КлючKey ЗначениеValue
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

Если ключи сопоставления переключений используются при запуске приложения, конфигурация принимает значение конфигурации в ключе, предоставленном в словаре.If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the key supplied by the dictionary:

dotnet run -CLKey1=value1 -CLKey2=value2

После выполнения предыдущей команды конфигурация содержит значения, показанные в следующей таблице.After running the preceding command, configuration contains the values shown in the following table.

КлючKey ЗначениеValue
CommandLineKey1 value1
CommandLineKey2 value2

Поставщик конфигурации переменных средыEnvironment Variables Configuration Provider

EnvironmentVariablesConfigurationProvider загружает конфигурацию из пары "ключ — значение" переменной среды выполнения.The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

Чтобы активировать конфигурацию переменных среды, вызовите метод расширения AddEnvironmentVariables в экземпляре ConfigurationBuilder.To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

При работе с иерархическими ключами в переменных среды разделитель-двоеточие (:) может работать не на всех платформах (например, в Bash).When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). Двойной знак подчеркивания (__) поддерживается на всех платформах и автоматически заменяется двоеточием.A double underscore (__) is supported by all platforms and is automatically replaced by a colon.

Служба приложений Azure позволяет задать переменные среды на портале Azure, который может переопределить конфигурацию приложения, используя поставщик конфигурации переменных среды.Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Дополнительные сведения см. в руководстве по переопределению конфигурации приложения Azure с помощью портала Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

AddEnvironmentVariables используется для загрузки переменных среды, имеющих префикс DOTNET_, для конфигурации узла при инициализации нового построителя узла с универсальным узлом и вызове CreateDefaultBuilder.AddEnvironmentVariables is used to load environment variables prefixed with DOTNET_ for host configuration when a new host builder is initialized with the Generic Host and CreateDefaultBuilder is called. Дополнительные сведения см. в разделе Конфигурация по умолчанию.For more information, see the Default configuration section.

AddEnvironmentVariables используется для загрузки переменных среды, имеющих префикс ASPNETCORE_, для конфигурации узла при инициализации нового построителя узла с веб-узлом и вызове CreateDefaultBuilder.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is called. Дополнительные сведения см. в разделе Конфигурация по умолчанию.For more information, see the Default configuration section.

CreateDefaultBuilder также загружает следующее:CreateDefaultBuilder also loads:

  • конфигурация приложения на основе переменных среды без префикса путем вызова AddEnvironmentVariables без префикса;App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • дополнительную конфигурацию из файлов appsettings.json и appsettings.{Environment}.json;Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • секреты пользователя (Менеджер секретов) в среде разработки.User secrets (Secret Manager) in the Development environment.
  • аргументы командной строки.Command-line arguments.

Поставщик конфигурации переменных среды вызывается после выполнения настройки с помощью секретов пользователя и файлов appsettings.The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. Вызов поставщика в этой позиции разрешает чтение переменных среды выполнения, чтобы переопределить конфигурацию, заданную секретом пользователя и файлом appsettings.Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

Если вам нужно добавить конфигурацию приложения из дополнительных переменных среды, вызовите дополнительные поставщики приложения в ConfigureAppConfiguration, а затем вызовите AddEnvironmentVariables с префиксом.If you need to provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call additional providers here as needed.
    // Call AddEnvironmentVariables last if you need to allow
    // environment variables to override values from other 
    // providers.
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})
}

ПримерExample

Пример приложения использует преимущества статически удобного метода CreateDefaultBuilder для создания узла, который включает вызов AddEnvironmentVariables.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. Выполните пример приложения.Run the sample app. Откройте в приложении браузер с адресом http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Обратите внимание, что выходные данные содержат пару "ключ — значение" для переменной среды ENVIRONMENT.Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. Значение отражает среду, в которой выполняется приложение, обычно при локальном запуске это Development.The value reflects the environment in which the app is running, typically Development when running locally.

Чтобы список переменных среды, отображаемый приложением, был коротким, приложение фильтрует переменные среды.To keep the list of environment variables rendered by the app short, the app filters environment variables. См. пример файла Pages/Index.cshtml.cs приложения.See the sample app's Pages/Index.cshtml.cs file.

Если хотите просмотреть все переменные среды, доступные для приложения, измените значение FilteredConfiguration в Pages/Index.cshtml.cs на следующее:If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

ПрефиксыPrefixes

Переменные среды, которые загружаются в конфигурацию приложения, фильтруются при добавлении префикса к методу AddEnvironmentVariables.Environment variables loaded into the app's configuration are filtered when you supply a prefix to the AddEnvironmentVariables method. Например, чтобы отфильтровать переменные среды по префиксу CUSTOM_, введите префикс поставщику конфигурации:For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables("CUSTOM_")
    .Build();

Префикс отделяется при создании пары конфигурации "ключ — значение".The prefix is stripped off when the configuration key-value pairs are created.

При создании построителя узла конфигурация узла предоставляется переменными среды.When the host builder is created, host configuration is provided by environment variables. Дополнительные сведения о префиксе, используемом для этих переменных среды, см. в разделе Конфигурация по умолчанию.For more information on the prefix used for these environment variables, see the Default configuration section.

Префиксы строк подключенияConnection string prefixes

API конфигурации имеет специальные правила обработки для четырех строк подключения переменных среды, связанных с настройкой строк подключения Azure для среды приложения.The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. Если префикс не указан в AddEnvironmentVariables, переменные среды с префиксами, указанными в таблице, загружаются в приложение.Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

Префикс строки подключенияConnection string prefix ПоставщикProvider
CUSTOMCONNSTR_ Поставщик пользователяCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ База данных SQL AzureAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

Когда переменная среды обнаруживается и загружается в конфигурацию с одним из четырех префиксов, приведенных в таблице, происходит следующее.When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • Ключ конфигурации создается путем удаления префикса переменных среды и добавления ключа раздела конфигурации (ConnectionStrings).The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • Создается новая пара "ключ — значение" конфигурации, которая представляет поставщика подключения базы данных (за исключением CUSTOMCONNSTR_, который не имеет указанного поставщика).A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
Ключ переменной средыEnvironment variable key Преобразованный ключ конфигурацииConverted configuration key Запись конфигурации поставщикаProvider configuration entry
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Запись конфигурации не создана.Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Ключ: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Значение: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Ключ: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Значение: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Ключ: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Значение: System.Data.SqlClientValue: System.Data.SqlClient

Поставщик пользовательской конфигурацииFile Configuration Provider

FileConfigurationProvider является базовым классом для загрузки конфигурации из файловой системы.FileConfigurationProvider is the base class for loading configuration from the file system. Следующие поставщики конфигурации предназначены для определенных типов файлов:The following configuration providers are dedicated to specific file types:

Поставщик конфигурации INIINI Configuration Provider

IniConfigurationProvider загружает конфигурацию из пары "ключ — значение" INI-файла во время выполнения.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

Чтобы активировать конфигурацию INI-файла, вызовите метод расширения AddIniFile в экземпляре ConfigurationBuilder.To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

Двоеточие можно использовать как разделитель раздела в конфигурации файла INI.The colon can be used to as a section delimiter in INI file configuration.

Перегрузки позволяют указать следующее.Overloads permit specifying:

  • Файл является обязательным или нет.Whether the file is optional.
  • Будет ли перезагружена конфигурация, если файл изменится.Whether the configuration is reloaded if the file changes.
  • IFileProvider используется для доступа к файлу.The IFileProvider used to access the file.

Чтобы указать конфигурацию приложения, при сборке веб-узла вызовите ConfigureAppConfiguration.Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.SetBasePath(Directory.GetCurrentDirectory());
    config.AddIniFile(
        "config.ini", optional: true, reloadOnChange: true);
})

Базовый путь задается с помощью SetBasePath.The base path is set with SetBasePath.

Общий пример конфигурации INI-файла.A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

Предыдущий файл конфигурации загружает следующие ключи с помощью value.The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:subsection:keysection1:subsection:key
  • section2:subsection0:keysection2:subsection0:key
  • section2:subsection1:keysection2:subsection1:key

Поставщик конфигурации JSONJSON Configuration Provider

JsonConfigurationProvider загружает конфигурацию из пары "ключ — значение" JSON-файла в среде выполнения.The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

Чтобы активировать конфигурацию JSON-файла, вызовите метод расширения AddJsonFile в экземпляре ConfigurationBuilder.To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

Перегрузки позволяют указать следующее.Overloads permit specifying:

  • Файл является обязательным или нет.Whether the file is optional.
  • Будет ли перезагружена конфигурация, если файл изменится.Whether the configuration is reloaded if the file changes.
  • IFileProvider используется для доступа к файлу.The IFileProvider used to access the file.

AddJsonFile автоматически вызывается дважды при инициализации нового построителя узла с CreateDefaultBuilder.AddJsonFile is automatically called twice when you initialize a new host builder with CreateDefaultBuilder. Метод вызывается для загрузки конфигурации из:The method is called to load configuration from:

  • appsettings.json – первым читается этот файл.appsettings.json – This file is read first. Версия файла среды может переопределить значения, предоставленные appsettings.json.The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json — версия среды файла загружается на основе IHostingEnvironment.EnvironmentName.appsettings.{Environment}.json – The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

Дополнительные сведения см. в разделе Конфигурация по умолчанию.For more information, see the Default configuration section.

CreateDefaultBuilder также загружает следующее:CreateDefaultBuilder also loads:

Сначала устанавливается поставщик конфигурации JSON-файлов.The JSON Configuration Provider is established first. Таким образом, секреты пользователя, переменные среды и аргументы командной строки переопределят конфигурацию, заданную файлами appsettings.Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

Вызовите ConfigureAppConfiguration при сборке узла, чтобы указать конфигурацию приложения для файлов, отличных от appsettings.json и appsettings.{Environment}.json.Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.SetBasePath(Directory.GetCurrentDirectory());
    config.AddJsonFile(
        "config.json", optional: true, reloadOnChange: true);
})

Базовый путь задается с помощью SetBasePath.The base path is set with SetBasePath.

ПримерExample

Пример приложения использует преимущества статически удобного метода CreateDefaultBuilder для создания узла, который включает два вызова AddJsonFile.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile. Конфигурация загружена из appsettings.json и appsettings.{Environment}.json.Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. Выполните пример приложения.Run the sample app. Откройте в приложении браузер с адресом http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Обратите внимание, что выходные данные содержат пары "ключ — значение" для конфигурации, представленной в таблице в зависимости от среды.Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. Ключи конфигурации ведения журнала используют двоеточие (:) как иерархический разделитель.Logging configuration keys use the colon (:) as a hierarchical separator.
КлючKey Значение разработкиDevelopment Value Рабочее значениеProduction Value
Logging:LogLevel:SystemLogging:LogLevel:System СведенияInformation СведенияInformation
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft СведенияInformation СведенияInformation
Logging:LogLevel:DefaultLogging:LogLevel:Default ОтладкаDebug ErrorError
AllowedHostsAllowedHosts * *

Поставщик конфигурации XMLXML Configuration Provider

XmlConfigurationProvider загружает конфигурацию из пары "ключ — значение" XML-файла в среде выполнения.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

Чтобы активировать конфигурацию XML-файла, вызовите метод расширения AddXmlFile в экземпляре ConfigurationBuilder.To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

Перегрузки позволяют указать следующее.Overloads permit specifying:

  • Файл является обязательным или нет.Whether the file is optional.
  • Будет ли перезагружена конфигурация, если файл изменится.Whether the configuration is reloaded if the file changes.
  • IFileProvider используется для доступа к файлу.The IFileProvider used to access the file.

Корневой узел файла конфигурации не учитывается при создании пар "ключ — значение" конфигурации.The root node of the configuration file is ignored when the configuration key-value pairs are created. Не указывайте в файле Document Type Definition (определение типа документа, DTD) или пространство имен.Don't specify a Document Type Definition (DTD) or namespace in the file.

Чтобы указать конфигурацию приложения, при сборке веб-узла вызовите ConfigureAppConfiguration.Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.SetBasePath(Directory.GetCurrentDirectory());
    config.AddXmlFile(
        "config.xml", optional: true, reloadOnChange: true);
})

Базовый путь задается с помощью SetBasePath.The base path is set with SetBasePath.

XML-файлы конфигурации могут использовать имена отдельных элементов для повторяющихся разделов.XML configuration files can use distinct element names for repeating sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section0>
    <key0>value</key0>
    <key1>value</key1>
  </section0>
  <section1>
    <key0>value</key0>
    <key1>value</key1>
  </section1>
</configuration>

Предыдущий файл конфигурации загружает следующие ключи с помощью value.The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

Повторяющиеся элементы, использующие то же имя элемента, работают, если атрибут name используется для различения элементов.Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

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

Предыдущий файл конфигурации загружает следующие ключи с помощью value.The previous configuration file loads the following keys with value:

  • section:section0:key:key0section:section0:key:key0
  • section:section0:key:key1section:section0:key:key1
  • section:section1:key:key0section:section1:key:key0
  • section:section1:key:key1section:section1:key:key1

Атрибуты можно использовать для предоставления значений.Attributes can be used to supply values:

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

Предыдущий файл конфигурации загружает следующие ключи с помощью value.The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

Поставщик конфигурации ключа для каждого файлаKey-per-file Configuration Provider

KeyPerFileConfigurationProvider использует файлы каталога как пары "ключ — значение" конфигурации.The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. Ключ является именем файла.The key is the file name. Значение содержит содержимое файла.The value contains the file's contents. Поставщик конфигурации ключа для каждого файла используется в сценариях размещения Docker.The Key-per-file Configuration Provider is used in Docker hosting scenarios.

Чтобы активировать конфигурацию ключа для каждого файла, вызовите метод расширения AddKeyPerFile в экземпляре ConfigurationBuilder.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. Значение параметра directoryPath должно быть абсолютным путем к файлам.The directoryPath to the files must be an absolute path.

Перегрузки позволяют указать следующее.Overloads permit specifying:

  • Action<KeyPerFileConfigurationSource> — делегат, который настраивает источник.An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • Обязательно ли указывать каталог и путь к каталогу.Whether the directory is optional and the path to the directory.

Двойное подчеркивание (__) используется в качестве разделителя ключа конфигурации в именах файлов.The double-underscore (__) is used as a configuration key delimiter in file names. Например, в имени файла Logging__LogLevel__System создается ключ конфигурации Logging:LogLevel:System.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

Чтобы указать конфигурацию приложения, при сборке веб-узла вызовите ConfigureAppConfiguration.Call ConfigureAppConfiguration when building the host to specify the app's configuration:

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

Базовый путь задается с помощью SetBasePath.The base path is set with SetBasePath.

Поставщик конфигурации памятиMemory Configuration Provider

MemoryConfigurationProvider использует коллекцию памяти в качестве пар "ключ — значение" конфигурации.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

Чтобы активировать конфигурацию коллекции в памяти, вызовите метод расширения AddInMemoryCollection в экземпляре ConfigurationBuilder.To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

Поставщик конфигурации может инициализироваться значением IEnumerable<KeyValuePair<String,String>>.The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

Чтобы указать конфигурацию приложения, при сборке узла вызовите ConfigureAppConfiguration.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

В следующем примере создается словарь конфигурации:In the following example, a configuration dictionary is created:

public static readonly Dictionary<string, string> _dict = 
    new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

Словарь используется с вызовом AddInMemoryCollection для предоставления конфигурации:The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddInMemoryCollection(_dict);
})

GetValueGetValue

ConfigurationBinder.GetValue<T> извлекает значение из конфигурации с указанным ключом и преобразует его в указанный тип.ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the specified type. Если ключ не найден, перегрузка позволяет предоставлять значение по умолчанию.An overload permits you to provide a default value if the key isn't found.

В следующем примере происходит следующее:The following example:

  • Из конфигурации извлекается строковое значение с ключом NumberKey.Extracts the string value from configuration with the key NumberKey. Если NumberKey отсутствует в ключах конфигурации, используется значение по умолчанию 99.If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • Значение получает тип int.Types the value as an int.
  • Значение сохраняется в свойстве NumberConfig для использования на странице.Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

    public void OnGet()
    {
        NumberConfig = _config.GetValue<int>("NumberKey", 99);
    }
}

GetSection, GetChildren и ExistsGetSection, GetChildren, and Exists

В следующих примерах рассмотрим файл JSON.For the examples that follow, consider the following JSON file. Четыре ключа находятся в двух разделах, один из которых содержит пару из подразделов.Four keys are found across two sections, one of which includes a pair of subsections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  },
  "section2": {
    "subsection0" : {
      "key0": "value",
      "key1": "value"
    },
    "subsection1" : {
      "key0": "value",
      "key1": "value"
    }
  }
}

Когда файл считывается в конфигурацию, для сохранения значений конфигурации создаются следующие уникальные иерархические ключи.When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration values:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1
  • section2:subsection0:key0section2:subsection0:key0
  • section2:subsection0:key1section2:subsection0:key1
  • section2:subsection1:key0section2:subsection1:key0
  • section2:subsection1:key1section2:subsection1:key1

GetSectionGetSection

IConfiguration.GetSection извлекает подраздел конфигурации с указанным ключом подраздела.IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.

Чтобы вернуть IConfigurationSection, содержащий только пары "ключ — значение" в section1, вызовите GetSection и укажите имя раздела.To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

var configSection = _config.GetSection("section1");

configSection не содержит значение, только ключ и путь.The configSection doesn't have a value, only a key and a path.

Аналогично, чтобы получить значения для ключей в section2:subsection0, вызовите GetSection и укажите путь к разделу.Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

var configSection = _config.GetSection("section2:subsection0");

Значение GetSection никогда не возвращает значение null.GetSection never returns null. Если соответствующий раздел не найден, возвращается пустой параметр IConfigurationSection.If a matching section isn't found, an empty IConfigurationSection is returned.

Когда GetSection возвращает соответствующий раздел, Value не заполняется.When GetSection returns a matching section, Value isn't populated. Key и Path возвращаются, если раздел существует.A Key and Path are returned when the section exists.

GetChildrenGetChildren

Вызов IConfiguration.GetChildren в section2 получает значение IEnumerable<IConfigurationSection>, которое включает:A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

  • subsection0
  • subsection1
var configSection = _config.GetSection("section2");

var children = configSection.GetChildren();

ExistsExists

Используйте ConfigurationExtensions.Exists, чтобы определить, существует ли раздел конфигурации.Use ConfigurationExtensions.Exists to determine if a configuration section exists:

var sectionExists = _config.GetSection("section2:subsection2").Exists();

Учитывая данные примера, sectionExists является false, потому что в данных конфигурации нет section2:subsection2.Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

Привязка к классуBind to a class

Конфигурация может быть привязана к классам, которые представляют группы связанных параметров, используя шаблон вариантов.Configuration can be bound to classes that represent groups of related settings using the options pattern. Дополнительные сведения можно найти по адресу: Шаблон параметров в ASP.NET Core.For more information, see Шаблон параметров в ASP.NET Core.

Значения конфигурации возвращаются как строки, но вызов Bind позволяет построить объекты POCO.Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.

Пример приложения содержит модель Starship (Models/Starship.cs):The sample app contains a Starship model (Models/Starship.cs):

public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}
public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}

Раздел starship файла starship.json создает конфигурацию, когда образец приложения использует поставщик конфигурации JSON для загрузки конфигурации.The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

Создаются следующие пары "ключ — значение" конфигурации.The following configuration key-value pairs are created:

КлючKey ЗначениеValue
starship:namestarship:name USS EnterpriseUSS Enterprise
starship:registrystarship:registry NCC-1701NCC-1701
starship:classstarship:class ConstitutionConstitution
starship:lengthstarship:length 304.8304.8
starship:commissionedstarship:commissioned FalseFalse
trademarktrademark Paramount Pictures Corp. https://www.paramount.comParamount Pictures Corp. https://www.paramount.com

Пример приложения вызывает GetSection с помощью ключа starship.The sample app calls GetSection with the starship key. Пары "ключ — значение" starship изолированы.The starship key-value pairs are isolated. Метод Bind вызывается в подразделе при прохождении в экземпляр класса Starship.The Bind method is called on the subsection passing in an instance of the Starship class. После привязки значения экземпляра экземпляру присваивается свойство для преобразования для просмотра.After binding the instance values, the instance is assigned to a property for rendering:

var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;
var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

Привязка к графу объектовBind to an object graph

Bind способна связывать весь граф объекта POCO.Bind is capable of binding an entire POCO object graph.

Образец содержит модель TvShow, в графе объектов которого находятся классы Metadata и Actors (Модели/TvShow.cs).The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}
public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}

В примере приложения есть файл tvshow.xml, содержащий данные конфигурации.The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>

Конфигурация привязана ко всему ​​графу объектов TvShow с помощью метода Bind.Configuration is bound to the entire TvShow object graph with the Bind method. Привязанный экземпляр присваивается свойству для подготовки к просмотру.The bound instance is assigned to a property for rendering:

var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

ConfigurationBinder.Get<T> привязывает и возвращает указанный тип.ConfigurationBinder.Get<T> binds and returns the specified type. Метод Get<T> может быть более удобным, чем использование Bind.Get<T> is more convenient than using Bind. В следующем коде показано, как использовать Get<T> с предыдущим примером, который позволяет привязать связанный экземпляр непосредственно к свойству, используемому для подготовки к просмотру.The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be directly assigned to the property used for rendering:

TvShow = _config.GetSection("tvshow").Get<TvShow>();
TvShow = _config.GetSection("tvshow").Get<TvShow>();

Привязка массива к классуBind an array to a class

Пример приложения демонстрирует концепции, описанные в этом разделе.The sample app demonstrates the concepts explained in this section.

Bind поддерживает массивы привязки к объектам с помощью массива индексов в ключах конфигурации.The Bind supports binding arrays to objects using array indices in configuration keys. Любой формат массива, который предоставляет сегмент числового ключа (:0:, :1:, … :{n}:), способен привязать массив к массиву класса POCO.Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array.

Примечание

Привязка предоставляется соглашением.Binding is provided by convention. Пользовательские поставщики конфигурации не обязаны реализовывать привязку массива.Custom configuration providers aren't required to implement array binding.

Обработка массива в оперативной памятиIn-memory array processing

Рассмотрите ключи и значения конфигурации, приведенные в следующей таблице.Consider the configuration keys and values shown in the following table.

КлючKey ЗначениеValue
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 value1value1
array:entries:2array:entries:2 value2value2
array:entries:4array:entries:4 value4value4
array:entries:5array:entries:5 value5value5

Эти ключи и значения загружаются в пример приложения с помощью поставщика конфигурации памяти.These keys and values are loaded in the sample app using the Memory Configuration Provider:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Массив пропускает значения для индекса #3.The array skips a value for index #3. Связующее свойство конфигурации не способно связывать нулевые значения или создавать нулевые записи в связанных объектах, что становится ясным в тот момент, когда демонстрируется результат привязки этого массива к объекту.The configuration binder isn't capable of binding null values or creating null entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is demonstrated.

В примере приложения класс POCO доступен для хранения привязанных данных конфигурации.In the sample app, a POCO class is available to hold the bound configuration data:

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

Данные конфигурации, связанные с объектом.The configuration data is bound to the object:

var arrayExample = new ArrayExample();
_config.GetSection("array").Bind(arrayExample);

Синтаксис ConfigurationBinder.Get<T> также может использоваться для получения более компактного кода.ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

ArrayExample = _config.GetSection("array").Get<ArrayExample>();
ArrayExample = _config.GetSection("array").Get<ArrayExample>();

Связанный объект, экземпляр ArrayExample, получает данные массива из конфигурации.The bound object, an instance of ArrayExample, receives the array data from configuration.

Индекс ArrayExample.EntriesArrayExample.Entries Index Значение ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

Индекс #3 в связанном объекте содержит данные конфигурации для конфигурационного ключа array:4 и его значения value4.Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. При привязке данных конфигурации, содержащих массив индексов, в ключах конфигурации эти индексы просто используются для выполнения итерации данных конфигурации при создании объекта.When configuration data containing an array is bound, the array indices in the configuration keys are merely used to iterate the configuration data when creating the object. Когда массив ключей конфигурации пропускает один или несколько индексов, в данных конфигурации не может быть сохранено нулевое значение и в связанном объекте не создается нулевая запись.A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.

Отсутствующий элемент конфигурации для индекса #3 может быть предоставлен перед привязкой к экземпляру ArrayExample любым поставщиком конфигурации, который создает правильную пару "ключ — значение" в конфигурации.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that produces the correct key-value pair in configuration. Если в образец включен дополнительный поставщик конфигурации JSON с отсутствующей парой "ключ — значение", то ArrayExample.Entries подойдет полному массиву конфигурации.If the sample included an additional JSON Configuration Provider with the missing key-value pair, the ArrayExample.Entries matches the complete configuration array:

missing_value.json:missing_value.json:

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

В ConfigureAppConfiguration:In ConfigureAppConfiguration:

config.AddJsonFile(
    "missing_value.json", optional: false, reloadOnChange: false);

Пары "ключ — значение", показанные в таблице, загружаются в конфигурации.The key-value pair shown in the table is loaded into configuration.

КлючKey ЗначениеValue
array:entries:3array:entries:3 value3value3

Если экземпляр класса ArrayExample связан после того, как поставщик конфигурации JSON включает запись для индекса #3, то массив ArrayExample.Entries включит значение.If the ArrayExample class instance is bound after the JSON Configuration Provider includes the entry for index #3, the ArrayExample.Entries array includes the value.

Индекс ArrayExample.EntriesArrayExample.Entries Index Значение ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

Обработка массива JSONJSON array processing

Если JSON-файл содержит массив, ключи конфигурации будут созданы для элементов массива с индексом раздела, начиная с нуля.If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. В следующем файле конфигурации subsection — это массив.In the following configuration file, subsection is an array:

{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}
{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}

Поставщик конфигурации JSON считывает данные конфигурации в следующие пары "ключ — значение".The JSON Configuration Provider reads the configuration data into the following key-value pairs:

КлючKey ЗначениеValue
json_array:keyjson_array:key valueAvalueA
json_array:subsection:0json_array:subsection:0 valueBvalueB
json_array:subsection:1json_array:subsection:1 valueCvalueC
json_array:subsection:2json_array:subsection:2 valueDvalueD

В примере приложения для привязки пар "ключ — значение" конфигурации доступен следующий класс POCO.In the sample app, the following POCO class is available to bind the configuration key-value pairs:

public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}
public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

После выполнения привязки JsonArrayExample.Key содержит значение valueA.After binding, JsonArrayExample.Key holds the value valueA. Подраздел значения хранится в свойстве массива POCO Subsection.The subsection values are stored in the POCO array property, Subsection.

Индекс JsonArrayExample.SubsectionJsonArrayExample.Subsection Index Значение JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

Поставщик пользовательской конфигурацииCustom configuration provider

Пример приложения демонстрирует, как создать базовый поставщик конфигурации, который считывает пары "ключ — значение" конфигурации из базы данных, используя Entity Framework (EF).The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

Поставщик имеет следующие характеристики.The provider has the following characteristics:

  • База данных в памяти EF используется для демонстрационных целей.The EF in-memory database is used for demonstration purposes. Чтобы использовать базу данных, для которой требуется строка подключения, выполните вторичный ConfigurationBuilder, чтобы предоставить строку подключения от другого поставщика конфигурации.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • Поставщик считывает таблицу базы данных в конфигурации при запуске.The provider reads a database table into configuration at startup. Поставщик не запрашивает базу данных для каждого ключа.The provider doesn't query the database on a per-key basis.
  • Функция перезагрузки на изменение не реализована, поэтому обновление базы данных после запуска приложения не влияет на конфигурацию приложения.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

Определите сущность EFConfigurationValue для хранения значений конфигурации в базе данных.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

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

Добавьте EFConfigurationContext в хранилище и обратитесь к настроенным значениям.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Создайте класс, реализующий IConfigurationSource.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

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

Создайте пользовательский поставщик конфигурации путем наследования от ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. Поставщик конфигурации инициализирует пустую базу данных.The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    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>
            {
                { "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;
    }
}

Метод расширения AddEFConfiguration позволяет добавить источник конфигурации к ConfigurationBuilder.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

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

В следующем коде показано, как использовать пользовательский EFConfigurationProvider в Program.cs.The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

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

Добавьте EFConfigurationContext в хранилище и обратитесь к настроенным значениям.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

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

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

Создайте класс, реализующий IConfigurationSource.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

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

Создайте пользовательский поставщик конфигурации путем наследования от ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. Поставщик конфигурации инициализирует пустую базу данных.The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    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>
            {
                { "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;
    }
}

Метод расширения AddEFConfiguration позволяет добавить источник конфигурации к ConfigurationBuilder.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

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

В следующем коде показано, как использовать пользовательский EFConfigurationProvider в Program.cs.The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Доступ к конфигурации во время запускаAccess configuration during startup

Внесите значение IConfiguration в конструктор Startup для доступа к значениям конфигурации в Startup.ConfigureServices.Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Чтобы получить доступ к конфигурации в Startup.Configure, либо добавьте значение IConfiguration непосредственно в метод, либо используйте экземпляр из конструктора.To access configuration in Startup.Configure, either inject IConfiguration directly into the method or use the instance from the constructor:

public class Startup
{
    private readonly IConfiguration _config;

    public Startup(IConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var value = _config["key"];
    }

    public void Configure(IApplicationBuilder app, IConfiguration config)
    {
        var value = config["key"];
    }
}

Дополнительные сведения см. в руководстве по доступу к конфигурации с использованием удобных методов.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Настройте доступ на странице Razor Pages или в представлении MVCAccess configuration in a Razor Pages page or MVC view

Для доступа к параметрам конфигурации на странице Razor Pages или в представлении MVC добавьте использование директивы (Справочник по C#: использование директивы) для пространства имен Microsoft.Extensions.Configuration и вставьте IConfiguration на страницу или в представление.To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

На странице Razor PagesIn a Razor Pages page:

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

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

В представлении MVCIn an MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index View</title>
</head>
<body>
    <h1>Access configuration in an MVC view</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

Добавление конфигурации из внешней сборкиAdd configuration from an external assembly

Реализация IHostingStartup позволяет при запуске добавлять в приложение улучшения из внешней сборки вне приложения класса Startup.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Дополнительные сведения можно найти по адресу: Использование начальных сборок размещения в ASP.NET Core.For more information, see Использование начальных сборок размещения в ASP.NET Core.

Дополнительные ресурсыAdditional resources