AppSettings.json:.NET Core/.NET 应用配置的利器
在 .NET Core 和 .NET 5/6/7/8 等现代 .NET 应用开发中,appsettings.json 是最常用、最核心的配置文件之一,它以 JSON 格式存储应用程序的配置信息,如数据库连接字符串、API 密钥、功能开关、日志级别等,替代了传统 .NET Framework 中基于 XML 的 web.config 或 app.config,让配置管理更简洁、灵活且跨平台,本文将详细介绍 appsettings.json 的使用方法,从基础操作到高级技巧,助你配置管理的核心技能。
认识 appsettings.json:基础结构与默认位置
appsettings.json 是一个 JSON 格式的配置文件,默认情况下,ASP.NET Core 和控制台应用模板会自动生成该文件,其基础结构如下:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"DefaultConnection": "Server=.;Database=MyDb;Trusted_Connection=True;"
},
"AppSettings": {
"ApiKey": "your-api-key-here",
"EnableFeature": true,
"MaxRetries": 3
}
}
默认位置与加载机制
- Web 应用(ASP.NET Core):默认位于项目根目录,通过
appsettings.json、appsettings.Development.json(开发环境)、appsettings.Production.json(生产环境)等环境特定文件覆盖配置。 - 控制台应用:同样位于项目根目录,需手动配置配置源(后文详述)。
.NET 的配置系统会自动按环境名称加载对应文件(如开发环境加载 appsettings.Development.json),后加载的配置会覆盖先加载的相同键,实现环境隔离。
基础用法:读取配置值
通过 IConfiguration 读取(推荐)
在 .NET 依赖注入(DI)容器中,IConfiguration 已默认注册为服务,可直接在类中通过构造函数注入并读取配置。
示例:在控制器或服务中使用
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private readonly IConfiguration _configuration;
// 通过构造函数注入 IConfiguration
public WeatherForecastController(IConfiguration configuration)
{
_configuration = configuration;
}
[HttpGet]
public IActionResult Get()
{
// 顶级键直接读取(如 "AllowedHosts")
var allowedHosts = _configuration["AllowedHosts"];
// 读取嵌套对象(如 "AppSettings:ApiKey")
var apiKey = _configuration["AppSettings:ApiKey"];
// 读取复杂对象(如 ConnectionStrings:DefaultConnection)
var connectionString = _configuration.GetConnectionString("DefaultConnection");
return Ok(new {
AllowedHosts = allowedHosts,
ApiKey = apiKey,
ConnectionString = connectionString
});
}
}
说明:
- 使用冒号 分隔嵌套层级(如
AppSettings:ApiKey对应 JSON 中的{"AppSettings": {"ApiKey": "..."}})。 GetConnectionString是扩展方法,专门读取ConnectionStrings节点的值(约定优于配置)。
绑定到强类型对象(更优雅的方式)
直接读取字符串键值不够类型安全,推荐将配置节绑定到 C# 对象,通过强类型访问。
步骤1:定义配置模型类
public class AppSettings
{
public string ApiKey { get; set; }
public bool EnableFeature { get; set; }
public int MaxRetries { get; set; }
}
public class ConnectionStrings
{
public string DefaultConnection { get; set; }
}
步骤2:绑定并使用
using Microsoft.Extensions.Configuration;
public class MyService
{
private readonly AppSettings _appSettings;
private readonly string _connectionString;
public MyService(IConfiguration configuration)
{
// 绑定 "AppSettings" 节点到 AppSettings 对象
_appSettings = configuration.GetSection("AppSettings").Get<AppSettings>();
// 绑定 "ConnectionStrings" 节点到 ConnectionStrings 对象
var connectionStrings = configuration.GetSection("ConnectionStrings").Get<ConnectionStrings>();
_connectionString = connectionStrings.DefaultConnection;
}
public void UseConfiguration()
{
Console.WriteLine($"API Key: {_appSettings.ApiKey}");
Console.WriteLine($"Enable Feature: {_appSettings.EnableFeature}");
Console.WriteLine($"Max Retries: {_appSettings.MaxRetries}");
Console.WriteLine($"Connection String: {_connectionString}");
}
}
优点:
- 类型安全:避免因配置键名拼写错误导致的运行时异常。
- 可维护性:配置结构化后,修改字段无需修改调用代码。
进阶用法:环境特定配置与多环境管理
实际开发中,开发、测试、生产环境的配置往往不同(如数据库连接、API 地址)。appsettings.json 支持通过环境特定文件实现配置隔离。
环境特定文件命名规则
默认约定:appsettings.{EnvironmentName}.json,如:
appsettings.Development.json:开发环境配置appsettings.Production.json:生产环境配置appsettings.Staging.json:预发布环境配置
文件覆盖机制
.NET 配置系统会自动加载基础文件(appsettings.json)和环境特定文件,环境特定文件的配置会覆盖基础文件的相同键。
示例:
基础 appsettings.json:
{
"AppSettings": {
"LogLevel": "Information",
"EnableFeature": false
}
}
开发环境 appsettings.Development.json:
{
"AppSettings": {
"LogLevel": "Debug",
"EnableFeature": true
}
}
运行时(开发环境),AppSettings:LogLevel 为 Debug,AppSettings:EnableFeature 为 true,覆盖了基础文件的值。
设置运行环境
通过环境变量或命令行参数指定环境:
- 命令行:
dotnet run --environment Development - 环境变量:
ASPNETCORE_ENVIRONMENT=Development(Windows)或export ASPNETCORE_ENVIRONMENT=Development(Linux/macOS) - launchSettings.json(VS/VS Code 中配置默认环境):
{ "profiles": { "MyApp": { "commandName": "Project", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" } } } }
高级技巧:自定义配置源与加密
添加自定义配置源
默认情况下,appsettings.json 的配置优先级较低,可通过 ConfigurationBuilder 添加其他配置源(如环境变量、命令行参数、Azure Key Vault 等),后添加的源优先级更高。
示例:在控制台应用中手动加载 appsettings.json
using Microsoft.Extensions.Configuration;
class Program
{
static void Main(string[] args)
{
// 1. 创建 ConfigurationBuilder
var builder = new ConfigurationBuilder();
// 2. 添加配置源(按优先级从低到高)
builder.SetBasePath(Directory.GetCurrentDirectory()) // 设置基础路径(默认项目根目录)
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true) // 基础配置文件
.AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json", optional: true) // 环境特定文件
.AddEnvironmentVariables() // 环境变量(优先级较高)
.AddCommandLine(args); // 命令行参数(优先级最高)
// 3. 构建 IConfigurationRoot
IConfiguration configuration = builder.Build();
// 读取配置(命令行参数可覆盖环境变量和文件配置)
var message = configuration["Message"] ?? "Default Message";
Console.WriteLine(message);
}
}
运行命令:dotnet run --Message "Hello from Command Line",输出 Hello from Command Line(命令行参数覆盖了文件配置)。
配置值加密(敏感信息保护)
appsettings.json 默认明文存储敏感信息(如数据库密码、API 密钥),存在安全风险,可通过以下方式加密:
方案1:使用 Azure Key Vault(推荐云场景)
将敏感配置存储在 Azure Key Vault 中,通过 AzureKeyVaultConfigurationProvider 加载:
// 在 Program.cs 中添加 builder.Configuration.AddAzureKeyVault();
方案2:使用 DPAPI(Windows 本地加密)
通过 `



还没有评论,来说两句吧...