C#怎么使用配置文件？C#读取appsettings配置教程详解

在C#开发中，配置文件是存储应用运行参数的常用方式，appsettings作为.NET Core及后续版本默认的配置源，掌握其读取方法对开发者十分重要。本文将详细介绍不同场景下读取appsettings配置的具体操作。

准备工作

首先需要在项目中添加必要的NuGet包，如果是.NET Core或.NET 6及以上版本的项目，默认已经包含了配置相关的基础包，若需要额外功能可以按需安装。同时需要在项目根目录创建appsettings.json文件，这是默认的配置文件。

基础appsettings配置示例

以下是一个简单的appsettings.json配置内容：

{
  "AppName": "配置读取示例应用",
  "MaxConnectionCount": 100,
  "IsEnableLog": true,
  "Database": {
    "Server": "127.0.0.1",
    "Port": 3306,
    "DatabaseName": "test_db"
  },
  "AllowedHosts": ["localhost", "192.168.0.1"]
}

基础配置读取方法

在.NET Core项目中，通常通过依赖注入获取IConfiguration实例来读取配置，首先需要在Program.cs中完成配置注册。

Program.cs配置注册

以下是.NET 6及以上版本的Program.cs配置示例：

var builder = WebApplication.CreateBuilder(args);

// 默认已经添加了appsettings.json的配置源，无需额外操作
// 如果需要添加其他配置文件可以添加如下代码
// builder.Configuration.AddJsonFile("appsettings.custom.json", optional: true, reloadOnChange: true);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

读取简单键值配置

可以通过IConfiguration的索引器或者GetValue方法读取简单配置项，以下是控制台中的读取示例：

using Microsoft.Extensions.Configuration;

// 构建配置
IConfiguration configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

// 读取字符串类型配置
string appName = configuration["AppName"];
// 读取并转换类型，默认值为空字符串
string appName2 = configuration.GetValue<string>("AppName", "");
// 读取整型配置
int maxConnectionCount = configuration.GetValue<int>("MaxConnectionCount", 0);
// 读取布尔型配置
bool isEnableLog = configuration.GetValue<bool>("IsEnableLog", false);

Console.WriteLine($"应用名称：{appName}");
Console.WriteLine($"最大连接数：{maxConnectionCount}");
Console.WriteLine($"是否开启日志：{isEnableLog}");

嵌套配置读取方法

对于嵌套的配置项，可以通过冒号分隔的路径来读取，也可以通过绑定到实体类的方式读取。

路径读取嵌套配置

// 读取嵌套的数据库服务器地址
string dbServer = configuration["Database:Server"];
// 读取嵌套的数据库端口
int dbPort = configuration.GetValue<int>("Database:Port", 3306);
// 读取嵌套的数据库名称
string dbName = configuration["Database:DatabaseName"];

Console.WriteLine($"数据库服务器：{dbServer}");
Console.WriteLine($"数据库端口：{dbPort}");
Console.WriteLine($"数据库名称：{dbName}");

绑定实体类读取配置

首先定义对应的实体类：

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

然后进行配置绑定：

// 绑定嵌套配置到实体类
DatabaseConfig databaseConfig = new DatabaseConfig();
configuration.GetSection("Database").Bind(databaseConfig);

// 或者使用Get方法直接获取
DatabaseConfig databaseConfig2 = configuration.GetSection("Database").Get<DatabaseConfig>();

Console.WriteLine($"绑定后数据库服务器：{databaseConfig.Server}");
Console.WriteLine($"绑定后数据库端口：{databaseConfig.Port}");

数组类型配置读取方法

对于配置中的数组类型，同样可以通过路径或者绑定实体类的方式读取。

路径读取数组配置

// 读取数组第一个元素
string firstAllowedHost = configuration["AllowedHosts:0"];
// 读取数组第二个元素
string secondAllowedHost = configuration["AllowedHosts:1"];

Console.WriteLine($"第一个允许的主机：{firstAllowedHost}");
Console.WriteLine($"第二个允许的主机：{secondAllowedHost}");

绑定实体类读取数组

定义包含数组的实体类：

public class AppConfig
{
    public string AppName { get; set; }
    public List<string> AllowedHosts { get; set; }
}

绑定整个配置到实体类：

AppConfig appConfig = configuration.Get<AppConfig>();
Console.WriteLine($"应用名称：{appConfig.AppName}");
Console.WriteLine("允许的主机列表：");
foreach (var host in appConfig.AllowedHosts)
{
    Console.WriteLine(host);
}

在ASP.NET Core控制器中读取配置

在ASP.NET Core项目中，可以通过构造函数注入IConfiguration来读取配置，示例如下：

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

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

    public ConfigController(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    [HttpGet]
    public IActionResult GetConfig()
    {
        var appName = _configuration["AppName"];
        var dbServer = _configuration["Database:Server"];
        return Ok(new { AppName = appName, DbServer = dbServer });
    }
}

注意事项

• appsettings.json文件的属性需要设置为“复制到输出目录”，否则运行时会找不到配置文件，通常设置为“如果较新则复制”即可。
• 读取配置时如果键不存在，使用索引器会返回null，使用GetValue方法可以设置默认值避免空引用问题。
• 如果项目同时存在appsettings.json和appsettings.Development.json，运行时会优先读取对应环境的配置文件， Development环境的配置会覆盖默认配置中的相同键。
• 配置键不区分大小写，配置AppName和appname是等效的。

C#appsettings配置文件IConfiguration修改时间：2026-07-02 21:09:14