Microsoft.Extensions.Configuration 详细应用指南

Microsoft.Extensions.Configuration 是.NET Core/.NET 5+中用于处理应用程序配置的核心组件。它提供了一个统一的配置系统，支持多种配置源，如JSON文件、环境变量、命令行参数等。

主要特性

分层配置源
多种配置提供程序
强类型绑定
配置重载
依赖注入集成

基础使用示例

安装必要的NuGet包

XML
<ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.CommandLine" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder " Version="8.0.0" />
</ItemGroup>

创建基本配置

C#
using Microsoft.Extensions.Configuration;

namespace AppExtConfig
{
    internal class Program
    {
        static void Main(string[] args)
        {

            // 创建配置构建器
            var builder = new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())    // 设置配置文件的基础路径
                .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)    // 添加JSON配置源
                .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json", optional: true)    // 添加环境特定的配置
                .AddEnvironmentVariables()    // 添加环境变量
                .AddCommandLine(args);        // 添加命令行参数

            IConfiguration configuration = builder.Build();

            // 读取配置值
            string connectionString = configuration.GetValue<string>("ConnectionStrings:DefaultConnection");
            
            Console.WriteLine(connectionString);
        }
    }
}

配置文件示例 (appsettings.json)

JSON
{
  "AppSettings": {
    "ApiUrl": "https://api.example.com",
    "MaxRetryCount": 3
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MyDb;User Id=sa;Password=123456;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    }
  }
}

高级特性示例

强类型配置绑定

C#
using Microsoft.Extensions.Configuration;

namespace AppExtConfig
{
    // 定义配置类
    public class AppSettings
    {
        public string ApiUrl { get; set; }
        public int MaxRetryCount { get; set; }
    }

    public class ConnectionStrings
    {
        public string DefaultConnection { get; set; }
    }

    internal class Program
    {
        static void Main(string[] args)
        {

            // 创建配置构建器
            var builder = new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())    // 设置配置文件的基础路径
                .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)    // 添加JSON配置源
                .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json", optional: true)    // 添加环境特定的配置
                .AddEnvironmentVariables()    // 添加环境变量
                .AddCommandLine(args);        // 添加命令行参数

            IConfiguration configuration = builder.Build();

            // 绑定配置
            var appSettings = configuration.GetSection("AppSettings").Get<AppSettings>();
            var connectionStrings = configuration.GetSection("ConnectionStrings").Get<ConnectionStrings>();

            // 使用配置
            Console.WriteLine($"API URL: {appSettings.ApiUrl}");
            Console.WriteLine($"Max Retry Count: {appSettings.MaxRetryCount}");

            Console.WriteLine($"Default Connection: {connectionStrings.DefaultConnection}");

        }
    }
}

配置变更监听

C#
// 监听配置变更
IChangeToken token = configuration.GetReloadToken();
token.RegisterChangeCallback(state => 
{
    Console.WriteLine("配置已更改！");
    // 重新加载配置
    var newApiUrl = configuration["AppSettings:ApiUrl"];
    Console.WriteLine($"新的API URL: {newApiUrl}");
}, state: null);

自定义配置源

C#
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Primitives;

namespace AppExtConfig
{
    public class CustomConfigurationSource : IConfigurationSource
    {
        public IConfigurationProvider Build(IConfigurationBuilder builder)
        {
            return new CustomConfigurationProvider();
        }
    }

    public class CustomConfigurationProvider : ConfigurationProvider
    {
        public override void Load()
        {
            // 设置自定义配置数据
            Data = new Dictionary<string, string>
        {
            {"CustomKey", "CustomValue"},
            {"CustomSection:NestedKey", "NestedValue"}
        };
        }
    }

    internal class Program
    {
        static void Main(string[] args)
        {

            // 使用自定义配置源
            var builder = new ConfigurationBuilder()
                .Add(new CustomConfigurationSource());

            // 构建配置  
            IConfiguration configuration = builder.Build();

            // 方式1：直接读取配置值  
            string customValue = configuration["CustomKey"];
            string nestedValue = configuration["CustomSection:NestedKey"];
        }
    }
}

依赖注入集成

C#
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.DependencyInjection.Abstractions
Microsoft.Extensions.Options
Microsoft.Extensions.Options.ConfigurationExtensions

C#
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Primitives;

namespace AppExtConfig
{
    public class AppSettings
    {
        public string ApiUrl { get; set; }
        public string ApiKey { get; set; }
    }

    public interface IMyService
    {
        void DoSomething();
    }

    public class MyService : IMyService
    {
        private readonly AppSettings _settings;

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

        public void DoSomething()
        {
            Console.WriteLine($"Using API URL: {_settings.ApiUrl}");
            Console.WriteLine($"Using API Key: {_settings.ApiKey}");
        }
    }

    internal class Program
    {
        static void Main(string[] args)
        {
            var services = new ServiceCollection();

            IConfiguration configuration = new ConfigurationBuilder()
                .SetBasePath(Directory.GetCurrentDirectory())
                .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
                .Build();

            // 或者使用这种更简洁的方式  
            services.Configure<AppSettings>(configuration.GetSection("AppSettings"));  

            services.AddTransient<IMyService, MyService>();

            var serviceProvider = services.BuildServiceProvider();

            var myService = serviceProvider.GetService<IMyService>();
            myService?.DoSomething();

            Console.ReadLine();
        }
    }
}

最佳实践

C#
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using System;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        try
        {
            // 创建主机  
            using var host = CreateHostBuilder(args).Build();

            // 验证配置  
            var validator = host.Services.GetRequiredService<IConfigurationValidator>();
            validator.ValidateConfiguration();

            // 运行示例服务  
            var exampleService = host.Services.GetRequiredService<ExampleService>();
            await exampleService.DoSomethingAsync();

            Console.WriteLine("按任意键退出...");
            Console.ReadKey();
        }
        catch (ConfigurationValidationException ex)
        {
            Console.WriteLine($"配置验证错误: {ex.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"发生错误: {ex.Message}");
        }
    }

    private static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                var env = hostingContext.HostingEnvironment;

                config.SetBasePath(Directory.GetCurrentDirectory())
                    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
                    .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true)
                    .AddJsonFile("appsettings.local.json", optional: true)
                    .AddEnvironmentVariables()
                    .AddCommandLine(args);

                // 开发环境使用用户机密  
                if (env.IsDevelopment())
                {
                    config.AddUserSecrets<Program>();
                }
            })
            .ConfigureServices((context, services) =>
            {
                // 注册配置  
                services.Configure<AppSettings>(
                    context.Configuration.GetSection("AppSettings"));

                // 注册服务  
                services.AddSingleton<IConfigurationValidator, ConfigurationValidator>();
                services.AddTransient<ExampleService>();
            })
            .ConfigureLogging(logging =>
            {
                logging.ClearProviders();
                logging.AddConsole();
                logging.AddDebug();
            });
}

// AppSettings.cs  
public class AppSettings
{
    public string ApiUrl { get; set; }
    public int MaxRetryCount { get; set; }
    public DatabaseSettings Database { get; set; }
}

public class DatabaseSettings
{
    public string ConnectionString { get; set; }
    public int CommandTimeout { get; set; }
}

// ConfigurationValidator.cs  
public interface IConfigurationValidator
{
    void ValidateConfiguration();
}

public class ConfigurationValidator : IConfigurationValidator
{
    private readonly IOptions<AppSettings> _settings;
    private readonly ILogger<ConfigurationValidator> _logger;

    public ConfigurationValidator(
        IOptions<AppSettings> settings,
        ILogger<ConfigurationValidator> logger)
    {
        _settings = settings;
        _logger = logger;
    }

    public void ValidateConfiguration()
    {
        var settings = _settings.Value;

        if (string.IsNullOrEmpty(settings.ApiUrl))
        {
            throw new ConfigurationValidationException("ApiUrl 不能为空");
        }

        if (settings.MaxRetryCount <= 0)
        {
            throw new ConfigurationValidationException("MaxRetryCount 必须大于0");
        }

        if (settings.Database == null)
        {
            throw new ConfigurationValidationException("Database 配置不能为空");
        }

        if (string.IsNullOrEmpty(settings.Database.ConnectionString))
        {
            throw new ConfigurationValidationException("数据库连接字符串不能为空");
        }

        _logger.LogInformation("配置验证完成");
    }
}

public class ConfigurationValidationException : Exception
{
    public ConfigurationValidationException(string message) : base(message)
    {
    }
}

// ExampleService.cs  
public class ExampleService
{
    private readonly AppSettings _settings;
    private readonly ILogger<ExampleService> _logger;

    public ExampleService(
        IOptions<AppSettings> settings,
        ILogger<ExampleService> logger)
    {
        _settings = settings.Value;
        _logger = logger;
    }

    public async Task DoSomethingAsync()
    {
        _logger.LogInformation("=== 当前配置信息 ===");
        _logger.LogInformation($"API地址: {_settings.ApiUrl}");
        _logger.LogInformation($"最大重试次数: {_settings.MaxRetryCount}");
        _logger.LogInformation($"数据库连接: {_settings.Database.ConnectionString}");
        _logger.LogInformation($"命令超时: {_settings.Database.CommandTimeout}秒");

        // 模拟一些异步操作  
        await Task.Delay(1000);
        _logger.LogInformation("操作完成");
    }
}

总结

Microsoft.Extensions.Configuration 提供了强大而灵活的配置管理功能：

支持多种配置源
分层配置管理
强类型配置绑定
运行时配置重载
与依赖注入完美集成

通过合理使用这些功能，可以构建出易于维护、安全可靠的配置系统。在实际应用中，应根据具体需求选择合适的配置方式，并遵循最佳实践来管理应用程序配置。

目录