.NET Core 3.0之Configuration原始碼探究(一)

Configuration總體介紹

微軟在.NET Core裡設計出了全新的配置體系，並以非常靈活、可擴充套件的方式實現。從其原始碼來看，其執行機制大致是，根據其Source，建立一個Builder例項，並會向其新增Provider，在我們使用配置資訊的時候，會從記憶體中獲取相應的Provider例項。

.NET Core採用了統一的呼叫方式來載入不同型別的配置資訊，並通過統一的抽象介面IConfigurationSource對配置源進行管理，這也是剛剛所說的靈活。而其擴充套件性就是我們可以自己自定義新的Provider例項，而不會改變其原來的呼叫方式。接下來的文章將會基於Consul，擴充套件一個新的Provider例項。

在ASP.NET Core 中，我們的應用配置是基於IConfigurationProvider的鍵值對。 我們先看一下思維導圖：

基於上圖，我們可以看到主要有鍵值對源有多種，分別是：

 環境變數

命令列引數

各種形式的配置檔案

記憶體物件

使用者自定義擴充套件源 

核心物件

在介紹.NET Core配置功能之前，先簡要說明一下Microsoft.Extensions.Configuration.Abstractions，該元件抽象了.NET Core的配置功能，並對自定義擴充套件制定了新的標準。以下介紹的四個核心物件全部來自於該元件。

IConfiguration

該介面表示一組鍵/值應用程式配置屬性，應用程式使用配置時的入口物件，.NET Core對其有多種擴充套件，其派生類包括位於統一類庫的IConfigurationSection，以及Microsoft.Extensions.Configuration類庫中的ConfigurationRoot、ConfigurationSection、IConfigurationRoot。我們可以通過DI獲取IConfiguration例項。

它主要有以下三個方法：

• GetChildren()：獲取直接子配置子節
• GetReloadToken()：返回一個IChangeToken，可用於確定何時重新載入配置
• GetSection(String)：獲取指定鍵的子節點

我們來看一下原始碼：

/// <summary>
    /// Represents a set of key/value application configuration properties.
    /// </summary>
    public interface IConfiguration
    {
        /// <summary>
        /// Gets or sets a configuration value.
        /// </summary>
        /// <param name="key">The configuration key.</param>
        /// <returns>The configuration value.</returns>
        string this[string key] { get; set; }

        /// <summary>
        /// Gets a configuration sub-section with the specified key.
        /// </summary>
        /// <param name="key">The key of the configuration section.</param>
        /// <returns>The <see cref="IConfigurationSection"/>.</returns>
        /// <remarks>
        ///     This method will never return <c>null</c>. If no matching sub-section is found with the specified key,
        ///     an empty <see cref="IConfigurationSection"/> will be returned.
        /// </remarks>
        IConfigurationSection GetSection(string key);

        /// <summary>
        /// Gets the immediate descendant configuration sub-sections.
        /// </summary>
        /// <returns>The configuration sub-sections.</returns>
        IEnumerable<IConfigurationSection> GetChildren();

        /// <summary>
        /// Returns a <see cref="IChangeToken"/> that can be used to observe when this configuration is reloaded.
        /// </summary>
        /// <returns>A <see cref="IChangeToken"/>.</returns>
        IChangeToken GetReloadToken();
    }

通常我們要求配置檔案要有足夠的靈活性，尤其是我們所擴充套件的配置資訊存放在了其他伺服器，當修改的時候我們很需要一套監控功能，以及時靈活的應對配置資訊的修改。現在.NET Core為我們提供了這樣一個功能，我們只需要自定義少量程式碼即可完成配置資訊的同步。這個方法就是GetReloadToken()，其返回值是IChangeToken。此處對配置資訊的同步只做一個引子，後面的文章會詳細說明。

由於ConfigurationRoot、ConfigurationSection聚集於IConfiguration介面，此處也對這兩個類進行討論，方便我們對.NET Core的配置功能有個更加形象的印象。這兩個介面，本質上就是.NET Core關於配置資訊的讀取方式。

XML是使用比較廣泛的一種資料結構，我們在配置XML時，一般會使用根節點、父節點、子節點之類的術語，此處也一樣。

ConfigurationRoot是配置的根節點，也實現了IConfigurationRoot，此介面只有一個方法，其主要功能就是實現對配置資訊的重新載入，另外還包括一個IConfigurationProvider型別的集合屬性。其原始碼如下

/// <summary>
/// Represents the root of an <see cref="IConfiguration"/> hierarchy.
/// </summary>
public interface IConfigurationRoot : IConfiguration
{
    /// <summary>
    /// Force the configuration values to be reloaded from the underlying <see cref="IConfigurationProvider"/>s.
    /// </summary>
    void Reload();

    /// <summary>
    /// The <see cref="IConfigurationProvider"/>s for this configuration.
    /// </summary>
    IEnumerable<IConfigurationProvider> Providers { get; }
}

下面是ConfigurationRoot關於Reload()方法的實現

/// <summary>
/// Force the configuration values to be reloaded from the underlying sources.
/// </summary>
public void Reload()
{
    foreach (var provider in _providers)
    {
        provider.Load();
    }

    RaiseChanged();
}

通過原始碼我們知道，如果呼叫了Reload()方法，所有型別的Provider都會重新載入。

前面有ConfigurationRoot表示配置的根節點，那麼ConfigurationSection則表示非跟節點，畢竟父節點、子節點都是相對，所以此處使用非根節點。ConfigurationSection繼承於IConfigurationSection，該介面只有三個只讀屬性，分別表示配置資訊的Key、Value以及路徑資訊，需要指出的是，此處的路徑資訊主要指從根節點到當前節點的路徑，以表示當前節點的位置，類似於A:B:C可以表示節點C的位置，其中A、B、C都是ConfigurationSection的Key。以下是ConfigurationSection的原始碼

/// <summary>
/// Represents a section of application configuration values.
/// </summary>
public interface IConfigurationSection : IConfiguration
{
    /// <summary>
    /// Gets the key this section occupies in its parent.
    /// </summary>
    string Key { get; }

    /// <summary>
    /// Gets the full path to this section within the <see cref="IConfiguration"/>.
    /// </summary>
    string Path { get; }

    /// <summary>
    /// Gets or sets the section value.
    /// </summary>
    string Value { get; set; }
}

IConfigurationBuilder

該介面主要用於建立IConfigurationProvider，其派生類包括Microsoft.Extensions.Configuration.ConfigurationBuilder。其成員包括

兩個只讀屬性：

• Properties：獲取可用於在IConfigurationBuilder之間共享資料的鍵/值集合
• Sources：該屬性用於快取不同的配置源，以用於相對應的Provider的建立

兩個方法：

• Add(IConfigurationSource source)：新增IConfigurationSource，並新增到屬性中Sources中
• Build()：該方法遍歷Sources屬性，並呼叫IConfigurationSource的Build()方法，通過獲取Provider集合，最終建立IConfigurationRoot物件

ConfigurationBuilder原始碼如下

/// <summary>
    /// Used to build key/value based configuration settings for use in an application.
    /// </summary>
    public class ConfigurationBuilder : IConfigurationBuilder
    {
        /// <summary>
        /// Returns the sources used to obtain configuration values.
        /// </summary>
        public IList<IConfigurationSource> Sources { get; } = new List<IConfigurationSource>();

        /// <summary>
        /// Gets a key/value collection that can be used to share data between the <see cref="IConfigurationBuilder"/>
        /// and the registered <see cref="IConfigurationProvider"/>s.
        /// </summary>
        public IDictionary<string, object> Properties { get; } = new Dictionary<string, object>();

        /// <summary>
        /// Adds a new configuration source.
        /// </summary>
        /// <param name="source">The configuration source to add.</param>
        /// <returns>The same <see cref="IConfigurationBuilder"/>.</returns>
        public IConfigurationBuilder Add(IConfigurationSource source)
        {
            if (source == null)
            {
                throw new ArgumentNullException(nameof(source));
            }

            Sources.Add(source);
            return this;
        }

        /// <summary>
        /// Builds an <see cref="IConfiguration"/> with keys and values from the set of providers registered in
        /// <see cref="Sources"/>.
        /// </summary>
        /// <returns>An <see cref="IConfigurationRoot"/> with keys and values from the registered providers.</returns>
        public IConfigurationRoot Build()
        {
            var providers = new List<IConfigurationProvider>();
            foreach (var source in Sources)
            {
                var provider = source.Build(this);
                providers.Add(provider);
            }
            return new ConfigurationRoot(providers);
        }
    }

此處令人感慨頗多，我們最終呼叫 ConfigurationRoot 的建構函式，究其原因是Provider提供了統一的資料訪問方式，不管是基於何種型別的Provider，我們都可以呼叫其Load()方法載入配置項。此外，IConfigurationBuilder本身有很多的擴充套件方法來註冊資料來源，比如AddJsonFile()擴充套件方法。我們來看一下，我們常見的寫法，

var builder = new ConfigurationBuilder()

            .SetBasePath(env.ContentRootPath)

            .AddJsonFile("appsettings1.json", false, true)

            .AddJsonFile("appsettings2.json", false, true);

Configuration = builder.Build();

IConfigurationSource

該介面表示應用程式配置的鍵值對。其派生類包括Microsoft.Extensions.Configuration.ChainedConfigurationSource、Microsoft.Extensions.Configuration.Memory.MemoryConfigurationSource。另外該派生類還會在檔案類配置場景下依賴Microsoft.Extensions.Configuration.FileExtensions元件。

它是所有配置源的抽象表示，包括JSON、XML、INI、環境變數等等。通過上文我們也知道了，IConfigurationBuilder會註冊多個IConfigurationSource例項。它只有一個方法，就是Build()方法，並返回IConfigurationProvider，由此可見，IConfigurationProvider的建立依賴於IConfigurationSource，這也是一一對應的關係。所有不同的源最終都會轉化成統一的鍵值對錶示。

以下為

/// <summary>
/// Represents a source of configuration key/values for an application.
/// </summary>
public interface IConfigurationSource
{
    /// <summary>
    /// Builds the <see cref="IConfigurationProvider"/> for this source.
    /// </summary>
    /// <param name="builder">The <see cref="IConfigurationBuilder"/>.</param>
    /// <returns>An <see cref="IConfigurationProvider"/></returns>
    IConfigurationProvider Build(IConfigurationBuilder builder);
}

以下是MemoryConfigurationSource的原始碼

/// <summary>
/// Represents in-memory data as an <see cref="IConfigurationSource"/>.
/// </summary>
public class MemoryConfigurationSource : IConfigurationSource
{
    /// <summary>
    /// The initial key value configuration pairs.
    /// </summary>
    public IEnumerable<KeyValuePair<string, string>> InitialData { get; set; }

    /// <summary>
    /// Builds the <see cref="MemoryConfigurationProvider"/> for this source.
    /// </summary>
    /// <param name="builder">The <see cref="IConfigurationBuilder"/>.</param>
    /// <returns>A <see cref="MemoryConfigurationProvider"/></returns>
    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new MemoryConfigurationProvider(this);
    }
}

IConfigurationProvider

通過上文的介紹，我們可以知道IConfigurationProvider是統一的對外介面，對使用者提供配置的查詢、重新載入等功能。其派生類包括Microsoft.Extensions.Configuration.ConfigurationProvider、Microsoft.Extensions.Configuration.ChainedConfigurationProvider、Microsoft.Extensions.Configuration.Memory.MemoryConfigurationProvider。另外該派生類還會在檔案類配置場景下依賴Microsoft.Extensions.Configuration.FileExtensions元件。

以下是Microsoft.Extensions.Configuration.ConfigurationProvider的原始碼：

/// <summary>
/// Base helper class for implementing an <see cref="IConfigurationProvider"/>
/// </summary>
public abstract class ConfigurationProvider : IConfigurationProvider
{
    private ConfigurationReloadToken _reloadToken = new ConfigurationReloadToken();

    /// <summary>
    /// Initializes a new <see cref="IConfigurationProvider"/>
    /// </summary>
    protected ConfigurationProvider()
    {
        Data = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
    }

    /// <summary>
    /// The configuration key value pairs for this provider.
    /// </summary>
    protected IDictionary<string, string> Data { get; set; }

    /// <summary>
    /// Attempts to find a value with the given key, returns true if one is found, false otherwise.
    /// </summary>
    /// <param name="key">The key to lookup.</param>
    /// <param name="value">The value found at key if one is found.</param>
    /// <returns>True if key has a value, false otherwise.</returns>
    public virtual bool TryGet(string key, out string value)
        => Data.TryGetValue(key, out value);

    /// <summary>
    /// Sets a value for a given key.
    /// </summary>
    /// <param name="key">The configuration key to set.</param>
    /// <param name="value">The value to set.</param>
    public virtual void Set(string key, string value)
        => Data[key] = value;

    /// <summary>
    /// Loads (or reloads) the data for this provider.
    /// </summary>
    public virtual void Load()
    { }

    /// <summary>
    /// Returns the list of keys that this provider has.
    /// </summary>
    /// <param name="earlierKeys">The earlier keys that other providers contain.</param>
    /// <param name="parentPath">The path for the parent IConfiguration.</param>
    /// <returns>The list of keys for this provider.</returns>
    public virtual IEnumerable<string> GetChildKeys(
        IEnumerable<string> earlierKeys,
        string parentPath)
    {
        var prefix = parentPath == null ? string.Empty : parentPath + ConfigurationPath.KeyDelimiter;

        return Data
            .Where(kv => kv.Key.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
            .Select(kv => Segment(kv.Key, prefix.Length))
            .Concat(earlierKeys)
            .OrderBy(k => k, ConfigurationKeyComparer.Instance);
    }

    private static string Segment(string key, int prefixLength)
    {
        var indexOf = key.IndexOf(ConfigurationPath.KeyDelimiter, prefixLength, StringComparison.OrdinalIgnoreCase);
        return indexOf < 0 ? key.Substring(prefixLength) : key.Substring(prefixLength, indexOf - prefixLength);
    }

    /// <summary>
    /// Returns a <see cref="IChangeToken"/> that can be used to listen when this provider is reloaded.
    /// </summary>
    /// <returns></returns>
    public IChangeToken GetReloadToken()
    {
        return _reloadToken;
    }

    /// <summary>
    /// Triggers the reload change token and creates a new one.
    /// </summary>
    protected void OnReload()
    {
        var previousToken = Interlocked.Exchange(ref _reloadToken, new ConfigurationReloadToken());
        previousToken.OnReload();
    }

    /// <summary>
    /// Generates a string representing this provider name and relevant details.
    /// </summary>
    /// <returns> The configuration name. </returns>
    public override string ToString() => $"{GetType().Name}";
}

通過原始碼，我們可以知道ConfigurationProvider以字典型別快取了多個Provider物件，有需要的時候，從記憶體中獲取即可，配置的載入通過Load()方法實現，在ConfigurationRoot裡我們介紹了其Reload，並且說明其方法是在迴圈呼叫ConfigurationProvider的Load方法，但是此處只提供了一個虛方法，其目的是要交給其他具體的Provider，比如環境變數、JSON、XML等，這些具體的Provider可以從相應的配置源中獲取配置資訊。所有的子節點KEY通過GetChildKeys方法實現，其重新載入方式通過ConfigurationReloadToken例項完成。

另外需要說明一下，在ConfigurationProvider建構函式裡，對字典進行了初始化，並同時設定了字典Key不受大小寫限制，這是一個需要注意的細節。

Configuration元件結構

通過檢視.NET配置功能的原始碼，所有依賴均基於Microsoft.Extensions.Configuration.Abstractions，在其上有一層實現，即Microsoft.Extensions.Configuration，其內部也多數是抽象實現，並提供了多個虛方法交給其派生元件，比如環境變數、命令列引數、各種檔案型配置等，當然各種檔案型配置還要依賴Microsoft.Extensions.Configuration.FileExtensions元件。

以下是.NET Core 3.0預覽版裡的Configuration各個元件的結構圖：