ASP.NET Core 7.0中的配置项Configuration(一)

本文章翻译自微软官方文档：https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-7.0

ASP.NET Core中的配置项Configuration是通过使用一个或多个configuration providers来实现,configuration providers可以从多种不同的配置源中读取键值对形式的配置数据，配置源可以是以下形式:

Settings files(配置文件),比如appsettings.json
Environment variables(环境变量)
Azure Key Vault
Azure App Configuration
Command-line arguments(命令行参数)
Custom providers
Directory files
In-memory .NET objects
本篇文章只介绍ASP.NET Core中的配置,更多相关配置信息请参考 .NET Configuration

应用配置及宿主(host)配置

ASP.NET Core配置并启动host,host负责应用的启动及生命周期管理。ASP.NET Core模板会创建一个包含host的 WebApplicationBuilder。虽然一些配置可以在host及应用配置中完成,但通常只有host必须的配置才会在host中完成。

在以下部分应用配置将会是重点并会详细介绍。本文中host配置会在应用配置下面描述。

默认应用配置源

通过dotnet new命令或者Visual Studio创建的ASP.NET Core web应用会生成以下代码：

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder初始化一个带有默认配置的WebApplicationBuilder类的新实例,已初始化的WebApplicationBuilder会对应用按以下顺序从高到低优先级提供默认配置：

Command-line arguments using the Command-line configuration provider.(命令行参数)
Non-prefixed environment variables using the Non-prefixed environment variables configuration provider.(无前缀环境变量)
User secrets when the app runs in the Development environment.(用户机密)
appsettings.{Environment}.json using the JSON configuration provider. For example, appsettings.Production.json and appsettings.Development.json.(带环境变量的配置文件)
appsettings.json using the JSON configuration provider.(默认配置文件)
A fallback to the host configuration described in the next section.

默认host配置源

以下按优先级从高到低列出了WebApplicationBuilder的默认host配置源：

Command-line arguments using the Command-line configuration provider.(命令行参数)
DOTNET_-prefixed environment variables using the Environment variables configuration provider.(DOTNET_前缀环境变量)
ASPNETCORE_-prefixed environment variables using the Environment variables configuration provider.(ASPNETCORE_前缀环境变量)

对于.NET Generic Host 和 Web Host，默认host配置源从高到低优先级如下:

ASPNETCORE_-prefixed environment variables using the Environment variables configuration provider.(ASPNETCORE_前缀环境变量)
Command-line arguments using the Command-line configuration provider.(命令行参数)
DOTNET_-prefixed environment variables using the Environment variables configuration provider.(DOTNET_前缀环境变量)

Host变量

以下变量在初始化host builders初期被锁上并且不会被应用配置影响:

Application name(应用名称)
Environment name, for example Development, Production, and Staging(环境名称,比如Development, Production及 Staging)
Content root
Web root
Whether to scan for hosting startup assemblies and which assemblies to scan for.
Variables read by app and library code from HostBuilderContext.Configuration in IHostBuilder.ConfigureAppConfiguration callbacks.

所有其他host config 是从application config读取以替换host config。

urls是许多非引导设置的常见主机设置之一。和其他未在以上列表列出的主机设置一样，URLS是在后续的application config中读取。Host config是application config的备份，所以URLS可以在Host config中设置，但是会被像appsettings.json的 application config配置源覆盖。

Application configuration providers

以下代码展示了可用的configuration providers被添加的顺序:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

providers在模板生成的应用中被添加的顺序正好与上面默认配置源优先级顺序相反。比如 JSON configuration provider 是在Command-line configuration provider之前被添加。

后添加的Configuration providers有更高的优先级并覆盖前面的设置。比如，如果MyKey同时在appsettings.json和环境变量中设置，环境变量中的设置将起效果。使用默认的configuration providers，Command-line configuration provider将覆盖所有其他providers.

appsettings.json

有以下appsettings.json文件：

{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  },
  "MyKey": "My appsettings.json Value",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

以下代码显示以上配置文件的设置：

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

默认的JsonConfigurationProvider由以下顺序加载配置：

appsettings.json
appsettings.{Environment}.json:比如appsettings.Production.json和appsettings.Development.json配置文件。

appsettings.{Environment}.json文件的配置项将会覆盖appsettings.json文件的配置项。
比如，一般地：

在开发环境，appsettings.Development.json文件的配置将会覆盖appsettings.json文件的相同配置项。
在生产环境，appsettings.Production.json文件的配置项将会覆盖appsettings.json文件的相同配置项。

还有下篇 ASP.NET Core中的配置项Configuration(二)

ASP.NET Core 7.0中的配置项Configuration(一)