Конфигурация

Основы конфигурации

Данное руководство устарело. Актуальное руководство: Руководство по ASP.NET Core 7

Важную роль в приложении играет конфигурация, которая определяет базовые настройки приложения. Приложение ASP.NET Core может получать конфигурационные настройки из следующих источников:

• Аргументы командной строки

• Переменные среды окружения

• Объекты .NET в памяти

• Файлы (json, xml, ini)

• Azure

• Можно использовать свои кастомные источники и под них создавать провайдеры конфигурации

Конфигурация приложения в ASP.NET Core представляет объект интерфейса IConfiguration:

public interface IConfiguration
{
	string this[string key] { get; set; }
	IEnumerable<IConfigurationSection> GetChildren();
	IChangeToken GetReloadToken();
	IConfigurationSection GetSection(string key);
}

Данный интерфейс содержит следующие компоненты:

• this [string key]: индексатор, через который можно получить по ключу значение параметра конфигурации. Стоит отметить, что и ключ, и значение параметра конфигурации представляет собой объект типа string

• GetChildren(): возвращает набор подсекций текущей секции конфигурации в виде объекта IEnumerable<IConfigurationSection>

• GetReloadToken(): возвращает объект IChangeToken, который применяется для отслеживания изменения конфигурации

• GetSection(string key): возвращает секцию конфигурации, которая соответствует ключу key

Также конфигурация может быть представлена интерфейсом IConfigurationRoot, который наследуется от IConfiguration:

public interface IConfigurationRoot : IConfiguration
{
	IEnumerable<IConfigurationProvider> Providers { get; }
	void Reload();
}

• Свойство Providers возвращает коллекцию применяемых провайдеров конфигурации. Каждый провайдер конфигурации представляет объект IConfigurationProvider

• Метод Reload() перезагружает значения из всех применяемых источников конфигурации

Итак, объект IConfiguration по сути хранит все конфигурационные настройки в виде набора пар "ключ"-"значение".

Для рассмотрения применения конфигурации в ASP.NET Core возьмем проект по типу Empty и изменим стандартный класс Startup следующим образом:

using System.Collections.Generic;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;

namespace ConfigurationApp
{
    public class Startup
    {
        public Startup()
        {
            // строитель конфигурации
            var builder = new ConfigurationBuilder()
                .AddInMemoryCollection(new Dictionary<string, string>
                {
                    {"firstname", "Tom"},
                    {"age", "31"}
                });
            // создаем конфигурацию
            AppConfiguration = builder.Build();

        }
        // свойство, которое будет хранить конфигурацию
        public IConfiguration AppConfiguration { get; set; }

        public void Configure(IApplicationBuilder app)
        {
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync(AppConfiguration["firstname"]);
            });
        }
    }
}

Для создания объекта IConfigurationRoot применяется метод Build() класса ConfigurationBuilder. А с помощью объекта IConfigurationSource для ConfigurationBuilder устанавливается источник конфигурационных настроек.

Как правило, установка конфигурации производится в конструкторе класа Startup. Поэтому для определения конфигурации приложения в класс добавлен конструктор, а для хранения конфигурации определено свойство AppConfiguration. Все настройки конфигурации будут храниться в памяти. Для добавления настроек применяется метод AddInMemoryCollection(), который в качестве параметра принимает словарь. Каждый элемент такого словаря представляет отдельную конфигурационную настройку. Например, {"firstname", "Tom"} - ключ настройки "firstname", а значение - "Tom". Далее этот элемент попадает в конфигурацию приложения:

AppConfiguration = builder.Build();

И затем мы можем использовать конфигурацию, обратившись к нужной настройке по ключу:

string firstName = AppConfiguration["firstname"];

Также мы можем динамически изменять уже имеющиеся настройки или определять новые:

public class Startup
{
    public Startup()
    {
        var builder = new ConfigurationBuilder()
            .AddInMemoryCollection(new Dictionary<string, string>
            {
                {"firstname", "Tom"},
                {"age", "31"}
			});
        AppConfiguration = builder.Build();
    }
    public IConfiguration AppConfiguration { get; set; }

    public void Configure(IApplicationBuilder app)
    {
        AppConfiguration["firstname"] = "alice";
        AppConfiguration["lastname"] = "simpson";
        app.Run(async (context) =>
        {
            await context.Response.WriteAsync($"{AppConfiguration["firstname"]} {AppConfiguration["lastname"]} - {AppConfiguration["age"]}");
        });
    }
}

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

Выше мы явным образом создавали объект IConfiguration, устанавливая для него источник конфигурации и добавляя различные конфигурационные настройки. Однако в принципе нам необязательно создавать свой объект IConfiguration, потому что среда ASP.NET Core уже по умолчанию через механизм Dependency Injection предоставляет нам такой объект, который уже наполнен некоторыми данными. И мы можем получить зависимость IConfiguration таким же образом, как и любой другой сервис, который внедряется через механизм внедрения зависимостей. Но в отличие от других зависимостей, объект IConfiguration мы можем также получить через конструктор класса Startup:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;

namespace ConfigurationApp
{
    public class Startup
    {
        public Startup(IConfiguration config)
        {
            AppConfiguration = config;
        }
        public IConfiguration AppConfiguration { get; set; }

        public void Configure(IApplicationBuilder app)
        {
            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Hello world");
            });
        }
    }
}

Посмотрим, что представляет подключаемая по умолчанию конфигурация:

Через отладку мы можем увидеть, что объект конфигурации содержит данные из четырех источников:

• Файл appsettings.json, который находится в проекте по умолчанию (провайдер JsonConfigurationProvider)

• Файл appsettings.Development.json, который находится в проекте по умолчанию (провайдер JsonConfigurationProvider). Формально приложение подхватывает файл с именем appsettings.{environment}.json, где environment - название стадии, на которой находится проект. Но поскольку по умолчанию для проекта задается стадия "Development" (то есть проект находится в процессе разработки), а в проекте определяется файл appsettings.develoment.json, то собственно он и подхватывается.

• Переменные окружения (провайдер EnvironmentVariablesConfigurationProvider)

• Параметры командной строки (провайдер CommandLineConfigurationProvider)

Также можно увидеть, что также применяется ChainedConfigurationProvider, который фактически соединяет все применяемые провайдеры в одну цепочку.

Как мы видим, объект конфигурации может использовать одновременно сразу несколько источников и провайдеров конфигурации. Все подключемые источники конфигурации считываются в том порядке, в котором они были добавлены. Если разные источники конфигурации содержат одинаковые ключи, то используется значение, последнего добавленного источника конфигурации. Например, в данном случае значения из appsettings.develoment.json перекроют значения с теми же ключами из appsettings.json.

Теперь рассмотрим различные провайдеры и источники конфигурации, которые мы можем использовать.