C# 如何配置和读取appsettings.json - .NET Core配置系统详解

来源：这里教程网时间：2026-02-21 17:32:59 作者：

在 .NET Core 及后续版本（.NET 5+）中，

appsettings.json

是默认推荐的配置源，它通过统一的

IConfiguration

接口被读取和管理。配置不是“手动解析 JSON”，而是由 配置提供程序（Configuration Providers） 自动加载、合并、分层，并支持环境变量、命令行参数等多源叠加。

配置文件结构与约定

appsettings.json

是标准 JSON 格式，支持嵌套对象和数组。框架按层级自动映射为冒号分隔的键（如

"Logging:LogLevel:Default"

）。常见结构如下：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=.;Database=MyApp;Trusted_Connection=true;"
  },
  "AppSettings": {
    "SiteName": "My Site",
    "PageSize": 20
  }
}

注意：文件名不重要，但必须在

Program.cs

中显式添加对应提供程序；

appsettings.Development.json

等环境变体需配合

IWebHostEnvironment.EnvironmentName

自动加载。

在 Program.cs 中注册配置源

.NET 6+ 使用最小托管模型，配置构建在

Host.CreateDefaultBuilder()

或手动

Host.CreateApplicationBuilder()

中完成。默认已包含

appsettings.json

和环境变体，但可自定义：

确保
appsettings.json
的 “复制到输出目录”属性设为“始终复制”（否则运行时找不到）若需额外 JSON 文件（如
secrets.json
），用
builder.Configuration.AddJsonFile("custom.json", optional: true)
环境变量优先级高于 JSON，可用于覆盖敏感值（如连接字符串）

示例（.NET 7+）：

var builder = Host.CreateApplicationBuilder(args);
// 默认已加载 appsettings.json + appsettings.{Environment}.json
// 如需额外文件：
builder.Configuration.AddJsonFile("appsettings.extra.json", optional: true);

读取配置的三种常用方式

1. 直接通过

IConfiguration

读取（适合简单值）
注入

IConfiguration

，用索引器或

GetValue<t></t>

获取：

var connectionString = configuration["ConnectionStrings:DefaultConnection"];
var pageSize = configuration.GetValue("AppSettings:PageSize");
var siteName = configuration.GetValue("AppSettings:SiteName");

2. 绑定到强类型对象（推荐用于结构化配置）
定义 POCO 类（字段/属性名需与 JSON 键路径匹配）：

public class AppSettings
{
public string SiteName { get; set; } = string.Empty;
public int PageSize { get; set; }
}

在

Program.cs

注册绑定：

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

使用时注入

IOptions<appsettings></appsettings>

或

IOptionsSnapshot<appsettings></appsettings>

（后者支持重载）：

var settings = options.Value.SiteName; // 或 options.Value.PageSize

3. 使用

IOptionsMonitor

响应配置热重载（如开发时修改 JSON 实时生效）
适用于需要监听变更的场景（如日志级别动态调整）：

builder.Services.Configure(builder.Configuration.GetSection("Logging"));
// 在服务中注入 IOptionsMonitor 即可订阅 OnChange

关键细节与避坑提示

GetSection("AppSettings")
返回的是子配置节，不是深拷贝，仍依赖原始
IConfiguration
的生命周期配置键名**不区分大小写**（JSON 本身是小写，但
configuration["AppSettings:SiteName"]
和
["appsettings:sitename"]
都有效）数组无法直接绑定到
List<t></t>
，需用
Get<t>()</t>
或
GetChildren()
手动遍历若配置缺失，
GetValue<t>()</t>
返回
default(T)
，
GetSection().Get<t>()</t>
返回
null
（引用类型）或抛异常（值类型未设默认值时）生产环境慎用
appsettings.json
存密钥——改用 Azure Key Vault、User Secrets（仅开发）或环境变量

基本上就这些。配置系统设计得足够灵活，但核心逻辑很清晰：加载 → 合并 → 绑定 → 使用。不需要手写 JSON 解析器，也不必操心线程安全——