Конфигурация в ASP.NET Core. Файловые провайдеры конфигурации. Файл JSON, XML и Ini

Содержание

JSON-файлы по умолчанию
- Свои Json-файлы конфигурации
XML-файлы
Ini-файлы
Перегрузки методов AddJsonFile, AddXmlFile и AddIniFile
Итого

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

JSON-файлы по умолчанию

Для работы с файлами json применяется провайдер JsonConfigurationProvider. Для загрузки конфигурации из json-файла применяется метод расширения AddJsonFile(). По умолчанию проекте ASP.NET Core уже содержит json-файлы конфигурации — это файлы appsettings.json и appsettings.Development.json, которые загружаются в приложении и могут использоваться для настройки приложения:

При этом, действия приложения при загрузке конфигурации из этих файлов следующая:

Загружается конфигурация из файла appsettings.json
Загружается конфигурация из файла appsettings.Development.json или appsettings.Production.json

то есть, если одна и таже настройка содержится и в файле appsettings.jsonи в appsettings.Development.json, то применится значение из appsettings.Development.json.

По умолчанию Json-файл appsettings.json выглядит следующим образом:

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

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

Для получения конфигурации из Json-файла мы можем также использовать интерфейс IConfiguration:

app.MapGet("/env", (IConfiguration configuration) => configuration.GetSection("Logging")
                                                                  .GetSection("LogLevel")
                                                                  .GetValue<string>("Default"));

Здесь мы читаем настройку Logging.LogLevel.Default:

Мы можем добавлять свои настройки в файлы Json, предоставляемые по умолчанию и считывать их:

{
  "Settings": {
    "Greetings": {
      "Ru": "Привет",
      "En": "Hello"
    },
    "UserName": "Anonymous",
    "SecretNumber":  124
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Здесь мы добавили новую секцию Settings в которой определили несколько настроек приложения. Для чтения значения какого-либо параметра мы можем использовать полный путь до неё. Следующий код:

app.MapGet("/env", (IConfiguration configuration) => configuration.GetValue<int>("Settings:SecretNumber"));

будет эквивалентен коду:

app.MapGet("/env", (IConfiguration configuration) => configuration.GetSection("Settings")
                                                                  .GetValue<int>("SecretNumber"));

Результат:

Свои Json-файлы конфигурации

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

{
  "Settings": {
    "Greetings": {
      "Ru": "Привет",
      "En": "Hello"
    },
    "UserName": "Anonymous",
    "SecretNumber": 34567
  }
}

Теперь добавим этот файл в конфигурацию и прочитаем настройку Settings:Greetings:Ru:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("options.json");
          
var app = builder.Build();

app.MapGet("/env", (IConfiguration configuration) => configuration.GetValue<string>("Settings:Greetings:Ru"));

Также, мы можем загружать не один, а несколько json-файлов, но при этом стоит помнить, что настройки из последнего загруженного файла, по умолчанию, перезапишут значения одноименных настроек из предыдущих файлов. Например, создадим ещё один файл конфигурации:

{
  "Settings": {
    "Greetings": {
      "Ru": "Добого времени суток",
      "En": "Hello"
    },
    "UserName": "Anonymous",
    "SecretNumber": 34567
  }
}

Теперь также добавим этот файл в конфигурацию и посмотрим на результат:

builder.Configuration.AddJsonFile("options.json")
                     .AddJsonFile("config.json");

XML-файлы

За использование конфигурации в XML-файле отвечает провайдер XmlConfigurationProvider. Для загрузки XML-файлов в качестве конфигурации приложения ASP.NET Core используется метод AddXmlFile(). Например, создадим xml-файл с настройками, которые мы использовали выше:

<?xml version="1.0" encoding="UTF-8" ?>
<Root>
    <Settings>
        <Greetings>
            <Ru>Добого времени суток</Ru>
            <En>Hello</En>
        </Greetings>
        <UserName>Anonymous</UserName>
        <SecretNumber>34567</SecretNumber>
    </Settings>
</Root>

Корневой узел (Root) может иметь любой название. Теперь мы можем читать настройки из этого файла также, как мы это делали с json-файлами:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddXmlFile("xmlConfig.xml");
          
var app = builder.Build();

app.MapGet("/env", (IConfiguration configuration) => configuration.GetValue<string>("Settings:Greetings:Ru"));

Ini-файлы

Для работы с конфигурацией в формате INI применяется провайдер IniConfigurationProvider. Соответственно, загружается такая конфигурация с использованием метода расширения AddIniFile(). Снова вернемся к нашим настройкам и представим их в виде Ini-файла:

[Settings]
UserName=Anonymous
SecretNumber=34567

[Settings:Greetings]
Ru=Добого времени суток
En=Hello

Здесь стоит обратить внимание на два момента:

Подсекция указывается через символ двоеточия, например, Settings:Greetings
Файл должен быть сохранен с кодировкой UTF-8

В остальном, работа с Ini-файлом осуществляется по уже описанному выше алгоритму:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("options.ini");
          
app.MapGet("/env", (IConfiguration configuration) => configuration.GetValue<string>("Settings:Greetings:Ru"));

Перегрузки методов AddJsonFile, AddXmlFile и AddIniFile

Методы AddJsonFile, AddXmlFile и AddIniFile имеют также перегруженные версии, позволяющие более тонко настроить загрузку конфигурации из файлов. Эти перегрузки аналогичны, поэтому рассмотрим их на примере метода AddJsonFile:

public static IConfigurationBuilder AddJsonFile (this IConfigurationBuilder builder, string path, bool optional);
public static IConfigurationBuilder AddJsonFile (this IConfigurationBuilder builder, string path, bool optional, bool reloadOnChange);

Что касается первого параметра (path), то мы его активно использовали выше.

Параметр optional устанавливает является ли файл обязательным или нет.
Параметр reloadOnChange указывает следует ли перезагружать конфигурацию при изменении файла.

Итого

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