C#怎么读取应用程序的配置文件appsettings.json

在C#开发中，appsettings.json是常用的配置文件格式，无论是ASP.NET Core应用还是.NET控制台应用，都可以通过统一的配置体系读取其中的内容，不需要手动解析JSON字符串。

读取前的准备工作

要读取appsettings.json，首先需要引入对应的NuGet包，不同项目类型的依赖略有区别：

• ASP.NET Core项目默认已经包含了Microsoft.Extensions.Configuration相关依赖，不需要额外安装
• .NET控制台项目需要手动安装以下三个NuGet包：
  • Microsoft.Extensions.Configuration
  • Microsoft.Extensions.Configuration.Json
  • Microsoft.Extensions.Configuration.Binder

基础读取步骤

1. 创建appsettings.json文件

首先在项目的根目录下创建appsettings.json文件，设置文件的属性为“如果较新则复制”，保证编译后文件会输出到程序运行目录。以下是一个基础的配置文件示例：

{
  "AppName": "配置读取示例应用",
  "MaxConnectionCount": 100,
  "Database": {
    "Server": "127.0.0.1",
    "Port": 3306,
    "UserName": "root",
    "Password": "123456"
  },
  "AllowedHosts": ["localhost", "ipipp.com"]
}

2. 构建配置对象

使用ConfigurationBuilder来加载appsettings.json文件，生成IConfiguration对象，后续所有配置读取都基于这个对象完成。

using Microsoft.Extensions.Configuration;
using System.IO;

// 构建配置
IConfiguration configuration = new ConfigurationBuilder()
    // 设置配置文件所在的基础路径，控制台应用需要指定当前目录，ASP.NET Core可以省略这行
    .SetBasePath(Directory.GetCurrentDirectory())
    // 加载appsettings.json文件，optional表示文件是否可选，reloadOnChange表示文件修改后是否自动重新加载
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

3. 读取配置项

读取配置有两种常用方式，分别是直接通过键路径读取和绑定到自定义实体类读取。

直接通过键路径读取

对于简单配置或者嵌套配置，可以直接使用configuration["键路径"]的方式读取，嵌套配置用冒号分隔层级。

// 读取顶层配置
string appName = configuration["AppName"];
int maxConnectionCount = int.Parse(configuration["MaxConnectionCount"]);

// 读取嵌套配置
string dbServer = configuration["Database:Server"];
int dbPort = int.Parse(configuration["Database:Port"]);
string dbUserName = configuration["Database:UserName"];
string dbPassword = configuration["Database:Password"];

// 读取数组配置
string firstAllowedHost = configuration["AllowedHosts:0"];
string secondAllowedHost = configuration["AllowedHosts:1"];

绑定到实体类读取

如果配置项较多，直接读取键路径的方式不够直观，可以定义和配置结构对应的实体类，通过Bind方法或者Get<T>方法绑定到实例。

首先定义对应的实体类：

public class DatabaseConfig
{
    public string Server { get; set; }
    public int Port { get; set; }
    public string UserName { get; set; }
    public string Password { get; set; }
}

public class AppConfig
{
    public string AppName { get; set; }
    public int MaxConnectionCount { get; set; }
    public DatabaseConfig Database { get; set; }
    public List<string> AllowedHosts { get; set; }
}

然后绑定配置到实体类实例：

using Microsoft.Extensions.Configuration;

// 绑定整个配置到AppConfig实例
AppConfig appConfig = configuration.Get<AppConfig>();

// 也可以只绑定某个节点到对应的实体类
DatabaseConfig dbConfig = configuration.GetSection("Database").Get<DatabaseConfig>();

// 获取绑定后的配置值
string appName = appConfig.AppName;
string dbServer = appConfig.Database.Server;
List<string> allowedHosts = appConfig.AllowedHosts;

ASP.NET Core中的特殊用法

在ASP.NET Core应用中，配置对象已经被框架自动注入到服务容器，不需要手动构建ConfigurationBuilder，可以直接通过构造函数注入IConfiguration来使用。

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;

[ApiController]
[Route("api/config")]
public class ConfigController : ControllerBase
{
    private readonly IConfiguration _configuration;

    // 构造函数注入IConfiguration
    public ConfigController(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    [HttpGet]
    public IActionResult GetConfig()
    {
        string appName = _configuration["AppName"];
        return Ok(new { AppName = appName });
    }
}

注意事项

• appsettings.json文件的路径必须正确，控制台应用如果设置了输出目录为bin文件夹，需要确保文件复制到输出目录
• 读取配置时要注意类型转换，直接读取到的都是字符串类型，需要根据实际需求转换为对应的类型，避免转换异常
• 如果同时存在appsettings.json和appsettings.Development.json等环境配置文件，框架会自动合并配置，环境相关的配置会覆盖基础配置的内容
• 如果配置项不存在，直接通过键路径读取会返回null，需要做非空判断避免空引用异常

C#appsettings.jsonConfigurationBuilderIConfigurationASP.NET_Core修改时间：2026-06-28 13:30:34