ASP.NET Web Pages - Database 物件完整 API 參考與最佳實務

Database 物件提供輕量級 ADO.NET 封裝，簡化 SQL 執行、參數化查詢、連線管理，適合中小型專案快速開發。

Database 核心方法完整參考

連線字串配置：Web.config

<connectionStrings>
 <add name="DefaultConnection"
 connectionString="Data Source=|DataDirectory|\AppData.sdf;Password=secret"
 providerName="System.Data.SqlServerCe.4.0" />
 <add name="SqlServerConnection"
 connectionString="Server=.;Database=MyDb;User Id=sa;Password=pwd;TrustServerCertificate=True"
 providerName="System.Data.SqlClient" />
</connectionStrings>

使用方式：var db = Database.Open("DefaultConnection");

參數化查詢：防止 SQL Injection 的關鍵

// ✅ 正確：參數化查詢
var sql = "SELECT * FROM Products WHERE CategoryId = @0 AND Price > @1";
var products = db.Query(sql, categoryId, minPrice);

// ✅ 正確：具名參數 (較易讀)
var sql = "SELECT * FROM Users WHERE Email = @email AND IsActive = @active";
var user = db.QuerySingle(sql, new { email = "user@example.com", active = true });

// ❌ 錯誤：字串串接 (SQL Injection 風險)
var sql = "SELECT * FROM Users WHERE Email = '" + email + "'";

參數佔位符：@0, @1, @2... (位置) 或 @paramName (具名)。

完整 CRUD 實作範例

Create - 新增資料

var sql = @"INSERT INTO Products (Name, Price, CategoryId, CreatedDate)
 VALUES (@0, @1, @2, @3)";
var result = db.Execute(sql, "New Product", 299.99, 5, DateTime.Now);
var newId = db.GetLastInsertId();

Read - 查詢資料

// 多筆查詢
var products = db.Query("SELECT * FROM Products WHERE CategoryId = @0", catId);
foreach (var p in products) { /* p.Name, p.Price 存取 */ }

// 單筆查詢
var product = db.QuerySingle("SELECT * FROM Products WHERE Id = @0", id);

// 純量查詢
var count = db.QueryValue("SELECT COUNT(*) FROM Products WHERE CategoryId = @0", catId);
var maxPrice = db.QueryValue("SELECT MAX(Price) FROM Products");

Update - 更新資料

var sql = "UPDATE Products SET Price = @0, UpdatedDate = @1 WHERE Id = @2";
var rows = db.Execute(sql, 349.99, DateTime.Now, productId);

Delete - 刪除資料

var rows = db.Execute("DELETE FROM Products WHERE Id = @0", productId);

資源管理與連線釋放

Database 物件實作 IDisposable，建議使用 using 區塊確保連線正確釋放：

using (var db = Database.Open("DefaultConnection")) {
 var products = db.Query("SELECT * FROM Products");
 // 處理資料
} // 自動呼叫 Dispose()，關閉連線回連線池

進階：交易處理

using (var db = Database.Open("DefaultConnection")) {
 db.Execute("BEGIN TRANSACTION");
 try {
 db.Execute("UPDATE Accounts SET Balance -= @0 WHERE Id = @1", amount, fromId);
 db.Execute("UPDATE Accounts SET Balance += @0 WHERE Id = @1", amount, toId);
 db.Execute("COMMIT");
 } catch {
 db.Execute("ROLLBACK");
 throw;
 }
}

或使用 System.Transactions.TransactionScope 進行分散式交易。

遷移建議：現代專案請使用 Entity Framework Core / Dapper

• EF Core：完整 ORM、LINQ 查詢、遷移、變更追蹤、關聯導航
• Dapper：高效能 Micro-ORM、原生 SQL、強型別映射、延遲載入支援
• Database 物件**：僅建議維護舊專案或極簡原型使用