Файловые провайдеры конфигурации

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

Файловые провайдеры конфигурации

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

1. IniConfigurationProvider – для использования конфигурации в виде INI-файлов;
2. JsonConfigurationProvider и NewtonsoftJsonConfigurationProvider – для использования конфигурации в виде JSON
3. XmlConfigurationProvider – для использования конфигурации в виде XML-файлов.

Для загрузки конфигурации из файлов применяются соответствующие методы расширения IConfigurationBuilder, например, AddJsonFile() для загрузки конфигурации из файла в формате JSON, AddXmlFile() – из XML-файла и так далее. Каждый из методов расширения также имеет перегруженные версии, позволяющие определять дополнительные настройки чтения конфигурационных файлов.

Работа с JSON-файлами конфигурации

Проект ASP.NET Core уже содержит JSON-файлы конфигурации, которые по умолчанию загружаются в приложении и могут использоваться для его настройки – это файлы appsettings.json и appsettings.Development.json

Второй JSON-файл демонстрирует возможность ASP.NET Core загружать определенные настройки приложения в зависимости от среды выполнения. Например, мы можем определить файлы формата appsettings.{EnvironmentName}.json и загружать только те настройки, которые необходимы при выполнении приложения в среде с именем EnvironmentName.  Загрузка конфигурации из этих файлов осуществляется в следующем порядке:

1. Загружаются настройки из файла appsettings.json
2. Загружаются настройки из appsettings.{EnvironmentName}.json,
3. Если оба файла содержат настройку с одинаковым ключом, то значение настройки применяется из последнего загруженного файла, то есть из appsettings. {EnvironmentName}.json.

Преимуществом использования JSON-файлов конфигурации является то, что, используя их мы можем создавать довольно сложные структуры параметров приложения. Например, посмотрим на содержание файла appsettings.json, которое создается по умолчанию в приложении ASP.NET Core Web API

{
   "Logging": {
      "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
    },
"AllowedHosts": "*"
}

Здесь мы можем видеть, что для настроек ведения журнала работы приложения используется отдельная секция (Logging), внутри которой определяется подсекция (LogLevel), которая уже, в свою очередь, содержит конкретные настройки ведения журнала. Мы можем определить в этом файле свои настройки и использовать их в приложении.

Например, создадим новое приложение ASP.NET Core Web API и добавим в файл appsettings.json следующие настройки

{
  "Weather": {
    "Count": 2
  },
    "Logging": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "AllowedHosts": "*"
  }

Теперь перейдем к контроллеру WeatherForecastController и внесем в него следующие изменения:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly IConfiguration _config;

    public WeatherForecastController(IConfiguration configuration)
    {
        _config = configuration;
    }

    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        var count = _config.GetSection("Weather").GetValue<int>("Count", 5);

        return Enumerable.Range(1, count).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

Здесь мы в конструкторе запрашиваем сервис конфигурации — IConfiguration и далее в методе Get() последовательно выполняем следующие действия:

1. Запрашиваем секцию «Weather» из конфигурации
2. Запрашиваем значение «Count» из секции. Если значение не было получено, то по умолчанию возвращается значение 5.

Таким образом, используя файл конфигурации мы регулируем количество элементов, которые вернет контроллер в ответ на наш запрос. Вот как будет выглядеть ответ сервера после запуска программы:

При необходимости мы можем разнести настройки нашего приложения по разным файлам JSON, подгрузив эти файлы при построении приложения. Для того, чтобы загрузить JSON-файл с конфигурацией приложения могут использоваться методы расширения, представленные в таблице

Последняя версия метода AddJsonFile() с использованием делегата позволяет проводить более тонкую настройку источника конфигурации. Например, создадим в папке с проектом новый файл с именем properties.json

и определим в нем следующие настройки:

{
  "Weather": {
    "count": 1
  }
}

Здесь мы задали новое значение для параметра Count. Теперь добавим этот файл в конфигурацию приложения, используя метод AddJsonFile(). Для этого изменим файл Program.cs как показано ниже

builder.Configuration.AddJsonFile((config) =>
{
    config.Path = "properties.json";
    config.Optional = true;
    config.ReloadOnChange = true;
    config.ReloadDelay = 1000;
});


// Add services to the container.

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

В вызове метода AddJsonFile() мы указали путь к файлу (файл должен находиться рядом с exe-файлом приложения), а также указали, что файл является необязательным (так как настройки с точно такими же ключами у нас уже имеются в файле appsettings.json) и необходимо его перезагрузить в случае изменения. При этом, в свойстве ReloadDelay указан размер задержки в миллисекундах перед тем, как файл будет перезагружен.

Теперь запустим приложение и выполним запрос из http-файла. Вы должны увидеть, что применились настройки именно из файла properties.json так как этот файл был загружен последним. 

Подобным образом мы можем добавлять в конфигурацию приложения любое количество JSON-файлов, каждый из которых может содержать различные настройки приложения. Однако, стоит ещё раз обратить внимание на то, каждый очередной JSON-файл добавляется в конец иерархии и перезаписывает значения настроек с одинаковыми ключами.

Теперь можете, не закрывая приложение, изменить значение Count в файле properties.json и через секунду снова выполнить запрос к контроллеру — вы увидите, что контроллер вернет количество элементов массива, учитывая новое значение Count.

Работа с XML- и INI-файлами конфигурации

Что касается работы с XML- и INI-файлами конфигурации в ASP.NET Core, то она реализована в точности также, как и с JSON-файлами – для XML-файлов используется провайдер конфигурации XmlConfigurationProvider и методы расширения AddXmlFile(), а для INI-файлов – провайдер IniConfigurationProvider и методы расширения AddIniFile(). Методы расширения содержат параметры аналогичные тем, которые перечислены в таблице выше. Различие состоит только в формате используемых файлов. Поэтому нет смысла занимать лишнее время на рассмотрение примеров использования XML- и INI-файлов конфигурации в наших приложениях, и мы можем приступить к следующей группе провайдеров конфигурации – нефайловым провайдерам.

Итого

Файловые провайдеры позволяют создавать конфигурации с разветвленной структурой, помещая отдельные настройки в секции и подсекции. Для конфигурации приложения мы можем использовать json-файлы, xml-файлы и ini-файлы. Конфигурацию приложения можно разносить по нескольким файлам. При этом, настройки с одинаковыми именами ключей перезаписываются последним прочитанным значением.