翻译自 https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-5.0

ASP.NET Core 中的配置使用一个或者多个配置提供程(configuration providers)序实现。配置提供程序从多种键值对中的配置源中读取配置数据：

设置文件，例如 appsetting.json
环境变量
Azure 键库
Azure App 配置
命令行参数
自定义提供器，安装的或者创建的
目录文件
内存中的 .NET 对象

本话题提供 ASP.NET Core 中关于配置的信息。更多关于在控制台应用程序中使用配置的信息，查看 .NET Configuration.

默认配置

使用 dotnet new 或者 Visual Studio 创建的 ASP.NET Core web 应用程序生成以下代码：

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder 按照以下顺序为应用程序提供默认配置：

ChainedConfigurationProvider：添加一个现存的 IConfiguration 作为一个源。在一个默认配置例子中，添加主机（host）配置并且设置它作为第一个应用程序配置的源。
appsettings.json 使用 JSON 配置提供器（JSON configuration provider）。
appsetttings.Environment.json 使用 JSON 配置提供器（JSON configuration provider）。例如,appsettings.Production.json 和 appsettings.Developments.json。
App secrets，当应用程序运行在开发 (Development) 环境中。
环境变量使用 Environment Variables configuration provider。
命令行参数使用 Command-line configuration provider。

后添加的配置提供器会覆盖先前添加的键值设置。例如，如果 MyKey 同事在 appsettings.json 和环境变量中设置，环境变量的值将会被使用。如果使用默认的配置提供器，命令行配置提供器(Command-line configuration provider) 将会覆盖所有的提供器。

关于 CreateDefaultBuilder 的更多信息，查看 Default builder settings。

下面的代码展示了使能的配置提供器的添加顺序：

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);
    }
}

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": "*"
}

示例 (sample download) 中的代码展示了几个上面的配置设置：

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 按照以下顺序加载配置：

1. appsettings.json

2. appsettings.Environment.json：例如，appsettings.Production.json 和 appsettings.Development.json 文件。文件的环境版本基于 IHostingEnvironment.EnvironmentName，更多信息，查看 Use multiple environments in ASP.NET Core.

appsettings.Environment.json 中的值会覆盖 appsettings.json 中的值。例如，默认的：

在开发环境中，appsettings.Development.json 配置会覆盖 appsettings.json 中存在的值
在生产环境中，appsettings.Production.json 的配置会覆盖 appsettings.json 中存在的值，例如，当部署应用程序到 Azure 上的时候。

使用选项模型绑定继承配置数据

读取相关配置值的推荐方式是使用选项模型 (options pattern)。例如，读取下面的配置值：

"Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

创建 PositionOptions 类：

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; }
    public string Name { get; set; }
}

一个选项类：

必须是带有公共无参数的构造方法的非抽象类
所有公共的可读写的属性类型要被绑定
字段没有绑定。在前面的代码中，Position 没有绑定。使用 Position 属性，因此字符串 "Position" 就不用在绑定类到一个配置提供器的时候硬编码在应用程序中

下面的代码：

调用 ConfigurationBinder.Bind 绑定 PositionOptions 类到 Position 区域
展示 Position 配置数据

public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

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

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

在上面的代码中，默认的，在应用程序启动后对于 JSON 配置文件的改变也会被读取到。

ConfigurationBinder.Get<T> 绑定和返回指定的类型。ConfigurationBinder.Get<T> 可能比使用 ConfigurationBinder.Bind 更方便。下面的代码展示了如何使用 ConfigurationBinder.Get<T> 使用 PositionOptions 类：

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions positionOptions { get; private set; }

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

    public ContentResult OnGet()
    {
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

默认的，上面的代码会读取到在应用程序启动后对于 JSON 配置文件的更改。

使用 options patter 的一种方法是绑定 Position 区域并且添加到依赖注入服务容器 (dependency injection service container) 中。下面的代码中，PositionOptions 在 Configure 中被添加到服务容器中，并绑定到配置：

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

使用了上面的代码，下面的代码读取 position options:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

上面的代码在应用程序启动后不会读取到对 JSON 配置文件的更改。如果要读取应用程序启动后的更改，可以使用 IOptionsSnapshot。

使用默认（default）的配置，appsettings.json 和 appsettings.Environment.json 文件使能了 reloadOnChange: true 。在应用程序启动后对 appsettings.json 和 appsettings.Environment.json 的更改会被 JSON configuration provider 读取到。

查看本文档中 JSON configuration provider 关于添加更多 JSON 配置文件的信息。

合并服务集合

考虑下面的 ConfigureServices 方法，其中注册服务和配置选项：

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(
        Configuration.GetSection(PositionOptions.Position));
    services.Configure<ColorOptions>(
        Configuration.GetSection(ColorOptions.Color));

    services.AddScoped<IMyDependency, MyDependency>();
    services.AddScoped<IMyDependency2, MyDependency2>();

    services.AddRazorPages();
}

相关的一组的注册可以被移动到扩展方法中去注册服务。例如，配置服务被添加到下面的类中：

using ConfigSample.Options;
using Microsoft.Extensions.Configuration;

namespace Microsoft.Extensions.DependencyInjection
{
    public static class MyConfigServiceCollectionExtensions
    {
        public static IServiceCollection AddConfig(
             this IServiceCollection services, IConfiguration config)
        {
            services.Configure<PositionOptions>(
                config.GetSection(PositionOptions.Position));
            services.Configure<ColorOptions>(
                config.GetSection(ColorOptions.Color));

            return services;
        }
    }
}

其余的服务在一个相似的类中被注册。下面的 ConfigureServices 方法使用的新的扩展方法注册服务：

public void ConfigureServices(IServiceCollection services)
{
    services.AddConfig(Configuration)
            .AddMyDependencyGroup();

    services.AddRazorPages();
}

备注：每一个 services.Add{GROUP_NAME} 扩展方法添加和潜在的会配置服务。例如，AddControllersWithViews 添加带有视图的 MVC 控制器的服务，AddRazorPages 添加带有 Razor Pages 的服务。我们推荐应用程序遵守命名的约定。把扩展方法统一放到命名空间 Microsoft.Extensions.DependencyInjection 中去封装一组服务的注册。

安全和用户秘密

数据配置指导：

永远不要把密码或者其他敏感数据使用配置提供器保存在代码中或者保存在文本配置文件中。在开发过程中，可以使用 Secret Manager 工具保存秘密数据
不要在开发环境或者测试环境中使用生产环境的秘密数据
在工程外部指定秘密数据，以防被意外的提交到源代码仓库中

默认的，用户秘密配置源是在 JSON 配置源之后注册的。因此，用户秘密的键值会生效，而不是 appsettings.json 和 appsettings.Environment.json 中的键值。

更多关于存储密码或者其他敏感数据的信息：

Use multiple environments in ASP.NET Core
Safe storage of app secrets in development in ASP.NET Core：包含关于使用环境变量存储敏感数据的建议。秘密管理工具使用 File configuration provider 在本地系统上保存用户密码在一个 JSON 文件

Azure Key Vault 为 ASP.NET Core 应用程序安全的存储应用程序的秘密。更多信息查看 Azure Key Vault Configuration Provider in ASP.NET Core。

环境变量

使用默认的配置，EnvironmentVariablesConfigurationProvider 在读取 appsettings.json，appsettings.Environment.json，和 user secrets 之后从环境变量加载键值对。因此，从环境变量读取到的键值会覆盖从 appsettings.json, appsettings.Environment.json 和 user secrets 中读取到的值。

: 分隔符在所有平台上对于环境便令分级键都是不工作的。__ 双下换线：

所有平台都支持。例如， Bash 不支持 : 分隔符，但是支持 __
会自动的被一个 : 替换

下面的设置命令：

在 Windows 上设置前面示例(preceding exampl)中的环境键值和值
使用示例程序(sample download)测试设置。dotnet run 命令必须在工程目录中运行

set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

上面的环境变量设置：

仅仅在设置他们的命令行窗口中启动的进程中
不会被使用 Visual Studio 启动的浏览器读取

下面的 setx 命令可以被用来在 Windows 上设置环境键和值。不同于 set，setx 是持久化的。/M 在系统环境设置变量。如果没有使用 /M 开关，一个用户的环境变量会被设置。

setx MyKey "My key from setx Environment" /M
setx Position__Title Setx_Environment_Editor /M
setx Position__Name Environment_Rick /M

为了测试上面的命令会覆盖 appsettings.json 和 asppsettings.Environment.json 的配置，需要做以下操作：

使用 Visual Studio: 退出和重启 Visual Studio
使用命令行：启动一个新的命令窗口，输入 dotnet run

调用 AddEnvironmentVariables，使用一个字符串指定环境变量的前缀：

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

在上面的代码中:

config.AddEnvironmentVariables(prefix: "MyCustomPrefix_") 在默认配置提供器 (default configuration providers) 之后添加。关于配置提供器顺序的示例，查看 JSON 配置提供器 (JSON configuration provider)。
使用 MyCustomPrefix_ 前缀设置的环境变量覆盖了默认配置提供器 (default configuration providers)。这包括没有前缀的环境变量。

当配置键值对被读取的时候，前缀会被去除。

下面的命令测试自定义前缀：

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

默认配置 (default configuration) 加载带有前缀为 DOTNET_ 和 ASPNETCORE_ 的环境变量和命令行参数。DOTNET_ 和 ASPNETCORE_ 前缀被 ASP.NET Core 用来配置主机和应用程序配置 (host and app configuration)，不能用来作为用户配置。更多关于主机和应用程序的配置，查看 .NET Generic Host。

关于 Azure App Service，在设置 (Settings) > 配置 (Configuration) 页面选择新建应用程序设置 (New application setting)。Azure 应用程序服务设置：

在休息是加密，并通过加密通道传输
暴露为环境变量

查看 Connection string prefixes 了解关于 Azure 数据库连接字符串的信息。

环境变量命名

环境变量的命名反映了 appsettings.json 文件的结构。层级中的每一个元素使用双下划线（推荐的）或者冒号分割开来。当一个元素的结构包含一个数组的时候，数组的索引应该被当做是当前路径中的一个额外的元素名称。考虑下面的 appsettings.json 文件和它在环境变量中等价的值。

appsettings.json

{
    "SmtpServer": "smtp.example.com",
    "Logging": [
        {
            "Name": "ToEmail",
            "Level": "Critical",
            "Args": {
                "FromAddress": "[email protected]",
                "ToAddress": "[email protected]"
            }
        },
        {
            "Name": "ToConsole",
            "Level": "Information"
        }
    ]
}

环境变量 (environment variables)

setx SmtpServer=smtp.example.com
setx Logging__0__Name=ToEmail
setx Logging__0__Level=Critical
setx Logging__0__Args__FromAddress=[email protected]
setx Logging__0__Args__ToAddress=[email protected]
setx Logging__1__Name=ToConsole
setx Logging__1__Level=Information

生成的 launchSettings.json 文件中环境变量的设置

在 launchSettings.json 中设置的环境变量会覆盖那些在系统环境中设置的值。例如，ASP.NET Core web 模板会生成一个 lauchSettings.json 文件，文件中设置了

endpoint 配置：

"applicationUrl": "https://localhost:5001;http://localhost:5000"

对 applicationUrl 的配置设置环境变量 ASPNETCORE_URLS 并覆盖环境中的值。

Escape environment variables on Linux

在 linux 上，URL 环境变量的值必须被 escape 后系统才能够解析它。使用 linux systemd-escape 工具生成 http:--localhost:5001

groot@terminus:~$ systemd-escape http://localhost:5001
http:--localhost:5001

显示环境变量

下面的代码在应用程序启动的时候输出显示了环境变量和对应的值，在调试环境设置的时候非常有用：

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var config = host.Services.GetRequiredService<IConfiguration>();

    foreach (var c in config.AsEnumerable())
    {
        Console.WriteLine(c.Key + " = " + c.Value);
    }
    host.Run();
}

命令行

使用默认的配置，CommandLineConfigurationProvider 在下列配置源之后从命令行参数键值对中加载配置：

appsettings.json 和 appsettings.Environment.json 文件
开发环境中的 App secrets
环境变量

默认的，在命令行中配置的值会覆盖其它所有配置提供的值。

命令行参数

下面的命令使用 = 设置键和值:

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

下面的命令使用 / 设置键值：

dotnet run /MyKey "Using /" /Position:Title=Cmd_ /Position:Name=Cmd_Rick

下面的命令使用 -- 设置键值：

dotnet run --MyKey "Using --" --Position:Title=Cmd-- --Position:Name=Cmd--Rick

键值：

必须紧跟 = ，或当值在一个空格后面的时候，键必须有个 -- 或者 / 前缀
当使用 = 的时候，值不是必须要有的，例如 MySetting=

在相同的命令行中，不要把使用 = 的键值对和使用空格的键值对的命令行参数混淆。

转换映射

切换映射允许键名替换逻辑。可以给 AddCommandLine 方法提供一个切换替换的字典。

当切换映射字典被用到的时候，字典被用来检查匹配命令行参数提供的键。日过命令行的键在字典中被找到，字典中的值就会被传回用来设置应用程序配置的键值对。切换映射要求任何的命令行键使用一个单独的破折号作为前缀。

切换映射字典键的规则：

切换必须以 - 或者 -- 开头
切换映射字典不能包含重复的键

使用一个切换映射字典，需要把它传递给 AddCommandLine 方法：

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

下面的代码展示了被替换的键的值：

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

下面的命令用来测试键替换：

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

对于使用切换映射的应用程序，调用 CreateDefaultBuilder 不应该传递参数。CreateDefaultBuilder 方法的 AddCommandLine 的调用不包括映射切换，没有方法可以传递切换映射的字典给 CreateDefaultBuilder。解决方法是允许 ConfigurationBuilder 方法的 AddCommandLine 同时处理参数和切换映射字典而不是传递参数给 CreateDefaultBuilder。

分层配置数据

配置 API 通过使用在配置键中的分界符扁平化分层数据来读取配置数据。

示例程序 (sample download) 包含下面的 appsettings.json 文件：

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

下面示例 (sample download) 中的代码展示了一些配置设置：

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}");
    }
}

读取分层配置数据的首选方式是使用选项模型。更多信息，查看本文档中的绑定分层配置数据 (Bind hierarchical configuration data)。

GetSection 和 GetChildren 方法可以用来分离配置数据中的分区和分区中的子部分。这些方法在之后的 GetSection, GetChildren, and Exists 中会描述到。

配置的键和值

配置的键：

不区分大小写。例如 ConnectionString 和 connectionstring 被认为是等价的键
如果一个键和值在多个配置提供器中被设置，最后一个提供器的值将会被使用。更多信息，查看默认配置 (Default configuration)
分层键
- 在配置 API 内部，一个冒号分隔符 (:) 在所有平台都能工作
- 在环境变量中，一个冒号分隔符可能不会在所有平台上工作。双下划线 (__) 被所有平台支持，并且会被自动的转换为一个冒号 (:)
- 在 Azure 键仓库中，分层的键使用 -- 作为一个分隔符。当秘密数据被加载到应用程序配置的时候，Azure Key Vault configuration provider 自动使用一个冒号 (:) 替换 (--)。
ConfigurationBinder 支持绑定数组到在配置键中使用数组索引的对象。数组绑定在 Bind an array to a class 部分描述。

配置值：

是字符串
Null 值不能存储在配置中或者绑定到对象

配置提供器

下面的表格中显示了 ASP.NET Core 应用程序中可以使用的配置提供器

配置源的读取的顺序按照它们的配置提供器被指定的顺序。在代码中对配置提供器排序来满足应用程序要求的配置源的顺序。

一个典型的配置提供器的顺序是：

appsettings.json
appsettings.Environment.json
User secrets
使用 Environment Variables configuration provider 的环境变量
使用 Command-line configuration provider 的命令行参数

一个常用的实践是在一系列的配置提供器的最后添加命令行配置提供器，用来覆盖其它提供器的配置设置

上面的提供器的顺序在默认配置 (default configuration) 中使用。

连接字符串前缀

配置 API 对于四种连接字符串环境变量有特殊的处理规则。这些连接字符串会根据应用程序环境解析来配置 Azure 连接字符串。下面表格中的带有前缀的环境变量在应用程序使用默认配置（default configuration）或者没有前缀没有应用到 AddEnvironmentVariables 的情况下会被加载到应用程序中。

当一个环境变量被发现并且使用表格中四种前缀的任一种被加载到配置中的时候：

通过移除环境变量的前缀创建配置的键，添加一个配置键的区域（ConnectionStrings）
一个新的配置的键值对被创建，这个键值对代表了数据库连接提供器 (CUSTOMCONNSTR_ 除外，由于没有固定的提供器)

文件配置提供器

FileConfigurationProvider 是从文件系统加载配置的基类。下面的配置提供器都从 FileConfigurationProvider 类继承而来。

INI configuration provider
JSON configuration provider
XML configuration provider

INI 配置提供器

IniConfigurationProvider 在运行时从 INI 文件中加载键值对的配置。

下面的代码清空了所有配置提供器，添加了一些配置提供器：

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

ASP.NET Core 托管和部署

翻译 - ASP.NET Core 基本知识 - 配置（Configuration）