企业官网建设流程全解析

简介：这份资源是Revit 2019.2二次开发官方案例合集，面向已掌握Revit基础操作、希望借助API扩展软件功能的BIM开发者与工程师，帮助解决插件编写、模型自动化与工作流集成中的实际问题。压缩包共约2000个文件、256.85MB，以1105个C#源码、186个addin清单、167个csproj工程及176个resx资源文件为主，另含VB项目、rvt与rfa模型样例、图标与说明文档，构成可直接编译运行的完整工程结构。147个案例覆盖基本元素创建与修改、参数读写、视图与打印控制、事件响应、外部程序集成及自定义界面等方向，每个案例均附源代码，便于在Visual Studio中逐项调试。已有4468人学习下载，适合作为二次开发入门到进阶的对照练习与排错参考。

1. 从 147 个官方案例里，我挑出了最值得先啃的 3 类

如果你正在做 Revit 2019.2 二次开发，手里攒了一堆零散 API 调用代码，却始终拼不出一个能跑通的完整插件，那这套 147 例官方案例加源代码的价值就不在“数量”，而在“它把 Revit API 的调用边界用可运行的方式标了出来”。我见过太多人卡在同一个地方：知道FilteredElementCollector能取元素，但不知道什么时候该用WhereElementIsNotElementType()，什么时候该用OfClass()，结果写出来的代码要么漏元素，要么性能崩掉。官方案例的好处是，它不跟你讲大道理，直接给你一个.rvt模型加一段.cs，你跑一遍就知道参数该怎么传、事务该怎么包、异常该在哪一层接住。这套东西适合两类人：一是刚过完 Revit API 基础、需要真实场景练手的开发者；二是已经能写单点功能、但想系统补齐“族实例操作、几何提取、参数批量读写、外部事件”这几块短板的老手。147 例不是让你从头到尾抄一遍，而是让你按场景分类去拆，拆完再拼回自己的业务里。

2. 官方案例的目录结构怎么读：先分类，再定位

2.1 按功能域把 147 例切成 6 个可复用的块

拿到一套官方案例，最忌讳按文件夹顺序从 001 看到 147。我一般先按功能域做一次粗分类，把案例归到下面 6 个块里，每个块挑 2 到 3 个典型例子精读，剩下的当字典查。

这个分类不是官方的，是我自己按“改代码时最常回去翻”的频次整理的。你会发现元素查询和事务修改这两块几乎贯穿所有案例，所以它们值得花最多时间。几何提取那块单独拎出来，是因为很多人在Solid转Face再取PlanarFace法向量时翻车，官方案例里给了带Options的完整写法，直接抄能省半天调试。

2.2 用最小命令跑通第一个案例：从编译到看到结果

假设你挑的是“统计当前模型中所有墙的体积”这个案例。不要急着改代码，先按下面步骤把原始案例跑通，确认环境没问题。

# 1. 确认 Revit 2019.2 已安装，且 .NET Framework 版本为 4.7.2 # 2. 用 Visual Studio 打开案例自带的 .sln，检查引用路径 # 重点看 RevitAPI.dll 和 RevitAPIUI.dll 是否指向本机安装目录 # 3. 生成解决方案，输出 .dll 到案例的 addin 目录 # 4. 把 .addin 文件复制到 Revit 的 Addins 文件夹 # 通常路径：C:\ProgramData\Autodesk\Revit\Addins\2019 # 5. 启动 Revit，在附加模块选项卡下找到对应按钮

跑通之后，你会在 Revit 里看到一个按钮，点一下弹出墙体积列表。这一步的意义不是功能本身，而是确认你的编译输出、.addin清单、Revit 版本三者对上了。很多人卡在“按钮不出现”，九成是.addin里的Assembly路径写成了相对路径，或者FullClassName和实际命名空间差了一个字母。官方案例的.addin文件通常写得很规范，直接对照改自己的就行。

2.3 从案例反推 API 调用链：以“批量修改参数”为例

官方案例里有一类专门做参数批量写入的，代码不长，但把事务、参数查找、类型转换三件事串得很清楚。我把它简化成下面这个骨架，你可以在自己的项目里直接套。

// 假设已拿到 doc 和一组 elementIds using (Transaction trans = new Transaction(doc, "BatchSetParam")) { trans.Start(); foreach (ElementId id in elementIds) { Element elem = doc.GetElement(id); // 按名称查找参数，注意 BuiltInParameter 和自定义参数的区别 Parameter param = elem.LookupParameter("Mark"); if (param != null && !param.IsReadOnly) { // 存储类型决定用哪个 Set 方法，字符串参数用 Set(string) param.Set("A-" + id.IntegerValue); } } trans.Commit(); }

这段代码里三个点最容易出错。第一，LookupParameter对自定义参数有效，但对某些内置参数可能返回 null，稳妥做法是先用get_Parameter(BuiltInParameter.ALL_MODEL_MARK)试一次。第二，IsReadOnly判断不能省，否则遇到只读参数直接抛异常，整个事务回滚。第三，Set方法有多个重载，传错类型不会报编译错误，但运行时会静默失败或抛ArgumentException。官方案例里通常会在Set之前加一个StorageType判断，这个习惯建议你保留。

3. 把官方案例改造成自己的插件：四个必须动手的环节

3.1 外部命令与外部应用的入口怎么选

官方案例里两种入口都有。IExternalCommand适合一次性操作，比如导出数据、批量改参数；IExternalApplication适合在 Revit 启动时注册 Ribbon 按钮、绑定外部事件。我一般这样分：如果功能需要用户点按钮触发，用IExternalCommand；如果需要在 Revit 空闲时自动跑，或者要挂接DocumentChanged事件，用IExternalApplication加ExternalEvent。官方案例里有一个“模型更新后自动检查”的例子，用的就是IExternalApplication注册ControlledApplication.DocumentChanged，然后在事件里通过ExternalEvent.Raise()回到主线程操作文档。这个模式在 2019.2 里很稳定，但要注意DocumentChanged触发频率很高，事件处理里不要做重活，否则 Revit 会明显卡顿。

3.2 事务与子事务：什么时候该拆，什么时候该合

官方案例里凡是修改模型的，几乎都包在Transaction里。但有一个细节很多人忽略：如果一个操作里包含多个独立步骤，比如“先删旧墙再建新墙”，最好拆成两个事务，或者用SubTransaction。原因是 Revit 的事务回滚是整体性的，如果第二个步骤失败，第一个步骤的修改也会被撤销。我见过一个案例，批量替换族实例时把删除和新建放在同一个事务里，结果某个类型加载失败，前面删掉的实例全没了，用户直接炸锅。官方案例里对这种情况通常用TransactionGroup或者分步Transaction，你在改造时可以根据业务容忍度决定：能接受整体回滚就合，不能就拆。

3.3 过滤器的性能写法：从 147 例里总结的三条规则

官方案例里元素过滤的写法五花八门，但性能好的写法有共同点。我总结三条：第一，能用OfClass(typeof(Wall))就不要用WhereElementIsNotElementType()加类别判断，前者走的是快速过滤通道。第二，需要按参数值筛选时，先用FilteredElementCollector拿到候选集，再用 LINQ 做内存过滤，不要试图在收集器里做复杂逻辑。第三，如果只需要元素 ID，用WhereElementIsNotElementType().ToElementIds()比ToElements()快很多，因为后者会构造完整元素对象。官方案例里有一个“统计门窗数量”的例子，原始写法用了ToElements()再遍历，我改成ToElementIds()后，在大型模型上耗时从 4 秒降到 0.6 秒。这个改动很小，但效果立竿见影。

3.4 几何提取的坑：Solid 为空、Face 法向量反了怎么办

几何这块是官方案例里最值得精读的部分，因为 Revit 的几何 API 有很多“玄学”行为。比如Element.get_Geometry(Options)返回的Solid可能为空，原因通常是Options.ComputeReferences没设成true，或者元素本身没有几何体（比如某些注释族）。再比如取PlanarFace的法向量时，FaceNormal的方向取决于面的生成方式，有时候指向实体内部，有时候指向外部。官方案例里有一个“判断墙朝向”的例子，它没有直接用FaceNormal，而是用Transform把法向量转到项目坐标系再判断，这样更稳。你在改造时如果发现法向量反了，不要急着取反，先检查Options和Transform的设置。

4. 避坑与排查：官方案例跑不通时先看这 5 条

4.1 现象：编译通过但 Revit 里找不到按钮

原因：.addin文件的Assembly路径写错，或者FullClassName与实际类名不匹配。解决：把.addin里的Assembly改成.dll的绝对路径，FullClassName用“命名空间.类名”格式，注意大小写。另外确认.addin文件放在C:\ProgramData\Autodesk\Revit\Addins\2019下，不是用户目录下的AppData。

4.2 现象：运行时报“事务未打开”或“事务已打开”

原因：在IExternalCommand里修改文档前没有Transaction.Start()，或者嵌套事务时外层没提交就开了内层。解决：所有doc的修改操作必须包在事务里，且事务不能嵌套。如果需要在事务里调用另一个方法，把事务对象传进去，不要在里面再new Transaction。官方案例里通常用using块保证释放，你照做就行。

4.3 现象：参数Set之后值没变，也不报错

原因：参数是只读的，或者存储类型不匹配。解决：先判断param.IsReadOnly，再根据param.StorageType选择Set重载。对于StorageType.String用Set(string)，StorageType.Integer用Set(int)，StorageType.Double用Set(double)。如果参数是共享参数但当前文档没有绑定，LookupParameter会返回 null，需要先绑定再写。

4.4 现象：几何提取返回的 Solid 数量不对

原因：Options的DetailLevel设置影响了几何精度，或者元素被裁剪。解决：把Options.DetailLevel设为ViewDetailLevel.Fine，ComputeReferences设为true。如果还是不对，检查元素是否在视图范围内，get_Geometry返回的是模型几何，不受视图裁剪影响，但某些族实例的几何需要先Activate类型才能取到。

4.5 现象：外部事件里操作文档导致 Revit 崩溃

原因：在非主线程直接调用了 Revit API。解决：所有对Document的修改必须通过ExternalEvent.Raise()回到主线程执行。官方案例里有一个“后台计算完成后更新模型”的例子，它把计算放在Task.Run里，计算完再Raise()，这样既不影响界面响应，也不会崩。注意ExternalEvent的Handler里不要做耗时操作，否则界面会卡。

5. 从 147 例到自己的工具集：一个可复用的验证习惯

官方案例最大的价值不是让你抄完 147 个功能，而是让你在改代码的过程中建立一套自己的验证习惯。我现在的做法是：每从案例里摘一个功能，就写一个最小测试命令，只做一件事，跑通后再合并到主插件里。比如从案例里摘了“批量改参数”，我就单独建一个TestBatchSetParam命令，只对当前选中的三个元素操作，确认事务、参数类型、异常处理都没问题，再把这个逻辑抽成静态方法供其他命令调用。这样做的代价是前期多写几个测试命令，但收益是后期改需求时不用在几百行代码里找哪一行出了问题。

另一个习惯是给每个从案例里学到的 API 调用点加一行注释，写明“这个参数在什么情况下会为 null”“这个返回值在什么版本有变化”。官方案例的代码通常不带这些注释，但你在调试时踩过的坑，记下来就是自己的文档。比如FilteredElementCollector的OfCategory在 2019.2 里对某些类别返回空集合，原因是类别 ID 和BuiltInCategory枚举对不上，这种细节官方案例不会专门讲，但你踩过一次就会记住。

最后说一个我自己的教训：不要试图把 147 例全部跑一遍再开始做项目。我最早就是这么干的，结果跑到第 30 个案例时已经忘了前 20 个在讲什么，时间全花在环境配置上。后来改成按功能域挑 10 到 15 个精读，每个都改一遍、跑一遍、记一遍，反而两周就能上手真实项目。官方案例是字典，不是教材，查比读更重要。希望帮到你。

本文还有配套的精品资源，点击获取