appsettings.json怎么用

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 本地加密）

通过 `