常见陷阱与最佳实践

Revit

常见陷阱与最佳实践

本章汇总 Revit 二次开发中最常见的陷阱和推荐工作方式，涵盖从 API 误用到架构设计的方方面面。

陷阱 1：在外部事件处理中创建事务

// ❌ 错误：在 DocumentChanged 等事件中创建新事务
app.DocumentChanged += (s, e) =>
{
    Document doc = e.GetDocument();
    using (Transaction tx = new Transaction(doc, "反应"))
    {
        tx.Start();    // 💥 异常！Revit 的事务尚未完成
        // ...
    }
};

// ✅ 正确：使用 IExternalEventHandler 延迟处理
public class MyEventHandler : IExternalEventHandler
{
    public void Execute(UIApplication app)
    {
        Document doc = app.ActiveUIDocument.Document;
        using (Transaction tx = new Transaction(doc, "处理"))
        {
            tx.Start();
            // 安全修改
            tx.Commit();
        }
    }

    public string GetName() => "MyHandler";
}

// 在事件中触发
var handler = new MyEventHandler();
var extEvent = ExternalEvent.Create(handler);
app.DocumentChanged += (s, e) => extEvent.Raise();

陷阱 2：单位混淆（英尺 vs 毫米）

// ❌ 错误：直接使用毫米值
Wall.Create(doc, curve, wallType.Id, level.Id,
    4000.0,   // 💥 这是 4000 英尺 ≈ 1219 米！
    0, false, false);

// ✅ 正确：转换为英尺
double heightFeet = UnitUtils.ConvertToInternalUnits(4000.0, UnitTypeId.Millimeters);
Wall.Create(doc, curve, wallType.Id, level.Id, heightFeet, 0, false, false);

// ✅ 读取时也需转换
double lengthFeet = wall.get_Parameter(BuiltInParameter.CURVE_ELEM_LENGTH).AsDouble();
double lengthMm = UnitUtils.ConvertFromInternalUnits(lengthFeet, UnitTypeId.Millimeters);

🔬 Revit 内部始终使用英尺。这源于 Revit 基于美国建筑行业开发的历史。

陷阱 3：在 ForgeTypeId 错误时混用 DisplayUnitType

// Revit 2022+ 推荐使用 ForgeTypeId
double mm = UnitUtils.ConvertFromInternalUnits(
    feetValue, UnitTypeId.Millimeters);                   // ✅ 新 API

// 旧版 API（Revit 2021 及以下）
double mm = UnitUtils.ConvertFromInternalUnits(
    feetValue, DisplayUnitType.DUT_MILLIMETERS);          // ✅ 旧 API

💡 如果目标 Revit 版本可能是 2022+ 和多版本兼容，检查 UnitUtils 的方法签名或使用条件编译。

陷阱 4：Commit 后立即使用元素引用

// ✅ 事务提交后元素引用仍然有效（与 AutoCAD 不同！）
Wall wall;
using (Transaction tx = new Transaction(doc, "创建"))
{
    tx.Start();
    wall = Wall.Create(doc, curve, wallType.Id, level.Id, 10, 0, false, false);
    tx.Commit();
}
// wall 仍然可以读取信息
string name = wall.Name;   // ✅ 可以

// 但修改仍然需要新事务
using (Transaction tx = new Transaction(doc, "修改"))
{
    tx.Start();
    wall.get_Parameter(BuiltInParameter.ALL_MODEL_INSTANCE_COMMENTS).Set("备注");  // ✅
    tx.Commit();
}

💡 与 AutoCAD 不同，Revit 的事务提交后，元素引用不会失效。但修改操作仍然需要新事务。

陷阱 5：类型未激活就创建实例

// ❌ 如果 FamilySymbol.IsActive == false，NewFamilyInstance 会失败
FamilySymbol symbol = GetFamilySymbol(doc, "门", "0915×2100mm");
FamilyInstance door = doc.Create.NewFamilyInstance(point, symbol, level, StructuralType.NonStructural);
// 💥 可能抛出异常

// ✅ 先激活
if (!symbol.IsActive)
    symbol.Activate();
FamilyInstance door = doc.Create.NewFamilyInstance(point, symbol, level, StructuralType.NonStructural);
doc.Regenerate();   // 推荐激活后再生

陷阱 6：遍历中删除元素

// ❌ 遍历中删除
var elements = new FilteredElementCollector(doc)
    .OfClass(typeof(FamilyInstance))
    .ToElements();

foreach (Element elem in elements)
{
    if (elem.Name.Contains("旧"))
        doc.Delete(elem.Id);      // 💥 可能导致迭代器失效
}

// ✅ 收集 ID，批量删除
var idsToDelete = new FilteredElementCollector(doc)
    .OfClass(typeof(FamilyInstance))
    .WhereElementIsNotElementType()
    .Cast<FamilyInstance>()
    .Where(fi => fi.Name.Contains("旧"))
    .Select(fi => fi.Id)
    .ToList();

doc.Delete(idsToDelete);    // 一次性批量删除

陷阱 7：大量使用 Where() 而不是过滤链

// ❌ 慢：把所有元素加载到内存再用 LINQ Where
var walls = new FilteredElementCollector(doc)
    .WhereElementIsNotElementType()
    .Where(e => e is Wall)
    .Where(e => e.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET)?.AsDouble() > 0)
    .ToList();

// ✅ 快：先用快速过滤缩小范围，再用 Where
var walls = new FilteredElementCollector(doc)
    .OfClass(typeof(Wall))          // 快速（数据库层）
    .WhereElementIsNotElementType() // 快速
    .ToElements()                   // ← 此时已大幅缩小范围
    .Where(e => e.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET)?.AsDouble() > 0)
    .ToList();

⚡ 规则：链式调用中，先放所有快速过滤方法（OfClass、OfCategory、WherePasses），最后再放 Where() Lambda。

陷阱 8：忘记 UpdateDocument 导致 RevitLookup 显示过时数据

这个问题常见于调试时——你修改了元素，但在 Revit 界面中看不到更新：

// 修改参数或几何后，需要通知 Revit 更新
doc.Regenerate();              // 再生模型
uidoc.RefreshActiveView();     // 刷新视图显示
uidoc.UpdateAllOpenViews();   // 更新所有打开视图

陷阱 9：使用 TaskDialog 在循环中

// ❌ 循环中弹窗 —— 让用户发疯
foreach (Wall wall in walls)
{
    TaskDialog.Show("提示", $"处理 {wall.Name}");   // 💥
}

// ✅ 累积信息，最后一次性展示
var sb = new StringBuilder();
foreach (Wall wall in walls)
{
    sb.AppendLine($"处理 {wall.Name}");
}
TaskDialog.Show("处理结果", sb.ToString());

陷阱 10：.addin 文件路径硬编码

<!-- ❌ 硬编码绝对路径 -->
<Assembly>C:\Users\Willow\Source\MyAddin.dll</Assembly>

<!-- ✅ 使用相对路径（相对于 .addin 文件所在目录） -->
<Assembly>MyAddin.dll</Assembly>

<!-- 或使用 AddInFolder 变量 -->
<Assembly>%RevitAddInFolder%\MyAddin.dll</Assembly>

最佳实践清单

事务

💡 使用 TransactionMode.Manual + RegenerationOption.Manual（除非特简单场景）
💡 用 using 包裹所有事务（自动回滚未提交事务）
💡 批量修改时使用 SubTransaction 隔离单元素失败
💡 事件处理器中不创建事务，用 IExternalEventHandler
💡 只读命令用 TransactionMode.ReadOnly

性能

💡 先用快速过滤（OfClass/OfCategory/WherePasses），再 Where() Lambda
💡 批量修改在一个事务中完成，减少再生次数
💡 WhereElementIsNotElementType() 只取实例时始终加上
💡 避免在循环中反复 get_Parameter()，提取结果到局部变量
💡 doc.GetElement(id) 有缓存——多次获取同一元素几乎无开销

稳定性

💡 命令入口 try-catch 并返回 Result.Failed（不抛出未处理异常）
💡 使用 parameter?.HasValue == true 检查参数有效性
💡 删除前检查元素是否存在
💡 检查 ActiveUIDocument 是否为 null（无打开文档时）

部署

💡 使用 .addin 清单文件，不要用 NETLOAD
💡 Copy Local = False
💡 ClientId 使用唯一 GUID
💡 发布前 Release 编译

AutoCAD vs Revit 开发差异速查

维度	AutoCAD	Revit
加载方式	NETLOAD 或 bundle	.addin 清单文件
命令入口	`[CommandMethod]` 特性	`IExternalCommand` 接口
事务	Transaction（不强制依赖）	Transaction（强制）
对象生命周期	事务外立即失效	事务提交后仍可用
元素访问	ObjectId + GetObject	ElementId + GetElement
过滤器	SelectionFilter + DXF	FilteredElementCollector
几何操作	直接的实体创建（Line, Circle）	不能直接创建 Element，需走 API
坐标单位	用户定义（mm/inch 等）	内部始终为英尺
撤销粒度	每步操作独立	每事务一个撤销步骤
UI 注册	CUI/CUIX 文件	IExternalApplication.OnStartup
事件处理	直接在事件中操作	需通过 IExternalEventHandler

必备工具推荐

工具	用途	地址
RevitLookup	查看元素属性/参数/几何	GitHub (jeremytammik/RevitLookup)
Add-In Manager	热加载/卸载插件（无需重启 Revit）	Autodesk SDK
RevitShell	交互式执行 C# 代码	GitHub (weiyen/RevitShell)
pyRevit	Python 脚本框架（含开发者工具）	GitHub (eirannejad/pyRevit)
Revit SDK	官方示例 + 文档	Autodesk Developer Center
Revit API Docs	在线 API 文档	revitapidocs.com

用户界面与 Ribbon