Конфигурация приложений C# (.NET): Microsoft.Extensions.Configuration

Конфигурация приложений C# (.NET): полное руководство

Управление конфигурацией — одна из ключевых задач при разработке современных приложений на C# (.NET). Библиотека Microsoft.Extensions.Configuration предоставляет мощный и гибкий механизм для чтения настроек из различных источников: JSON-файлов, переменных окружения, аргументов командной строки и секретов. В этой статье мы подробно разберём, как настроить конфигурацию в .NET приложениях, используя лучшие практики и примеры кода.

Основные возможности библиотеки

• Множество источников данных: JSON, XML, INI, переменные окружения, аргументы командной строки, Azure Key Vault и другие.
• Иерархическая структура: поддержка вложенных разделов через ключи с двоеточием (Section:Subsection:Key).
• Привязка к классам (Options Pattern): автоматическое заполнение объектов POCO из конфигурации.
• Гибкое переопределение: последний добавленный источник имеет приоритет.
• Поддержка секретов: для разработки — Secret Manager, для продакшена — защищённые хранилища.

Установка и подключение

Для работы с конфигурацией в .NET приложении (консольное, ASP.NET Core, MAUI и др.) необходимо установить NuGet-пакет:

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables
dotnet add package Microsoft.Extensions.Configuration.CommandLine

В ASP.NET Core эти пакеты уже включены по умолчанию.

Базовый пример: чтение из appsettings.json

Создадим файл appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MyDb;User Id=sa;Password=MyPass;"
  },
  "AppSettings": {
    "AppName": "MyApp",
    "Version": "1.0.0",
    "MaxRetries": 3
  }
}

Код для чтения конфигурации в консольном приложении:

using Microsoft.Extensions.Configuration;

class Program
{
    static void Main(string[] args)
    {
        // Создаём конфигурацию
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
            .AddEnvironmentVariables()
            .AddCommandLine(args)
            .Build();

        // Чтение простых значений
        string appName = configuration["AppSettings:AppName"];
        Console.WriteLine($"App Name: {appName}");

        // Чтение вложенных разделов
        string connString = configuration.GetConnectionString("DefaultConnection");
        Console.WriteLine($"Connection String: {connString}");

        // Чтение целого числа
        int maxRetries = int.Parse(configuration["AppSettings:MaxRetries"]);
        Console.WriteLine($"Max Retries: {maxRetries}");

        // Получение раздела целиком
        var appSettingsSection = configuration.GetSection("AppSettings");
        Console.WriteLine($"Version: {appSettingsSection["Version"]}");
    }
}

Шаблон Options (привязка к классам)

Лучшая практика — использовать строго типизированную конфигурацию через IOptions<T>. Для этого:

1. Создайте класс для секции конфигурации:

public class AppSettings
{
    public string AppName { get; set; }
    public string Version { get; set; }
    public int MaxRetries { get; set; }
}

2. Зарегистрируйте конфигурацию в DI-контейнере (для ASP.NET Core или с помощью Microsoft.Extensions.DependencyInjection):

// В Program.cs (ASP.NET Core) или вручную
builder.Services.Configure<AppSettings>(
    builder.Configuration.GetSection("AppSettings"));

// Затем в любом сервисе используйте IOptions
public class MyService
{
    private readonly AppSettings _settings;

    public MyService(IOptions<AppSettings> options)
    {
        _settings = options.Value;
    }

    public void DoWork()
    {
        Console.WriteLine($"App: {_settings.AppName}, Version: {_settings.Version}");
    }
}

Работа с переменными окружения и секретами

Для чувствительных данных (пароли, ключи API) используйте:

• Переменные окружения: AddEnvironmentVariables() — ключи с двоеточием заменяются на двойное подчёркивание (AppSettings__MaxRetries).
• Secret Manager (для разработки): dotnet user-secrets set "AppSettings:ApiKey" "my-secret-key"