AutoCAD .NET API：在 DWG 中建立自定義資料（XData/XRecord）與擴展字典

自定義資料儲存層級

AutoCAD 資料庫 (Database) 提供兩種層級的自定義資料容器：

• 圖形級：儲存於命名物件字典 (NOD, NamedObjectsDictionary)，全圖唯一，適合共享定義（如公司部門結構）。
• 實體級：儲存於每個 DBObject 的擴展字典 (ExtensionDictionary)，專屬於該實體（如員工薪資、部門索引）。

核心容器類別

• DBDictionary：鍵值對集合，鍵為字串，值為 DBObject（可巢狀字典）。
• Xrecord：通用資料載體，可儲存任意 TypedValue 陣列（類似 XData 但無大小限制）。

實戰：建立公司部門結構（圖形級）

[CommandMethod("CreateDivision")]
public void CreateDivision() {
    Database db = HostApplicationServices.WorkingDatabase;
    using (Transaction tr = db.TransactionManager.StartTransaction()) {
        // 取得 NOD 並開啟寫入模式
        DBDictionary nod = (DBDictionary)tr.GetObject(db.NamedObjectsDictionaryId, OpenMode.ForWrite);

        // 嘗試取得或建立 "ACME_DIVISION" 字典
        DBDictionary acmeDict;
        if (!nod.Contains("ACME_DIVISION")) {
            acmeDict = new DBDictionary();
            nod.SetAt("ACME_DIVISION", acmeDict);
            tr.AddNewlyCreatedDBObject(acmeDict, true);
        } else {
            acmeDict = (DBDictionary)tr.GetObject(nod.GetAt("ACME_DIVISION"), OpenMode.ForRead);
        }

        // 在 acmeDict 下建立部門字典與經理記錄...
        tr.Commit();
    }
}

實戰：為實體附加擴展資料（實體級）

[CommandMethod("AttachEmployeeData")]
public void AttachEmployeeData() {
    Database db = HostApplicationServices.WorkingDatabase;
    using (Transaction tr = db.TransactionManager.StartTransaction()) {
        // 選取一個實體（如文字、圓等）
        PromptEntityResult per = Application.DocumentManager.MdiActiveDocument.Editor.GetEntity("\n選取實體: ");
        if (per.Status != PromptStatus.OK) return;

        DBObject obj = tr.GetObject(per.ObjectId, OpenMode.ForWrite);

        // 確保擴展字典存在
        ObjectId extDictId = obj.ExtensionDictionary;
        if (extDictId == ObjectId.Null) {
            obj.CreateExtensionDictionary();
            extDictId = obj.ExtensionDictionary;
        }

        DBDictionary extDict = (DBDictionary)tr.GetObject(extDictId, OpenMode.ForWrite);

        // 建立 Xrecord 存儲員工資料
        Xrecord xrec = new Xrecord();
        xrec.Data = new ResultBuffer(
            new TypedValue((int)DxfCode.Thickness, "員工姓名"), // 100 字串
            new TypedValue((int)DxfCode.Real, 50000.0),         // 40 雙精度
            new TypedValue((int)DxfCode.Thickness, "Sales")      // 部門
        );

        extDict.SetAt("EMPLOYEE_DATA", xrec);
        tr.AddNewlyCreatedDBObject(xrec, true);
        tr.Commit();
    }
}

讀取自定義資料

[CommandMethod("ReadEmployeeData")]
public void ReadEmployeeData() {
    // ... 選取實體、取得擴展字典 ...
    if (extDict.Contains("EMPLOYEE_DATA")) {
        Xrecord xrec = (Xrecord)tr.GetObject(extDict.GetAt("EMPLOYEE_DATA"), OpenMode.ForRead);
        foreach (TypedValue tv in xrec.Data) {
            // 根據 DxfCode 解析
            Application.DocumentManager.MdiActiveDocument.Editor.WriteMessage($"{tv.TypeCode}: {tv.Value}");
        }
    }
}

關鍵最佳實踐

• 事務管理：所有資料庫讀寫必須在 Transaction 中，確保原子性與一致性。
• OpenMode：ForRead 唯讀，ForWrite 修改，ForNotify 僅通知不鎖定。
• 新物件登記：tr.AddNewlyCreatedDBObject(obj, true) 將新建物件加入事務，第二參數 true 表示自動產生 Handle。
• 資料型別：使用 DxfCode 列舉對應 DXF 群組碼，確保跨版本相容。
• 效能：避免在大量實體上建立龐大擴展字典；共享定義置於 NOD，實體僅存索引鍵。

應用場景

• 圖形標準化：統一圖層、線型、文字樣式定義（NOD）。
• 資產管理：每個圖元附加設備編號、維護記錄、責任人（擴展字典 + Xrecord）。
• 參數化設計：儲存幾何約束、驅動參數、版本歷史。
• 跨系統整合：將 ERP/BIM 資料嵌入 DWG，實現雙向同步。