revit api 事务与事务组

在 Revit API 开发中，理解事务（Transaction）、事务组（TransactionGroup）及文档再生（Regenerate）的机制是确保操作正确性和效率的核心。以下从三者的作用、使用场景、代码示例及核心区别展开说明：

一、`Document.Regenerate()`：强制同步文档状态

Regenerate() 是 Document 类的方法，用于强制刷新文档的内部状态，确保所有未生效的修改（如参数变更、元素创建/删除）被应用。

核心作用：在事务内，部分修改（如参数设置、元素几何信息更新）可能处于“待处理”状态，Regenerate() 会触发文档重新计算，将这些修改同步到数据库和 UI，避免后续操作依赖旧状态。
使用场景：
1. 事务内修改参数后需立即读取最新值；
2. 创建元素后需获取其边界框、几何信息等依赖实时状态的数据；
3. 批量修改后需确保中间状态正确，供后续步骤使用。

注意事项：

必须在事务内调用，否则会抛出异常；
频繁调用会降低性能，建议在一系列修改后集中调用一次。

using (Transaction trans = new Transaction(doc, "修改并读取参数"))
{trans.Start();// 修改墙的高度参数Wall wall = ...;Parameter heightParam = wall.get_Parameter(BuiltInParameter.WALL_USER_HEIGHT_PARAM);heightParam.Set(3000); // 设置新值（暂未生效）// 若不调用 Regenerate()，此处可能读取到旧值doc.Regenerate(); // 读取最新参数值double newHeight = heightParam.AsDouble();trans.Commit(); // 提交时自动再生，无需额外调用
}

二、多个独立事务（`Transaction`）：拆分独立操作

一个程序中可以使用多个独立事务，每个事务是一个独立的操作单元，由 Start() 启动，Commit() 提交（修改生效）或 Rollback() 回滚（取消修改）。

核心特性：
- 事务间相互独立，前一个事务的提交结果不会被后一个事务的失败影响；
- 每个事务提交后，修改立即永久生效，UI 同步更新，且无法通过 API 撤回（需用户手动 Undo）。
适用场景：
- 拆分无强关联的逻辑步骤（如“创建元素”“修改参数”“添加标注”）；
- 避免长事务导致的性能问题（如批量操作拆分为多个小事务，逐步释放资源）；
- 依赖前序操作的最终状态（如创建元素后，需通过 FilteredElementCollector 重新获取元素，而 collector 依赖已提交的状态）。

注意事项：

不支持嵌套事务（一个事务未提交时启动另一个事务会报错）；
过多事务可能因频繁触发内部再生而增加性能开销，需平衡拆分粒度。

// 事务1：创建墙（提交后立即生效）
using (Transaction trans1 = new Transaction(doc, "创建墙"))
{trans1.Start();Wall wall = Wall.Create(doc, curve, levelId, false);trans1.Commit(); // 墙已永久保存到文档，UI 显示
}// 事务2：修改墙的材质（依赖事务1的结果）
using (Transaction trans2 = new Transaction(doc, "修改墙材质"))
{trans2.Start();// 通过 ID 获取已创建的墙（事务1已提交，可安全获取）Wall wall = doc.GetElement(wallId) as Wall;Parameter materialParam = wall.get_Parameter(BuiltInParameter.WALL_MATERIAL_PARAM);materialParam.Set(materialId); // 修改材质trans2.Commit(); // 材质修改生效，UI 同步更新
}

三、事务组（`TransactionGroup`）：打包原子操作

事务组用于将多个事务“打包”为一个逻辑单元，组内所有事务的修改需通过组的 Commit() 最终生效，支持整体回滚，确保多步操作的原子性（“要么全成，要么全败”）。

核心特性：
- 组内子事务的 Commit() 仅使修改“临时生效”（未写入最终文档）；
- 事务组的 Rollback() 可撤销所有子事务的临时修改，包括 UI 显示的内容；
- 显示模式（TransactionGroupMode）控制子事务提交后的 UI 反馈：
  - Manual（默认）：子事务提交后 UI 不显示修改，仅组提交后一次性刷新；
  - Automatic：子事务提交后 UI 即时显示修改，但仍为临时状态，组回滚时同步撤销。

适用场景：

多步操作必须整体成功（如批量导入数据、复杂构件创建），避免部分成功导致的文档不一致；
需要预览中间结果（自动模式），同时保留“一键撤销所有操作”的能力。

using (TransactionGroup tg = new TransactionGroup(doc, "创建并配置墙"))
{// 自动模式：子事务提交后 UI 即时显示修改（临时状态）tg.Start(TransactionGroupMode.Automatic);// 子事务1：创建墙（临时提交）Wall wall = null;using (Transaction t1 = new Transaction(doc)){t1.Start("创建墙");wall = Wall.Create(doc, curve, levelId, false);t1.Commit(); // 墙在 UI 中显示（临时状态）}// 子事务2：修改墙高度（临时提交）using (Transaction t2 = new Transaction(doc)){t2.Start("修改高度");Parameter heightParam = wall.get_Parameter(BuiltInParameter.WALL_USER_HEIGHT_PARAM);heightParam.Set(4000); // 高度改为4米t2.Commit(); // UI 中墙高度即时更新（仍为临时状态）}// 若操作有误，调用 Rollback() 撤销所有修改（墙消失，UI 回滚）// tg.Rollback();// 所有子事务确认无误后，提交事务组（修改永久生效）tg.Commit();
}

四、核心区别总结

维度	多个独立事务	事务组（TransactionGroup）	`Regenerate()`
作用	拆分独立操作，各自生效	打包多步操作，确保原子性（全成或全败）	强制同步事务内的文档状态
生效时机	单个事务 `Commit()` 后立即永久生效	子事务 `Commit()` 临时生效，组 `Commit()` 后永久生效	调用后立即同步事务内的中间状态
回滚范围	仅能回滚当前未提交的单个事务	可回滚组内所有子事务的临时修改	无回滚功能，仅同步状态
UI 反馈	提交后即时显示，不可通过 API 撤销	取决于模式（自动模式即时显示，可被组回滚撤销）	同步事务内状态，可能触发 UI 局部刷新
典型场景	无强关联的分步操作	需整体成功的复杂操作（如批量建模）	事务内依赖实时状态的操作（如读取几何信息）

综上，开发时需根据操作的关联性、原子性需求及性能考量选择合适的机制：独立事务适合灵活拆分，事务组适合确保整体一致性，而 Regenerate() 则是事务内同步状态的关键工具。

在 Revit API 中，事务组（TransactionGroup）的 Assimilate() 方法是一个特殊的提交方式，它与普通的 Commit() 不同，核心作用是将事务组内的所有子事务“合并”为一个单独的操作记录，而非保留每个子事务的独立历史记录。

`Assimilate()` 的特性

合并历史记录
当调用 Assimilate() 时，事务组内的所有子事务会被视为一个“整体操作”，在 Revit 的撤销历史（Undo 栈）中仅留下一条记录。而 Commit() 会保留每个子事务的独立历史记录，允许单独撤销某个子事务。
最终生效逻辑
与 Commit() 类似，Assimilate() 会使组内所有子事务的临时修改永久生效，但区别在于历史记录的合并。
适用场景
适合需要将多步操作“打包”为一个不可拆分的历史记录的场景，例如：
- 批量创建元素（如生成 100 个柱子），希望用户 Undo 时一次性撤销所有柱子，而非逐个撤销；
- 复杂逻辑操作（如“创建墙 → 开洞 → 添加装饰”），用户无需关心中间步骤，只需整体撤销。

代码示例：`Assimilate()` 与 `Commit()` 的对比

（1）使用 `Assimilate()`

using (TransactionGroup tg = new TransactionGroup(doc, "批量创建并修改墙"))
{tg.Start(TransactionGroupMode.Automatic);// 子事务1：创建墙Ausing (Transaction t1 = new Transaction(doc)){t1.Start("创建墙A");Wall.Create(doc, curveA, levelId, false);t1.Commit();}// 子事务2：创建墙Busing (Transaction t2 = new Transaction(doc)){t2.Start("创建墙B");Wall.Create(doc, curveB, levelId, false);t2.Commit();}// 调用 Assimilate()：合并为一条历史记录tg.Assimilate(); 
}
// 结果：Revit 的 Undo 栈中仅显示 "批量创建并修改墙"，撤销时会同时删除墙A和墙B

（2）使用 `Commit()`

using (TransactionGroup tg = new TransactionGroup(doc, "批量创建并修改墙"))
{tg.Start(TransactionGroupMode.Automatic);// 子事务1：创建墙Ausing (Transaction t1 = new Transaction(doc)){t1.Start("创建墙A");Wall.Create(doc, curveA, levelId, false);t1.Commit();}// 子事务2：创建墙Busing (Transaction t2 = new Transaction(doc)){t2.Start("创建墙B");Wall.Create(doc, curveB, levelId, false);t2.Commit();}// 调用 Commit()：保留子事务历史tg.Commit(); 
}
// 结果：Revit 的 Undo 栈中会显示 "创建墙B"、"创建墙A"、"批量创建并修改墙"，
// 可逐个撤销（先撤销墙B，再撤销墙A）

关键区别

方法	历史记录处理	撤销行为	适用场景
`Commit()`	保留所有子事务的独立记录	可按子事务顺序逐个撤销	需要细粒度撤销中间步骤的场景
`Assimilate()`	合并所有子事务为一条记录	只能整体撤销整个事务组的操作	需将多步操作视为一个整体的场景