Cấu hình với appsettings

Tên cửa hàng, số món tối đa mỗi đơn, chuỗi kết nối database: những giá trị này khác nhau giữa máy dev và server thật. Viết cứng trong code thì mỗi lần đổi phải build lại. ASP.NET Core đọc chúng từ file cấu hình.

Khái niệm

⚙️ appsettings.json: file JSON chứa cấu hình của ứng dụng, được đọc tự động khi khởi động.

🌍 Môi trường (environment): tên chế độ đang chạy như Development hay Production, quyết định file appsettings.{Môi trường}.json nào được đọc sau để ghi đè appsettings.json.

Ví dụ

Thêm vào appsettings.json:

{
  "Shop": {
    "Name": "Shop An",
    "MaxItemsPerOrder": 20
  }
}

Đọc trong controller qua IConfiguration:

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/shop")]
public class ShopController : ControllerBase
{
    private readonly IConfiguration _config;

    public ShopController(IConfiguration config)
    {
        _config = config;
    }

    [HttpGet]
    public string Get()
    {
        string? name = _config["Shop:Name"];
        int max = _config.GetValue<int>(
            "Shop:MaxItemsPerOrder");
        return $"{name}: tối đa {max} món";
    }
}

• IConfiguration có sẵn trong container, chỉ cần nhận qua constructor.
• Dấu : nối tên các cấp trong JSON: Shop:Name.
• GetValue<int> đọc giá trị rồi đổi sang kiểu int.

Đọc cấu hình vào class

Nhiều giá trị cùng nhóm thì đọc cả nhóm vào một class:

using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<ShopOptions>(
    builder.Configuration.GetSection("Shop"));

public class ShopOptions
{
    public string Name { get; set; } = "";
    public int MaxItemsPerOrder { get; set; }
}

Class cần dùng nhận IOptions<ShopOptions> qua constructor, rồi đọc options.Value.MaxItemsPerOrder. Cách này có kiểu rõ ràng, gõ sai tên property thì compiler báo ngay. Tên property vẫn phải khớp với key trong JSON.

Thử ngay

Dùng ShopController ở phần Ví dụ. Mở file appsettings.Development.json có sẵn trong project, thêm:

{
  "Shop": {
    "MaxItemsPerOrder": 5
  }
}

Chạy lại server rồi gọi curl -i http://localhost:5000/api/shop.

Đoán trước khi chạy: dotnet run chạy ở môi trường Development. Số món tối đa in ra là 20 hay 5?

HTTP/1.1 200 OK

Shop An: tối đa 5 món

Lỗi hay gặp

Gõ sai tên key. Ứng dụng không báo lỗi, chỉ trả về giá trị mặc định.

// SAI — thiếu chữ s, max luôn bằng 0
int max = _config.GetValue<int>(
    "Shop:MaxItemPerOrder");

// ĐÚNG — gõ sai tên property thì compiler báo
int max = options.Value.MaxItemsPerOrder;

Đọc qua class ShopOptions như ở trên thì tên key chỉ khai báo một lần, không phải gõ lại chuỗi ở nhiều nơi.

Để mật khẩu trong appsettings.json. File này được commit lên git, ai có code là thấy mật khẩu. Khi dev, lưu bí mật bằng dotnet user-secrets. Trên server, lưu bằng biến môi trường.

Tóm tắt

• Cấu hình nằm trong appsettings.json, đọc qua IConfiguration.
• appsettings.Development.json ghi đè giá trị khi chạy ở môi trường dev.
• Nhóm cấu hình nên đọc vào class bằng Configure<T> và IOptions<T>.
• Không để mật khẩu hay khoá bí mật trong file commit lên git.