方法将配置值绑定到指定类型的对象上,适用于需要将一组相关的配置值聚合到一个对象中的情况

MyOptions? myOptions= _configuration.GetSection("Student").Get();

方法将配置绑定到已实例化的自定义对象上,适用于将配置值直接绑定到现有对象的情况

var myOptions = new MyOptions();_configuration.GetSection(myOptions.Key).Bind(myOptions);

注入容器

builder.Services.Configure(builder.Configuration.GetSection("Student"));

使用配置

private readonly MyOptions _options;public WeatherForecastController(IOptions options){    _options = options.Value;}public void Test(){    string? name = _options.Name;}

更详细的描述，可以直接阅读官方文档

核心执行流程是使用IConfigurationBuilder的Build方法，遍历配置的IConfigurationSource集合，创建IConfigurationProvider实例，将不同的IConfigurationProvider集合存储到IConfigurationRoot中，用户读取时依次遍历IConfigurationProvider集合，获取Value。

根据我的理解，这个过程可以分为三个部分，以IConfigurationBuilder为核心。第一部分是对用户的IConfiguration，第二部分是确定配置数据来源的IConfigurationSource，第三部分则是IConfigurationProvider。

这几个对象的关系：IConfigurationBuilder 用于构建和配置应用程序的配置体系，生成一个 IConfigurationRoot 对象作为配置的根节点，而 IConfiguration 和 IConfigurationSection 则用于读取和访问配置值，处理嵌套和分层的配置结构

在上文介绍的IConfigurationBuilder接口中，Add()方法会将IConfigurationSource到Sources配置源集合中。

FileConfigurationSource 和 StreamConfigurationSource 都继承自 IConfigurationSource，而 JsonConfigurationSource 又继承自 FileConfigurationSource，意味着它们拥有各自的实现方式，但都遵循了 IConfigurationSource 的接口规范。这样，开发人员就可以基于实际需求选择不同的 IConfigurationSource 实现方式来读取与处理配置数据

可以看出 ConfigurationProvider 是 IConfigurationProvider 的基础实现，而 FileConfigurationProvider 和 JsonConfigurationProvider 则是针对特定类型的数据源进行的实现，它们都继承自 ConfigurationProvider 并且遵循了 IConfigurationProvider 接口的规范

以下是源代码的部分删减和修改，以便于更好地理解

在程序启动时，创建一个新的 HostBuilder 实例。调用 ConfigureDefaults() 方法向 HostBuilder 实例中添加一些默认的配置和服务

public static IHostBuilder CreateDefaultBuilder(string[]? args){    HostBuilder builder = new();    return builder.ConfigureDefaults(args);}

在ConfigureDefaults()方法中，会调用静态方法ApplyDefaultAppConfiguration()。用于向应用程序的配置对象中添加默认的配置信息。

internal static void ApplyDefaultAppConfiguration(HostBuilderContext hostingContext, IConfigurationBuilder appConfigBuilder, string[]? args){    // 首先获取主机环境和一些配置参数    IHostEnvironment env = hostingContext.HostingEnvironment;    bool reloadOnChange = GetReloadConfigOnChangeValue(hostingContext);        // 加载 appsettings.json 和 appsettings.{环境名称}.json 文件中的配置信息（如果存在）。同时，还要每当文件改变时重新加载配置信息。    appConfigBuilder.AddJsonFile("appsettings.json", optional: true, reloadOnChange: reloadOnChange)            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: reloadOnChange);        // AddUserSecrets方法加载用户机密    if (env.IsDevelopment() && env.ApplicationName is { Length: > 0 })    {        try        {            var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));            appConfigBuilder.AddUserSecrets(appAssembly, optional: true, reloadOnChange: reloadOnChange);        }        catch (FileNotFoundException)        {            // The assembly cannot be found, so just skip it.        }    }    // 将操作系统环境变量中的配置信息添加到配置对象中    appConfigBuilder.AddEnvironmentVariables();        // AddCommandLineConfig方法将命令行参数中的配置信息添加到配置对象中    AddCommandLineConfig(appConfigBuilder, args);    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL2026:RequiresUnreferencedCode", Justification = "Calling IConfiguration.GetValue is safe when the T is bool.")]    static bool GetReloadConfigOnChangeValue(HostBuilderContext hostingContext) => hostingContext.Configuration.GetValue("hostBuilder:reloadConfigOnChange", defaultValue: true);}

我们继续跟进AddEnvironmentVariables方法，就会发现在主机初始时，就已经将默认的ConfigurationSource添加到configurationBuilder中了。

public static IConfigurationBuilder AddCommandLine(    this IConfigurationBuilder configurationBuilder,    string[] args,    IDictionary? switchMappings){   configurationBuilder.Add(new CommandLineConfigurationSource { Args = args, SwitchMappings = switchMappings });   return configurationBuilder;}

接下来就开始构建和返回 IHost 实例

public IHost Build(){    _hostBuilt = true;        // 诊断监听器    using DiagnosticListener diagnosticListener = LogHostBuilding(this);        // 初始化主机配置，包括默认配置和应用程序附加的配置    InitializeHostConfiguration();    // 初始化主机环境，设置应用程序名称、内容根路径和环境名称    InitializeHostingEnvironment();    // 初始化 HostBuilderContext 对象，将主机环境和主机配置设置为成员变量    InitializeHostBuilderContext();    // 初始化应用程序配置，包括从 appsettings.json 文件加载配置信息和应用程序自定义的配置    InitializeAppConfiguration();    // 初始化服务提供程序，包括向 DI 容器中添加所需的服务并编译容器以生成 IServiceProvider 实例    InitializeServiceProvider();    return ResolveHost(_appServices, diagnosticListener);}

在InitializeHostConfiguration()方法中，我们创建了ConfigurationBuilder对象，并通过调用Build()方法生成了一个IConfiguration实例。然而，在下文的InitializeAppConfiguration()方法中，我们又重新创建了一次ConfigurationBuilder并进行了配置。因此，我们可以直接跳过InitializeHostConfiguration()方法，直接来看InitializeAppConfiguration()方法的实现。

private void InitializeAppConfiguration(){    IConfigurationBuilder configBuilder = new ConfigurationBuilder()        .SetBasePath(_hostingEnvironment!.ContentRootPath)        .AddConfiguration(_hostConfiguration!, shouldDisposeConfiguration: true);    foreach (Action buildAction in _configureAppConfigActions)    {        buildAction(_hostBuilderContext!, configBuilder);    }    // Build() 方法从 ConfigurationBuilder 实例中创建 IConfiguration 实例    _appConfiguration = configBuilder.Build();    _hostBuilderContext!.Configuration = _appConfiguration;}

经过前面的铺垫，我们终于来到了IConfigurationBuilder对象中。在该对象中，Build()方法的实现非常简单，它遍历Sources集合中的每个IConfigurationSource对象，并调用其Build()方法生成对应的IConfigurationProvider实例。然后，将所有的IConfigurationProvider合并到一个单独的IConfigurationRoot实例中，最终将该对象返回。

public IConfigurationRoot Build(){    var providers = new List();    foreach (IConfigurationSource source in Sources)    {        IConfigurationProvider provider = source.Build(this);        providers.Add(provider);    }    return new ConfigurationRoot(providers);}

我们看下IConfigurationSource的Build()方法的实现，分了图片左侧这么多。我们挑选命令行的深入看一下。

CommandLineConfigurationProvider的构造方法：

public CommandLineConfigurationProvider(IEnumerable args, IDictionary? switchMappings = null){    Args = args;    if (switchMappings != null)    {        // 确保命令行参数映射到配置键的字典是有效的、无重复的，并且所有键都是大小写不敏感的        _switchMappings = GetValidatedSwitchMappingsCopy(switchMappings);    }}private static Dictionary GetValidatedSwitchMappingsCopy(IDictionary switchMappings){    // 使用不区分大小写的比较器来确保字典中的所有键都是大小写不敏感的    var switchMappingsCopy = new Dictionary(switchMappings.Count, StringComparer.OrdinalIgnoreCase);    foreach (KeyValuePair mapping in switchMappings)    {        // Only keys start with "--" or "-" are acceptable        if (!mapping.Key.StartsWith("-") && !mapping.Key.StartsWith("--"))        {            throw new ArgumentException(                SR.Format(SR.Error_InvalidSwitchMapping, mapping.Key),                nameof(switchMappings));        }        if (switchMappingsCopy.ContainsKey(mapping.Key))        {            throw new ArgumentException(                SR.Format(SR.Error_DuplicatedKeyInSwitchMappings, mapping.Key),                nameof(switchMappings));        }        switchMappingsCopy.Add(mapping.Key, mapping.Value);    }    return switchMappingsCopy;}

在上文的IConfigurationBuilder的Build()方法中，我们将所有的IConfigurationProvider对象添加到ConfigurationRoot并返回配置根对象。其中，我们需要重点关注的是p.Load()方法用于加载配置信息。该方法涉及的热加载，在下文中介绍。

public ConfigurationRoot(IList providers){    _providers = providers;    // 用于存储所有的更改通知委托对象    _changeTokenRegistrations = new List(providers.Count);    foreach (IConfigurationProvider p in providers)    {        p.Load();        // ChangeToken.OnChange() 方法注册一个更改通知委托，监听该提供程序的更改通知，并在收到通知时调用 RaiseChanged() 方法        _changeTokenRegistrations.Add(ChangeToken.OnChange(p.GetReloadToken, RaiseChanged));    }}

该方法是解析命令行参数的Load方法。如有兴趣，您可以继续查看该方法的实现代码，来深入了解其中的实现逻辑。(该方法代码全贴)

public override void Load(){    var data = new Dictionary(StringComparer.OrdinalIgnoreCase);    string key, value;    using (IEnumerator enumerator = Args.GetEnumerator())    {        while (enumerator.MoveNext())        {            string currentArg = enumerator.Current;            int keyStartIndex = 0;            if (currentArg.StartsWith("--"))            {                keyStartIndex = 2;            }            else if (currentArg.StartsWith("-"))            {                keyStartIndex = 1;            }            else if (currentArg.StartsWith("/"))            {                // "/SomeSwitch" is equivalent to "--SomeSwitch" when interpreting switch mappings                // So we do a conversion to simplify later processing                currentArg = $"--{currentArg.Substring(1)}";                keyStartIndex = 2;            }            int separator = currentArg.IndexOf("=");            if (separator < 0)            {                // If there is neither equal sign nor prefix in current argument, it is an invalid format                if (keyStartIndex == 0)                {                    // Ignore invalid formats                    continue;                }                // If the switch is a key in given switch mappings, interpret it                if (_switchMappings != null && _switchMappings.TryGetValue(currentArg, out string? mappedKey))                {                    key = mappedKey;                }                // If the switch starts with a single "-" and it isn"t in given mappings , it is an invalid usage so ignore it                else if (keyStartIndex == 1)                {                    continue;                }                // Otherwise, use the switch name directly as a key                else                {                    key = currentArg.Substring(keyStartIndex);                }                if (!enumerator.MoveNext())                {                    // ignore missing values                    continue;                }                value = enumerator.Current;            }            else            {                string keySegment = currentArg.Substring(0, separator);                // If the switch is a key in given switch mappings, interpret it                if (_switchMappings != null && _switchMappings.TryGetValue(keySegment, out string? mappedKeySegment))                {                    key = mappedKeySegment;                }                // If the switch starts with a single "-" and it isn"t in given mappings , it is an invalid usage                else if (keyStartIndex == 1)                {                    throw new FormatException(SR.Format(SR.Error_ShortSwitchNotDefined, currentArg));                }                // Otherwise, use the switch name directly as a key                else                {                    key = currentArg.Substring(keyStartIndex, separator - keyStartIndex);                }                value = currentArg.Substring(separator + 1);            }            // Override value when key is duplicated. So we always have the last argument win.            data[key] = value;        }    }    Data = data;}

通过上文我们已经了解了如何添加和解析配置文件。关于配置键的读取和设置也非常简单。在ConfigurationRoot类中，我们看下基于索引的方法进行操作

public string? this[string key]{    get => GetConfiguration(_providers, key);    set => SetConfiguration(_providers, key, value);}

GetConfiguration() 方法会倒序依次遍历所有的配置提供程序，当获取到key,就会返回结果。（所以后添加的配置文件会覆盖之前的key）

internal static string? GetConfiguration(IList providers, string key){    for (int i = providers.Count - 1; i >= 0; i--)    {        IConfigurationProvider provider = providers[i];        if (provider.TryGet(key, out string? value))        {            return value;        }    }    return null;}

SetConfiguration（）方法会将每个IConfigurationProvider 中的key,进行修改

internal static void SetConfiguration(IList providers, string key, string? value){    foreach (IConfigurationProvider provider in providers)    {        provider.Set(key, value);    }}

我们现在将从程序中添加 JSON 配置文件并解析配置文件的源码流程进行说明。

builder.Configuration.AddJsonFile("MyConfig.json",        optional: true, // 文件是否可选        reloadOnChange: true ); // 如果文件更改，是否重载配置

我们来看 AddJsonFile() 方法，它实际上是使用参数构建了一个 JsonConfigurationSource，然后将其传递给 IConfigurationBuilder。

public static IConfigurationBuilder AddJsonFile(this IConfigurationBuilder builder, IFileProvider? provider, string path, bool optional, bool reloadOnChange){    return builder.AddJsonFile(s =>    {        s.FileProvider = provider;// 这个为自动更新提供文件变动监听方法        s.Path = path;        s.Optional = optional;        s.ReloadOnChange = reloadOnChange;        s.ResolveFileProvider();    });}public static IConfigurationBuilder AddJsonFile(this IConfigurationBuilder builder, Action? configureSource)    => builder.Add(configureSource);

JsonConfigurationSource 类的构建方法，用于创建和返回一个新的IConfigurationProvider 对象。EnsureDefaults()确保提供了默认值，返回一个具体的解析实例JsonConfigurationProvider

public class JsonConfigurationSource : FileConfigurationSource{  public override IConfigurationProvider Build(IConfigurationBuilder builder)  {      EnsureDefaults(builder);      return new JsonConfigurationProvider(this);  }}

FileConfigurationProvider是JsonConfigurationProvider的父类，在构造方法中ChangeToken.OnChange方法来持续监听文件更新。

public FileConfigurationProvider(FileConfigurationSource source){    ThrowHelper.ThrowIfNull(source);    Source = source;    if (Source.ReloadOnChange && Source.FileProvider != null)    {        _changeTokenRegistration = ChangeToken.OnChange(            () => Source.FileProvider.Watch(Source.Path!),            () =>            {                Thread.Sleep(Source.ReloadDelay);                Load(reload: true);            });    }}

JsonConfigurationProvider 方法和上文命令行一样，到了具体的实现。

public class JsonConfigurationProvider : FileConfigurationProvider{    public JsonConfigurationProvider(JsonConfigurationSource source) : base(source) { }    public override void Load(Stream stream)    {        try        {            Data = JsonConfigurationFileParser.Parse(stream);        }        catch (JsonException e)        {            throw new FormatException(SR.Error_JSONParseError, e);        }    }}

简要概述自动更新（热加载）的实现过程基于生产者和消费者的关系。它利用FileProvider（内部使用操作系统的文件变更API，并可选择性地开启轮询机制）来生成文件的变更信息，并通过Load/ReLoad方法来消费和重新加载文件。

IFileProvider 是一个用于抽象文件系统访问的接口。它允许您使用文件和文件夹的基本操作，例如读取、写入和删除文件。

IFileProvider 接口还支持监视文件系统上的更改。您可以注册一个事件，当文件或目录上发生更改时，将调用回调方法。这对于及时更新应用程序配置非常有用。

.NET Core 内置了许多实现了 IFileProvider 接口的文件访问器，例如 PhysicalFileProvider、EmbeddedFileProvider和CompositeFileProvider。在配置文件中默认的是PhysicalFileProvider。

下边是一个使用PhysicalFileProvider来监听文件更改的Demo：

public static void Main(string[] args){    string path = @"C:\Users\";    // 生效一次    PhysicalFileProvider phyFileProvider = new PhysicalFileProvider(path);    // 订阅文件更改事件    IChangeToken watcher = phyFileProvider.Watch("*.*");    watcher.RegisterChangeCallback((state) =>    {        Console.WriteLine($"文件发生改变: {state}");    }, null);    // 持续生效             ChangeToken.OnChange(        changeTokenProducer: () => phyFileProvider.Watch("*.*"),        changeTokenConsumer: () => Console.WriteLine($"文件发生改变")    );    Console.ReadLine();}

在我们.NET中ChangeToken和IChangeToken是用于实现配置变更通知的机制。它们是用于监视配置更改并触发相应操作的重要组件。

ChangeToken是一个抽象类，用于表示一个令牌，用于检测配置更改。它定义了一种模式，允许订阅者注册在配置更改时接收通知。

public static class ChangeToken{  public static IDisposable OnChange(Func changeTokenProducer, Action changeTokenConsumer, TState state)  {      return new ChangeTokenRegistration(changeTokenProducer, changeTokenConsumer, state);  }}

注册ChangeToken的回调函数

public ChangeTokenRegistration(Func changeTokenProducer, Action changeTokenConsumer, TState state){    _changeTokenProducer = changeTokenProducer;    _changeTokenConsumer = changeTokenConsumer;    _state = state;    IChangeToken? token = changeTokenProducer();    RegisterChangeTokenCallback(token);}private void RegisterChangeTokenCallback(IChangeToken? token){    if (token is null)    {        return;    }    IDisposable registraton = token.RegisterChangeCallback(s => ((ChangeTokenRegistration?)s)!.OnChangeTokenFired(), this);    if (token.HasChanged && token.ActiveChangeCallbacks)    {        registraton?.Dispose();        return;    }    SetDisposable(registraton);}

IChangeToken是ChangeToken的接口，定义了ChangeToken的行为和功能。它包含一个属性HasChanged，指示令牌是否已更改，以及一个事件RegisterChangeCallback，用于注册当令牌更改时触发的回调函数。

public interface IChangeToken{    bool HasChanged { get; }    bool ActiveChangeCallbacks { get; }    IDisposable RegisterChangeCallback(Action callback, object? state);}

PhysicalFileProvider 是 .NET中实现 IFileProvider 接口的一个类，用于访问物理文件系统上的文件和文件夹。它可以在应用程序启动时，自动注册到 DI 容器中。

PhysicalFileProvider 的 Watch 方法用于监视指定路径下的文件和文件夹，以便在更改时自动更新应用程序。它返回了一个 IChangeToken 对象，用于触发更改通知。

public IChangeToken Watch(string filter){    if (filter == null || PathUtils.HasInvalidFilterChars(filter))    {        return NullChangeToken.Singleton;    }    // Relative paths starting with leading slashes are okay    filter = filter.TrimStart(_pathSeparators);    return FileWatcher.CreateFileChangeToken(filter);}

CreateFileChangeToken方法接收一个字符串参数 filter，表示要监视的文件或文件夹的相对路径。它将返回一个实现了 IChangeToken 接口的对象作为文件更改的通知。

通过调用 GetOrAddChangeToken(filter) 方法，查找与 filter 参数对应的更改令牌 IChangeToken 对象。如果找到一个 IChangeToken 对象，则返回它，否则会创建一个新的更改令牌并添加到缓存中，然后返回它。

当一个文件或文件夹被更改时，FileSystemWatcher（这个阅读有点难度，暂时没有深入研究） 会通知更改令牌 IChangeToken 对象，PollForChanges 属性为 true时，在默认时间间隔内检查文件或文件夹的变化，进而引发更改通知。然后，应用程序可以处理这个更改通知，例如重新加载配置或更新数据源。

public IChangeToken CreateFileChangeToken(string filter){    IChangeToken changeToken = GetOrAddChangeToken(filter);    return changeToken;}

GetOrAddWildcardChangeToken 是 PhysicalFileProvider 用于创建通配符监视的 IChangeToken 对象的方法，可在文件或文件夹更改时通知应用程序，并进行必要的更新。

internal IChangeToken GetOrAddWildcardChangeToken(string pattern){    if (!_wildcardTokenLookup.TryGetValue(pattern, out ChangeTokenInfo tokenInfo))    {        var cancellationTokenSource = new CancellationTokenSource();        var cancellationChangeToken = new CancellationChangeToken(cancellationTokenSource.Token);        var matcher = new Matcher(StringComparison.OrdinalIgnoreCase);        matcher.AddInclude(pattern);        tokenInfo = new ChangeTokenInfo(cancellationTokenSource, cancellationChangeToken, matcher);        tokenInfo = _wildcardTokenLookup.GetOrAdd(pattern, tokenInfo);    }    IChangeToken changeToken = tokenInfo.ChangeToken;    if (PollForChanges)    {        // The expiry of CancellationChangeToken is controlled by this type and consequently we can cache it.        // PollingFileChangeToken on the other hand manages its own lifetime and consequently we cannot cache it.        var pollingChangeToken = new PollingWildCardChangeToken(_root, pattern);        if (UseActivePolling)        {            pollingChangeToken.ActiveChangeCallbacks = true;            pollingChangeToken.CancellationTokenSource = new CancellationTokenSource();            PollingChangeTokens.TryAdd(pollingChangeToken, pollingChangeToken);        }        changeToken = new CompositeChangeToken(            new[]            {                changeToken,                pollingChangeToken,            });    }    return changeToken;}

现在回顾一下配置文件的自动更新，相信您应该能够理解它了。

通过上文对源码的解析，我们已经了解到了 Configuration 组件的工作流程。在封装自定义数据源时，我们不需要关注热加载部分，只需要按照以下步骤进行：

如果需要支持热加载功能，还需要相应地实现 IChangeToken 接口和 IOptionsChangeTokenSource接口。这些接口的实现可以参考官方文档或其他资料。

具体示例请看官方Demo

在 JSON 文件中，可以使用 [ ] 符号表示一个数组。如果要将这个数组作为配置项读取，可以使用 GetSection() 方法获取该数组所在的子节点，然后通过 AsEnumerable() 方法将其转换为 IEnumerable> 类型，并对其中的每个元素进行处理。

如果环境变量中包含特殊字符（如 $、:、/ 等），可能会导致解析错误。为了正确地从环境变量中读取特殊字符，可以使用双引号 " 对变量进行引用，例如："my$envVar"。

可以使用 AddCommandLine() 方法将命令行参数添加到 IConfigurationBuilder 中。在使用该方法时，需要指定一个字典，用于将命令行参数映射到配置键。

可以使用 Add() 方法按顺序向 IConfigurationBuilder 中添加配置源。越先添加的配置源优先级越高。此外，还可以使用 AddJsonFile().AddEnvironmentVariables() 等方法来指定默认的配置源，并在需要时使用 AddFirst()、AddLast() 等方法将其他配置源添加到特定位置。

可以继承 ConfigurationProvider 抽象类，并实现其抽象成员来创建一个新的 IConfigurationProvider。然后，可以通过 Add() 方法将其添加到 IConfigurationBuilder 中，并在需要时进行配置。

这篇文章耗时近两周。阅读源码的过程并不算困难，但是将整个过程通过文字进行讲解时，却遇到了如何设计文章结构和顺序的困扰。幸好有GPT的帮助，可以提供语言表达上的支持。接下来，我将努力提升自己的技术水平和写作能力，为我们.NET社区贡献绵薄之力。

如果您觉得这篇文章有所收获，还请点个赞并关注。如果您有宝贵建议，欢迎在评论区留言，非常感谢您的支持！

(也可以关注我的公众号噢：Broder,万分感谢^_)