简介：这份资源面向具备一定C#与.NET基础、希望系统掌握Revit二次开发的工程师与BIM从业者，汇集Revit 2019.2版本官方提供的147个开发案例及配套源代码，覆盖元素创建与修改、参数读写、视图与打印控制、事件响应、工作流集成、界面扩展及性能优化等主题，可用于对照学习API调用方式与最佳实践。压缩包共约2000个文件、256.85MB，以cs源码、addin清单、rtf说明、resx资源、csproj工程文件为主，另含rvt与rfa示例模型、vb项目及少量dll、sln解决方案，便于在Visual Studio中直接打开运行调试。目前已有4473人学习下载。每个案例独立成项，读者可借此理解命令注册、外部应用加载与模型交互的完整链路，并规避常见API误用导致的性能问题。
1. 从一份 147 例的 Revit 二次开发案例包说起
接手一个 BIM 插件项目时，最耗时间的往往不是写业务逻辑，而是搞不清 Revit API 里某个接口到底该怎么调、事务边界该放在哪、模型元素怎么过滤才不卡。手头这份 Revit 2019.2 二次开发官方案例包，把 147 个独立示例连同源代码一起摊开，覆盖了从文档读写、元素创建、参数操作到族与视图处理的常见场景。它适合两类人：刚接触 Revit 开发、想照着跑通第一个命令的新手，以及已经在写插件、需要一份可对照的 API 用法索引的老手。下面按「能干什么、怎么跑、怎么改」的顺序拆开讲。
2. 案例包结构与技术栈：147 个示例是怎么组织的
2.1 目录分层与示例编号逻辑
这类官方案例包的组织方式通常比较规整，常见做法是按功能域分文件夹，每个示例一个独立子目录，里面放源码、项目文件和说明。147 个示例不会平铺在一个目录里，而是按「应用级」「文档级」「元素级」「视图与注释」「族与参数」等主题归拢。我一般先看根目录的索引文件或解决方案文件，确认哪些示例能独立编译、哪些依赖共享的公共类库。
典型的目录形态大致是这样：
RevitSamples/ ├── Samples.sln # 总解决方案，聚合全部示例 ├── Common/ # 公共工具类，如命令注册、日志 ├── 01_Application/ # 应用与外部命令入口 ├── 02_Document/ # 文档打开、保存、事务 ├── 03_Element/ # 元素创建、过滤、修改 ├── 04_Parameter/ # 参数读写与共享参数 ├── 05_Family/ # 族加载与族实例 ├── 06_View/ # 视图、注释、标注 └── 07_Advanced/ # 事件、外部事件、模型更新编号前缀是给检索用的，不是执行顺序。真正决定一个示例能不能跑的是它的.addin清单和项目引用。每个示例目录里通常有一个.csproj，引用RevitAPI.dll和RevitAPIUI.dll，这两个程序集来自本机安装的 Revit 2019.2，路径一般在安装目录下。公共类库Common被多个示例引用，改它会影响一片示例，这点后面避坑章节会细说。
2.2 技术栈与运行前提
这套案例的技术栈很集中：C# + .NET Framework 4.7 左右 + Revit 2019.2 API。Revit 2019 系列对 .NET 版本有明确要求，项目文件里的目标框架必须和本机 Revit 运行时匹配，否则加载时会报程序集版本不兼容。开发工具用 Visual Studio 2017 及以上即可，2019 版本对这套老项目兼容性更稳。
运行前提有三条，缺一不可：
- 本机安装 Revit 2019.2，且 API 程序集路径与项目引用一致；
- 示例编译输出的
.dll放到 Revit 能扫描到的插件目录，或通过.addin文件指向输出路径； .addin清单里的Assembly路径、FullClassName与编译产物完全对应。
提示：Revit 2019.2 的 API 程序集默认不开复制到输出目录，项目引用里要把
Copy Local设为False，否则运行时会和 Revit 自带的程序集冲突。
2.3 一个示例的完整构成
拿一个「创建墙体」类示例来说，目录里通常有这些文件：
| 文件 | 作用 |
|---|---|
CreateWallCommand.cs | 实现IExternalCommand的命令入口 |
CreateWall.csproj | 项目文件，含 API 引用与输出配置 |
CreateWall.addin | 插件清单，告诉 Revit 加载哪个类 |
README或注释 | 示例说明与运行前置条件 |
.addin清单是新手最容易忽略的一环，它的结构决定了 Revit 启动时能不能发现这个命令。一个最小清单长这样：
<?xml version="1.0" encoding="utf-8"?> <RevitAddIns> <AddIn Type="Command"> <Name>CreateWallSample</Name> <Assembly>D:\Samples\CreateWall\bin\Debug\CreateWall.dll</Assembly> <FullClassName>CreateWall.CreateWallCommand</FullClassName> <ClientId>11111111-2222-3333-4444-555555555555</ClientId> <VendorId>DEV</VendorId> </AddIn> </RevitAddIns>Assembly必须是绝对路径或相对清单文件的正确相对路径，FullClassName要带完整命名空间。ClientId用任意合法 GUID 即可，但同一台机器上不要和别的插件重复。这三项任何一项写错，Revit 启动时不会报错，命令就是不出来，属于典型的「玄学」问题。
3. 跑通第一个示例：从编译到命令出现在 Ribbon
3.1 环境检查与项目引用修正
拿到案例包后不要急着批量编译，先挑一个最简单的示例单独跑通。打开它的.csproj，检查两个HintPath是否指向本机真实路径：
<Reference Include="RevitAPI"> <HintPath>C:\Program Files\Autodesk\Revit 2019\RevitAPI.dll</HintPath> <Private>False</Private> </Reference> <Reference Include="RevitAPIUI"> <HintPath>C:\Program Files\Autodesk\Revit 2019\RevitAPIUI.dll</HintPath> <Private>False</Private> </Reference>Private为False就是前面说的不复制到输出目录。如果本机 Revit 装在别的盘符或用了不同的小版本目录，把这两行路径改掉即可。改完先编译，编译通过说明引用没问题；编译报「找不到类型或命名空间」，多半是目标框架版本不对，把项目属性里的目标框架调到与本机一致的 .NET Framework 版本。
3.2 命令入口的标准写法
所有示例的命令入口都遵循IExternalCommand接口。一个带事务的创建类命令，骨架大致如下：
using Autodesk.Revit.Attributes; using Autodesk.Revit.DB; using Autodesk.Revit.UI; namespace CreateWall { [Transaction(TransactionMode.Manual)] [Regeneration(RegenerationOption.Manual)] public class CreateWallCommand : IExternalCommand { public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements) { UIDocument uidoc = commandData.Application.ActiveUIDocument; Document doc = uidoc.Document; // 事务必须显式开启，TransactionMode.Manual 下不会自动提交 using (Transaction tx = new Transaction(doc, "Create Wall")) { tx.Start(); try { Wall.Create(doc, Line.CreateBound( new XYZ(0, 0, 0), new XYZ(10, 0, 0)), Level.Create(doc, 0).Id, false); tx.Commit(); } catch (Exception ex) { tx.RollBack(); message = ex.Message; return Result.Failed; } } return Result.Succeeded; } } }这段代码有三个关键点。TransactionMode.Manual表示事务由代码自己管，忘记tx.Start()会直接抛异常；Wall.Create的第二个参数是定位线，必须用Line.CreateBound而不是直接 new；Level.Create(doc, 0)在已有标高为 0 的文档里会重名，实际示例里通常先查已有标高再复用。message和elements是 Revit 回传错误信息的通道，失败时把异常写进message，用户能在界面上看到原因。
3.3 加载与验证
编译出.dll后，把.addin清单放到 Revit 的插件扫描目录，通常是%APPDATA%\Autodesk\Revit\Addins\2019。启动 Revit，在「附加模块」选项卡下找对应按钮。如果命令没出现，按这个顺序排查：清单文件名是否以.addin结尾、XML 是否格式正确、Assembly路径是否存在、FullClassName是否和代码里的命名空间类名完全一致。这四步能解决绝大多数「命令不显示」的问题。
命令出现后点一下，看是否弹出预期结果。创建类示例建议在空白项目文件里跑，避免在真实模型上误操作。跑通一个之后，再按主题批量编译其余示例，遇到编译失败的单独处理，不要一次性全量编译后被一堆错误淹没。
4. 核心模块拆解：元素过滤、参数读写与事务边界
4.1 元素过滤器的三种写法与性能差异
147 个示例里出现频率最高的操作是「找到某类元素」。Revit API 提供三种过滤路径：FilteredElementCollector链式过滤、ElementClassFilter组合、以及基于ElementParameterFilter的参数过滤。写法不同，性能差距在大型模型上很明显。
// 写法一：按类别快速过滤，最常用 var walls = new FilteredElementCollector(doc) .OfCategory(BuiltInCategory.OST_Walls) .WhereElementIsNotElementType() .ToElements(); // 写法二：按参数值过滤，适合查特定标记的元素 var paramFilter = new ElementParameterFilter( ParameterFilterRuleFactory.CreateEqualsRule( new ElementId(BuiltInParameter.ALL_MODEL_MARK), "A-01")); var marked = new FilteredElementCollector(doc) .WherePasses(paramFilter) .ToElements();第一种写法先按类别缩小范围，再排除类型元素，是官方示例里最常见的组合。第二种把参数条件交给 Revit 内部执行，比取回全部元素后在 C# 里Where过滤快得多。血泪经验是：不要在FilteredElementCollector之后接复杂的 LINQ 再ToList()，能下推到 API 层的条件尽量下推，否则大模型上遍历几万个元素会明显卡顿。
4.2 参数读写的类型陷阱
参数操作看似简单，实际坑最多。Revit 参数分实例参数和类型参数，取值接口有AsString、AsDouble、AsElementId等多种，用错方法拿到的是空值或错误单位。
Parameter p = element.LookupParameter("注释"); if (p != null && p.StorageType == StorageType.String) { string oldValue = p.AsString(); using (Transaction tx = new Transaction(doc, "Set Comment")) { tx.Start(); p.Set("已复核"); tx.Commit(); } }StorageType必须先判断，字符串参数用AsDouble会抛异常。长度类参数存的是内部单位（英尺），显示值和存储值之间要换算，直接Set(3000)得到的不是 3000 毫米。共享参数还要先确认参数绑定到了目标类别，LookupParameter返回null时先查绑定关系，而不是怀疑代码写错。
4.3 事务与子事务的边界控制
事务边界是 Revit 二次开发里最容易翻车的地方。一个事务里做太多操作，失败回滚代价大；事务开得太碎，性能又差。常见做法是按「一次用户操作」划事务，批量修改时用TransactionGroup包住多个事务，整体成功再统一提交。
using (TransactionGroup tg = new TransactionGroup(doc, "Batch Update")) { tg.Start(); foreach (var id in elementIds) { using (Transaction tx = new Transaction(doc, "Update One")) { tx.Start(); // 单个元素修改 tx.Commit(); } } tg.Assimilate(); // 全部成功才合并，任一失败可整体回滚 }Assimilate把组内事务合并成一个可回滚单元，适合「要么全改要么全不改」的场景。注意事务内不要弹模态对话框或做长时间 IO，Revit 在事务未提交时对界面操作很敏感，容易引发不可预期的状态。
5. 避坑与常见问题：命令不显示、事务报错、版本不兼容
5.1 命令在 Ribbon 里找不到
现象：Revit 启动正常，附加模块选项卡下没有目标按钮。原因通常是.addin清单问题：文件没放在Addins\2019目录、XML 有语法错误、Assembly路径指向不存在的文件、FullClassName拼写和实际类不一致。解决：先用浏览器打开清单确认 XML 合法，再逐项核对路径和类名，最后看 Revit 日志目录下有没有加载失败记录。清单里ClientId重复也会导致后加载的插件被忽略。
5.2 运行时报「事务未开启」
现象：点击命令后弹出异常，提示需要在事务中修改文档。原因：命令类标了TransactionMode.Manual，但代码里直接调用了修改模型的方法，没有tx.Start()。解决：所有写操作包进Transaction，读操作不需要。如果用了TransactionMode.Automatic，Revit 会自动开事务，但这种方式在复杂命令里不好控制回滚粒度，官方案例基本都用Manual。
5.3 批量编译时大量示例失败
现象：单独编译某个示例成功，全量编译时一片红。原因：多个示例引用了Common公共类库，公共类库的目标框架或 API 引用版本和部分示例不一致；或者示例之间有同名类冲突。解决：先单独编译Common，确认它通过后再编译依赖它的示例；同名类冲突时检查各示例的命名空间是否重复，必要时改命名空间而不是删代码。
5.4 在真实模型上跑示例导致模型异常
现象：示例在空白文件里正常，在项目模型上跑完出现元素错位或参数被改。原因：示例代码多为演示用途，硬编码了坐标、标高或参数名，真实模型里这些假设不成立。解决：跑任何写操作示例前先备份模型，优先在副本上验证；把示例里的硬编码值改成从当前文档动态获取，比如标高按名称查找而不是按 Id 写死。
6. 二次开发改造：把示例代码变成可维护的插件骨架
示例代码的价值不在直接上线，而在提供可复用的调用范式。我改造这类案例包的习惯是：先抽一个公共层，把事务封装、参数读写、元素查找做成工具方法，再让各命令只写业务差异部分。下面这个封装把「在事务里执行并统一处理异常」固化下来，命令里就不用反复写 try-catch 和回滚。
public static class RevitTask { // 统一事务执行器：成功提交，失败回滚并回传错误信息 public static Result RunInTransaction(Document doc, string name, Action<Document> action, ref string message) { using (Transaction tx = new Transaction(doc, name)) { tx.Start(); try { action(doc); tx.Commit(); return Result.Succeeded; } catch (Exception ex) { tx.RollBack(); message = $"[{name}] {ex.Message}"; return Result.Failed; } } } }命令入口随之简化成一行调用，业务逻辑放进 lambda。改造时还有两个验证方法值得坚持：一是每改一个示例，先在空白模型上跑通再上真实模型；二是给每个命令加一个「只读预检」分支，先统计会影响多少元素，用户确认后再执行写操作。这样即使逻辑有偏差，也能在写入前拦住。
参数相关的改造建议单独建一个映射表，把业务字段名和 Revit 参数名、存储类型对应起来，避免散落在各命令里的字符串硬编码。表格形式大致如下：
| 业务字段 | Revit 参数名 | 存储类型 | 单位换算 |
|---|---|---|---|
| 构件编号 | 标记 | String | 无 |
| 设计长度 | 长度 | Double | 英尺转毫米 |
| 所属楼层 | 标高 | ElementId | 按名称查找 |
有了这张表，参数读写就变成查表加类型分派，新增字段只改表不改命令。从那以后我每次接手新的 Revit 案例包，都强制先跑通一个最小示例、再抽公共层、最后才批量改造，顺序颠倒过一次，返工花了两天。希望这套拆法能帮到你，案例包里的 147 个示例足够当一段时间的 API 对照手册用。
本文还有配套的精品资源，点击获取
