NBearV3 ORM 基礎教學：實體設計、關聯關係、程式碼生成與 Gateway 資料存取完整實戰

教學目標

掌握 NBearV3 ORM 模組開發 Web 應用的完整流程：實體關係設計（繼承、1:1、1:N、N:M）、可空型別與複合型別、工具生成程式碼/配置/資料庫腳本、Gateway 資料存取操作。

專案結構

1. 空白方案 + 3 專案：EntityDesigns、Entities、website (ASP.NET)
2. EntityDesigns 參考 NBear.Common.Design.dll
3. Entities 稍後參考 NBear.Common.dll
4. website 參考 Entities + NBear.Data.dll

Step 1：設計實體與關聯（類別圖或程式碼）

建立自訂型別（於 Entities 專案）

public struct UserName { public string FirstName; public string LastName; }
public enum UserStatus { Available, Deleted }

實體定義（EntityDesigns\EntityDesigns.cs）

[MappingName("Categories")]
public interface Category : Entity {
    [PrimaryKey] int CategoryID { get; }
    [SqlType("nvarchar(15)")] string CategoryName { get; set; }
    [SqlType("ntext")] string Description { get; set; }
    byte[] Picture { get; set; }
}

[MappingName("Products")]
public interface Product : Entity {
    [PrimaryKey] int ProductID { get; }
    [SqlType("nvarchar(40)")] string ProductName { get; set; }
    int SupplierID { get; set; }
    int CategoryID { get; set; }
    [SqlType("nvarchar(20)")] string QuantityPerUnit { get; set; }
    decimal UnitPrice { get; set; }
    short UnitsInStock { get; set; }
    short UnitsOnOrder { get; set; }
    short ReorderLevel { get; set; }
    bool Discontinued { get; set; }
}

// 完整教學實體範例（User/LocalUser/UserProfile/LocalUserPhone/Group/UserGroup）
// 繼承：LocalUser : User
// 1:1：User.Profile → UserProfile (FkQuery, Contained=true, LazyLoad=false)
// 1:N：LocalUser.Phones → LocalUserPhone[] (FkQuery, Contained=true, LazyLoad=true)
// N:M：User.Groups → Group[] (ManyToManyQuery, 關聯實體 UserGroup)
// 複合型別：User.Name → UserName (CompoundUnit, SqlType=ntext)
// 可空型別：User.Birthday → DateTime?
// 關聯實體：UserGroup (Relation, RelationKey 指向 User/Group)

Step 2：元資料屬性詳細說明

• PrimaryKey：主鍵，可多欄位。int ID { get; } 僅 get 映射自增欄位
• SqlType：指定字串對應資料庫型別（預設 nvarchar(127)）
• CompoundUnit：標記複合型別，序列化為 XML 存入單一欄位
• FkQuery：1:1 或 1:N 外鍵查詢，參數：外鍵欄位、Contained(級聯)、LazyLoad
• FkReverseQuery：反向 1:1 關聯
• ManyToManyQuery：N:M 關聯，必須指定關聯實體型別
• Relation + RelationKey：關聯實體定義，RelationKey 指定對應實體
• NotNull + SerializationIgnore：非空欄位、排除 XML 序列化
• ReadOnly：唯讀實體（對應 View）

Step 3：工具生成三大產出

1. 編譯 EntityDesigns
2. 執行 EntityDesignToEntity.exe 載入 DLL
3. Generate Entities → Entities\Entities.cs
4. Generate Configuration → website\EntityConfig.xml
5. Generate DB Script → website\db.sql（於目標資料庫執行建立資料表）

Step 4：Web.config 配置

<configSections>
  <section name="entityConfig" type="NBear.Common.EntityConfigurationSection, NBear.Common" />
</configSections>
<entityConfig>
  <includes> <add key="Sample Entity Config" value="~/EntityConfig.xml" /> </includes>
</entityConfig>
<connectionStrings>
  <add name="DbName" connectionString="Server=(local);Database=tempdb;Uid=sa;Pwd=sa" providerName="NBear.Data.SqlServer.SqlDbProvider" />
</connectionStrings>

Step 5：Gateway 資料存取實戰

Gateway gateway = new Gateway("tempdb");  // 或 Gateway.Default

// 建立完整物件圖並級聯儲存
LocalUser newUser = new LocalUser();
newUser.ID = Guid.NewGuid();
newUser.Password = "12345";
newUser.Name = new UserName { FirstName = "teddy", LastName = "ma" };
newUser.Status = UserStatus.Available;

// 1:1 關聯
UserProfile profile = new UserProfile { ID = Guid.NewGuid(), UserID = newUser.ID, ProfileContent = "..." };
newUser.Profile = profile;

// 1:N 關聯
LocalUserPhone[] phones = new LocalUserPhone[2];
phones[0] = new LocalUserPhone { ID = Guid.NewGuid(), UserID = newUser.ID, Description = "home", Number = "111" };
phones[1] = new LocalUserPhone { ID = Guid.NewGuid(), UserID = newUser.ID, Description = "work", Number = "222" };
newUser.Phones = new LocalUserPhoneArrayList(phones);

// N:M 關聯（需手動處理，因未標記 Contained）
Group group = new Group { ID = Guid.NewGuid(), Name = "new group" };
newUser.Groups = new GroupArrayList { group };

gateway.Save<LocalUser>(newUser);  // 級聯儲存 Profile、Phones，但不含 Groups

// 驗證儲存結果
LocalUser saved = gateway.Find<LocalUser>(newUser.ID);
// 檢查 Profile、Phones 是否級聯儲存
// Groups 未儲存 → 需手動儲存 Group + 建立 UserGroup 關聯實體

// 複合型別序列化自訂
SerializationManager.RegisterSerializeHandler(typeof(UserName), 
    o => ((UserName)o).FirstName + "," + ((UserName)o).LastName,
    s => { var p = s.Split(','); return new UserName { FirstName = p[0], LastName = p[1]; });
gateway.Save<LocalUser>(saved);  // 此後 UserName 存為 "teddy,ma" 而非 XML

Gateway 初始化多資料庫支援

// 方式 1：Web.config connectionStrings name
public static Gateway Northwind = new Gateway("Northwind");
public static Gateway TestAccessDb = new Gateway("TestAccessDb");

// 方式 2：直接提供連線字串
Gateway TestDbAccess = new Gateway(DatabaseType.MsAccess, @"C:\path\db.mdb");
Gateway Northwind = new Gateway(DatabaseType.SqlServer, "Server=(local);Database=Northwind;Uid=sa;Pwd=sa");
Gateway Northwind2 = new Gateway(DatabaseType.SqlServer9, "Server=(local)\SQLEXPRESS;Database=Northwind;Uid=sa;Pwd=sa");
Gateway MySql = new Gateway(DatabaseType.MySql, "Dsn=mysqltest;database=test;server=localhost;uid=root;pwd=sa");
Gateway Oracle = new Gateway(DatabaseType.Oracle, "Data Source=localhost;User ID=system;Pwd=sa;Unicode=True");

支援 Access、SQL Server 2000/2005、MySQL、Oracle 等多種資料庫。

執行結果驗證

執行後可見完整級聯儲存流程、N:M 關聯手動處理、複合型別 XML 序列化與自訂序列化切換效果。