C# 读取 appsettings.json 配置项方法

文章导读
C# 读取 appsettings.json 的目标通常不是“能不能读”,而是让配置在控制台、ASP.NET Core、类库或单元测试里都能以可控方式取到,并且缺失项、类型错误、环境切换时不出隐性故障。先确认项目是否已经引入 Microsoft.Extensions.Configuration 系列包、配置文件是否被复制到输出目录、以及你是要读单个值还是绑定一个强类型对象,这三点决定了后续写法。
📋 目录
  1. A 先确认当前场景和目标
  2. B 按这个顺序处理
  3. C 改完后怎么验证
  4. D 容易忽略的边界
A A

C# 读取 appsettings.json 的目标通常不是“能不能读”,而是让配置在控制台、ASP.NET Core、类库或单元测试里都能以可控方式取到,并且缺失项、类型错误、环境切换时不出隐性故障。先确认项目是否已经引入 Microsoft.Extensions.Configuration 系列包、配置文件是否被复制到输出目录、以及你是要读单个值还是绑定一个强类型对象,这三点决定了后续写法。

在 .NET 项目里读取 appsettings.json,通用做法是先用 ConfigurationBuilder 加载 JSON 文件(可选按环境叠加 appsettings.{Environment}.json),再通过索引器读单值或用 GetSection/Bind 绑定强类型对象;ASP.NET Core 模板已内置该流程,控制台或类库需自行加包并设置文件属性。判断是否可用,看能否读到值、缺失键是否按预期回退、以及发布后输出目录里是否有该配置文件。不适用场景是高度动态、需要热更新的配置,那类需求要额外接 reloadOnChange 或配置中心,不能只依赖一次加载。

先确认当前场景和目标

先分清三种常见场景,它们的起点不同:ASP.NET Core Web 项目在 Program.cs 里已经由 WebApplication.CreateBuilder 建好配置,通常直接用 builder.Configuration 或注入 IConfiguration 即可;控制台程序和类库没有这层封装,需要自己 new ConfigurationBuilder;单元测试里往往希望不读真实文件,而是用内存集合或直接构造配置对象。

需要先确认的信息有三类。第一是包引用:Microsoft.Extensions.Configuration、Microsoft.Extensions.Configuration.Json、Microsoft.Extensions.Configuration.Binder 是否已安装,绑定强类型时没有 Binder 包会编译不过。第二是文件属性:appsettings.json 的“复制到输出目录”通常是“如果较新则复制”,如果不设置,发布或运行到 bin 目录时会找不到文件。第三是目标形态:只读一个连接字符串,和需要把整个节点映射成对象,写法不一样,后者更容易在类型转换上出问题。

判断条件可以简化成一句:如果项目已经是 ASP.NET Core 模板,优先用内置配置;如果是控制台或类库,就补包并显式指定 basePath;如果希望不同环境不同值,就把环境名纳入加载顺序,而不是在代码里写 if 判断。

按这个顺序处理

第一步是把配置文件的加载固定下来。下面的片段是控制台或类库的通用骨架,BasePath 指向程序运行目录,文件名和环境文件按需替换;放进 Program.cs 的 Main 或启动方法里执行即可。

using Microsoft.Extensions.Configuration;

var env = Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT") ?? "Production";

var configuration = new ConfigurationBuilder()
    .SetBasePath(AppContext.BaseDirectory)
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddJsonFile($"appsettings.{env}.json", optional: true, reloadOnChange: true)
    .AddEnvironmentVariables()
    .Build();

optional 的取值需要按业务判断:主文件一般设为 false,缺失时尽早暴露问题;环境文件设为 true,避免本地调试时因没有对应文件而报错。reloadOnChange 只是提供变更通知能力,实际能否生效还取决于宿主和消费方式,不要默认它一定即时生效。

C# 读取 appsettings.json 配置项方法

第二步是读取方式的选择。单个值用索引器,冒号表示层级,键不存在时返回 null,需要自己决定是抛异常还是给默认值。

// 读单值
string? conn = configuration["ConnectionStrings:Default"];
string host = configuration["Smtp:Host"] ?? "localhost";

// 读节并绑定强类型
public class SmtpOptions
{
    public string Host { get; set; } = "";
    public int Port { get; set; } = 25;
}

var smtp = configuration.GetSection("Smtp").Get<SmtpOptions>();
// 或
var smtp2 = new SmtpOptions();
configuration.GetSection("Smtp").Bind(smtp2);

对应的 appsettings.json 结构需要与键名一致,大小写通常不敏感,但建议保持一致以免混淆:

{
  "ConnectionStrings": {
    "Default": "Server=.;Database=Demo;Trusted_Connection=True;"
  },
  "Smtp": {
    "Host": "smtp.example.com",
    "Port": 587
  }
}

第三步,如果项目是 ASP.NET Core,就不必再手动 Build,直接注入使用,并在启动时做一次绑定校验。下面的片段放在 Program.cs 中,适合需要强类型的场景;校验失败时的行为取决于你是否配置了 ValidateOnStart,需要结合项目框架版本确认可用性。

builder.Services.Configure<SmtpOptions>(builder.Configuration.GetSection("Smtp"));

// 使用处
public class MailService
{
    private readonly SmtpOptions _options;
    public MailService(IOptions<SmtpOptions> options) => _options = options.Value;
}

顺序上的原则是:先让配置文件被正确加载,再决定读单值还是绑定对象,最后才处理环境覆盖和校验。反过来先写业务代码,最后才发现路径或包引用不对,返工成本更高。

改完后怎么验证

验证动作从最小可观察信号开始。先在读取后打印或断点查看取到的值,确认不是 null;再把 appsettings.json 里一个键删掉,观察程序是抛异常还是走默认值,这能验证 optional 和空值处理的预期是否一致。对强类型绑定,故意把 Port 写成非数字字符串,看是否在绑定阶段抛出转换异常,避免线上才发现类型不一致。

C# 读取 appsettings.json 配置项方法

还要验证文件确实被带到了运行目录。查看 bin 下对应目录是否存在 appsettings.json,或者发布后用命令行在输出目录启动一次程序,确认没有出现“配置文件找不到”的异常。若使用了环境变量覆盖,可以临时设置一个同名环境变量(层级用双下划线表示,例如 Smtp__Host),确认它是否按预期覆盖了 JSON 中的值。

预期信号是:主配置键能稳定读到;可选环境文件缺失不影响启动;类型错误在启动或绑定阶段暴露,而不是在使用时静默变成默认值。若观察到读到的值与文件内容不符,先排查加载顺序和环境变量覆盖,而不是怀疑 API 用法。

容易忽略的边界

文件路径是最常见的坑。SetBasePath 用 AppContext.BaseDirectory 在多数运行方式下可行,但通过某些测试宿主或特殊启动方式运行时,当前目录可能不同,需要用环境确认后再固定。类库本身不应假设自己知道宿主的工作目录,配置对象通常由调用方传入更稳妥。

版本和包方面,不同 .NET 版本对配置包的引用方式有差异,ASP.NET Core 项目一般已隐式包含,控制台项目需要显式安装;绑定强类型依赖 Binder 包,缺了会编译失败而不是运行时报错,这一点在迁移旧项目时容易踩到。reloadOnChange 依赖文件系统通知,容器挂载卷、某些网络文件系统下可能收不到变更,不能当作实时配置中心使用。

不适用或需要回退的情况也要想清楚:如果配置需要多实例一致、频繁变更、带审计,单靠本地 appsettings.json 不合适,应改用配置中心或数据库配置表;如果只是临时改一个值排查问题,可以直接改文件并重启,而不必引入额外的热更新逻辑。敏感信息如密码、密钥不建议长期明文放在 appsettings.json 中,通常改用用户机密、环境变量或密钥管理服务,并在代码里保留从配置读取的入口,方便后续替换来源。