ASP.NET Core 6 使用 yaml 檔案取代預設的 appsettings.json 設定檔

ASP.NET 以前預設設定檔是 Web.config 或 App.config ,使用 xml ,現在 ASP.NET Core 預設是使用 appsettings.json,還有使用過 ini。不過隨者專案增加,筆者也發現了一些小缺點。

在設定設定檔時往往會忘記或是不確定設定檔的每個欄位是什麼,又要找原始碼或是翻文件,而且大多主機不能開啟 word 檔案,要變更設定就變得非常麻煩。而 ini 支援度不佳, xml 對使用者來說太難,json 的格式很容易寫錯逗號,且標準規範又不支援註解,於是筆者最近就看上了 yaml。

Yaml 非常適合用來寫設定檔,包括 Docker Compose, Kubernetes, SpringBoot 也可以使用 application.yml 做為設定檔,而在 ASP.NET Core 中還沒有原生支援,不過還好有萬能的社群,本文就來介紹如何使用 yaml 設定檔。

安裝

先使用 NuGet 安裝 NetEscapades.Configuration.Yaml 套件,或是使用 .NET CLI 執行以下指令安裝
	
dotnet add package NetEscapades.Configuration.Yaml
    

使用示範

在筆者撰寫本文的當下,在 NetEscapades.Configuration 的 Github 上示範的是 ASP.NET Core 是 3.0 以前的舊版的寫法,不是用於現在新版的寫法,不過要轉換也非常簡單,使用方式就只要在 Program.cs 中加入下面這行即可
    
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddYamlFile("appsettings.yml");
    

可選參數:
  • optional: 檔案是可選的,如果是 fasle(預設值為 false) 則找不檔案時會拋出錯誤
  • reloadOnChange: 變更時重新讀取設定檔
如果將 optional 設定 false 且沒有找到該檔案時會拋出錯誤,錯誤訊息範例如下:
    
Unhandled exception. System.IO.FileNotFoundException: The configuration file 'appsettings.yml' was not found and is not optional. The expected physical path was 'C:\Users\ruyu
t\Documents\RiderProjects\2023\test\WebApplicationYamlAppSettingTest\WebApplicationYamlAppSettingTest\appsettings.yml'.
   at Microsoft.Extensions.Configuration.FileConfigurationProvider.Load(Boolean reload)
   at Microsoft.Extensions.Configuration.ConfigurationManager.AddSource(IConfigurationSource source)
   at Microsoft.Extensions.Configuration.ConfigurationManager.Microsoft.Extensions.Configuration.IConfigurationBuilder.Add(IConfigurationSource source)
   at Microsoft.Extensions.Configuration.YamlConfigurationExtensions.AddYamlFile(IConfigurationBuilder builder, Action`1 configureSource)
   at Microsoft.Extensions.Configuration.YamlConfigurationExtensions.AddYamlFile(IConfigurationBuilder builder, IFileProvider provider, String path, Boolean optional, Boolean
reloadOnChange)
   at Microsoft.Extensions.Configuration.YamlConfigurationExtensions.AddYamlFile(IConfigurationBuilder builder, String path, Boolean optional)
   at Program.<Main>$(String[] args) in C:\Users\ruyut\Documents\RiderProjects\2023\test\WebApplicationYamlAppSettingTest\WebApplicationYamlAppSettingTest\Program.cs:line 2
    

預設的 appsettings.json 設定檔內容如下:
    
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}
    

等效的 yaml 如下:
    
Logging:
  LogLevel:
    Default: Information
    Microsoft.AspNetCore: Warning
AllowedHosts: "*"
    

多設定檔

如果想要拆分設定檔,或是不同的環境有不同的設定檔怎麼辦? 可以使用下面的方式讀取多個設定檔,下面的會覆蓋上面的。下面的例子為 json 是可選的,但是一定要 yml (因為 optional 選項),且若 json 和 yml 都共有的設定值會以下方的 yml 為主。而且除了 json 和 yml 外還支援 Ini 和 Xml 檔案,非常方便!
    
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddYamlFile("appsettings.yml", optional: false, reloadOnChange: true);
    

讀取範例

範例設定檔:
    
Swagger:
  Json: true # 啟用 Swagger JSON Endpoint
  Ui: true   # 啟用 Swagger UI Endpoint
Attachment:
  Path: ./attachment # 附件儲存路徑
    

範例程式碼:
    
[ApiController]
public class SettingController : ControllerBase
{
    private readonly IConfiguration _configuration;

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

    [HttpGet("setting")]
    public IActionResult Get()
    {
        return Ok(new
            {
                SwaggerJson = _configuration["Swagger:Json"],
                SwaggerUi = _configuration["Swagger:Ui"],
                AttachmentPath = _configuration["Attachment:Path"],
            }
        );
    }
}
    

範例輸出:
    
{
  "swaggerJson": "true",
  "swaggerUi": "true",
  "attachmentPath": "./attachment"
}
    

延伸閱讀:
ASP.NET Core 6 讀取設定檔(appsettings.json)範例
ASP.NET Core 使用強型別讀取設定檔 appsettings.json 教學
ASP.NET Core 7 啟動時驗證設定檔(appsettings.json)內容

參考資料:
Wiki - YAML
Yaml 官網 Github - andrewlock/NetEscapades.Configuration

留言