ASP.NET Core 教學 - 自訂組態設定檔

-- Pageviews

ASP.NET Core 教學 - 自訂組態設定檔

.NET Core 讀取組態設定的方式跟過去有點不同，已經不再使用 ConfigurationManager 來取用組態設定值。
本篇將介紹 ASP.NET Core 的 Configuration 取用及建議做法。

1. 建立組態設定檔

在專案當中建立一個 Configuration 的資料夾，並建立 Settings.json。
可以依照個人喜好或團隊習慣的方式建立組態檔，檔名跟路徑並沒有特別的規則。
JSON 的內容也沒有限制，只要是符合 JSON 格式即可，我的範例 Settings.json 就建立的很隨興。

Configuration\Settings.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "SupportedCultures": [
    "en-GB",
    "zh-TW",
    "zh-CN"
  ],
  "CustomObject": {
    "Property": {
      "SubProperty": 1,
      "SubProperty2": true,
      "SubProperty3": "This is sub property."
    }
  }
}

過去 ASP.NET MVC、.NET Application 的組態設定檔預設用 Web.config 或 App.config，採用 XML 格式。
現在 .NET Core 建議採用 JSON 格式，比較簡潔易讀。

2. 載入組態設定

在 Startup.cs 的 ConfigureServices 載入組態設定，並註冊到 Services 中，讓組態設定之後可以被 DI。

Startup.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton(GetSettings());
    }

    private IConfigurationRoot GetSettings()
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(Path.Combine(Directory.GetCurrentDirectory(), "Configuration"))
            .AddJsonFile(path: "Settings.json", optional: true, reloadOnChange: true);
        return builder.Build();
    }
}

主要是透過 ConfigurationBuilder 產生 IConfigurationRoot 的實例。

  • SetBasePath：設定 Configuration 的目錄位置，如果是放在不同目錄，再把路徑換掉即可。
  • AddJsonFile：
  1. path：加入要被使用組態檔案。
  2. optional：如果是必要組態檔 optional 就要設定為 false，當檔案不存在就會拋出 FileNotFoundException。
  3. reloadOnChange：如果檔案被更新，就同步更新 IConfigurationRoot 實例的值。

3. 使用組態設定

透過 DI 取用 IConfigurationRoot 實例，以 Dictionary 的方式取用組態檔的值。

如果不了解 DI 可以參考這篇：ASP.NET Core 教學 - Dependency Injection

1
2
3
4
5
6
7
public HomeController(IConfigurationRoot config)
{
    var defaultCulture = config["SupportedCultures:1"]; // defaultCulture = "zh-TW"
    var subProperty1 = config["CustomObject:Property:SubProperty1"]; // subProperty1 = "1"
    var subProperty2 = config["CustomObject:Property:SubProperty2"]; // subProperty2 = "True"
    var subProperty3 = config["CustomObject:Property:SubProperty3"]; // subProperty3 = "This is sub property."
}

從上述範例可以看出，Key 值就是 Settings.json 內容的 Node 名稱，並以 : 符號區分階層。

4. 強型別及型態

上面範例有兩個很大的問題：

  1. 使用字串當做 Key 是弱型別，沒辦法在編譯期間檢查出打錯字。
  2. 型態不符合預期，不管是數值或布林值全都是變字串型態。

要使用強型別，首先要建立相對應的類別，Settings.json 的對應類別如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class Settings
{
    public string[] SupportedCultures { get; set; }
    public CustomObject CustomObject { get; set; }
}

public class CustomObject
{
    public Property1 Property { get; set; }
}

public class Property1
{
    public int SubProperty1 { get; set; }
    public bool SubProperty2 { get; set; }
    public string SubProperty3 { get; set; }
}

修改一下 Startup.cs 的 Services 註冊：

1
2
3
4
5
public void ConfigureServices(IServiceCollection services)
{
    //services.AddSingleton(GetSettings());
    services.Configure<Settings>(GetSettings());
}

使用的 DI 改成注入 IOptions<T>，如下：

1
2
3
4
5
6
7
public HomeController(IOptions<Settings> settings)
{
    var defaultCulture = settings.Value.SupportedCultures[1]; // defaultCulture = "zh-TW"
    var subProperty1 = settings.Value.CustomObject.Property.SubProperty1; // subProperty1 = 1
    var subProperty2 = settings.Value.CustomObject.Property.SubProperty2; // subProperty2 = true
    var subProperty3 = settings.Value.CustomObject.Property.SubProperty3; // subProperty3 = "This is sub property."
}

這樣就可以是強型別，且有明確的型態。

參考

Configuration in ASP.NET Core

ASP.NET Core C#