简介Revit 2019.2二次开发官方案例合集合计收录147个官方示例及完整源代码面向希望系统掌握Revit插件开发的工程师也适合BIM二次开发初学者由浅入深地学习。案例覆盖基础元素创建与修改、参数读写与关联、视图显示控制、事件响应、工作集协作以及同Excel、BIM 360等外部系统的交互与集成并分别给出C#与VB.NET两种语言实现。压缩包内总计2000个文件、约256.85MB以1105个C#源代码文件为核心辅以插件注册配置、项目工程文件、界面资源等配套文件另含RVT、RFA模型样例供对照验证目录结构与开发环境工程一一对应。资源发布以来累计已有4470人学习下载在同类二次开发资料中关注度较高。借助这些官方示例可以逐步梳理外部命令从编写、注册到功能面板扩展的完整流程学习官方推荐代码范式规避常见API误用陷阱从而切实提升实际项目中的Revit二次开发效率。1. 为什么这 147 例官方案例值得当成二次开发骨架来拆说个直接点的结论学 Revit 二次开发最忌讳的是对着 API 文档从头背。文档只告诉你某个方法“能做什么”不告诉你它在一个真实的建模场景里“该怎么配合着用”。这套 147 例的官方案例源代码每一条都长着工程痛点的样子怎么在墙上开洞、怎么遍历体量、怎么给尺寸标注加事件、怎么在族文档里改几何。每个例子都能单独编译、单独运行实际上比很多培训视频值得刷因为你能直接看到官方封装的边界和惯例。它的适用人群很明确正在维护某个 Revit 插件、想给建模工具加自动化能力或者要带新人快速建立二次开发范式的开发者。核心问题就一个——把“API 去哪查”变成“用法在哪抄”。2. 案例包怎么组织解压结构、编译入口和三类引用关系2.1 先从目录结构认出“哪部分值得抄”这类资源解压后通常不是一个大而全的工程而是十几个小主题目录每个主题目录里又分散着若干样例每个样例有自己的 .csproj入口类基本都实现IExternalCommand或IExternalApplication。这是官方刻意保留的颗粒度——Revit 插件打包时按命令拆分方便你在不改别人代码的前提下挑单个文件出来复用。我一般不会直接开最外层的解决方案文件而是先跑一条命令把目录树拍平做一份“项目清单”find ./ -type f -name *.csproj | sed s#/# - #g | sort projects.txt wc -l projects.txt grep -i -E (geometry|volume|wall|window) projects.txt第一行把所有工程文件名拉平到一行第二行统计总数确认资源里的样例数量和你预期是否一致第三行用关键词先过滤出你最关心的主题。这一步花不了两分钟但能让你快速建一个类似索引的东西后面查具体代码时就有一个稳定路径。解压后的典型布局通常会有下面几类东西目录/文件作用我的使用方式加载工具目录免写 .addin 直接跑样例的命令调试单例时优先用省去反复重启文档目录API 说明与版本差异说明主要查方法签名和废弃提示样例源码目录按文档、几何、族、UI 等主题分开90% 的时间在这里翻代码示例数据目录供样例读取的 RVT 文件跑几何类样例时先打开对应文件资源实物不用过于关心文件大小关键是你得知道入口在哪。看到一堆.sln时克制一下不要全量编译按需打开单个工程文件能省非常多心智负担。2.2 147 例不全是“独立按钮”而是按功能切成四大块把整套样例摊开归纳会自然出现几个规律。大约三分之一围绕文档与视图操作三分之一是几何计算与族操作剩下的是界面交互、外部事件与文档关联。这个分层对做实际工具的人很重要如果只是接一个测量命令根本不需要先读 50 个 UI 例子直接从几何那组切入即可如果要批量导出明细则优先读文档那组因为里面涉及如何用过滤器收集元素以及事务的范围控制。官方案例里被大量复用的也是一个三层结构命令层只拿UIDocument和Document业务逻辑放进公共类数据输出放到外部接口。很多后来被诟病“容易崩”的开发恰恰是把三层混写在一起。比如在Execute里既做几何遍历又写文件再改参数一旦中间出错整个外部命令直接抛异常Revit 就可能把 UI 卡住。// 我习惯的样例解读顺序先看命令入口边界再看内部封装 public class GeometrySample : IExternalCommand { public Result Execute( ExternalCommandData commandData, ref string message, ElementSet elements) { // 命令层只负责取文档、校验状态、调用内部方法 Document doc commandData.Application.ActiveUIDocument.Document; if (doc null) return Result.Failed; return GeometryLibrary.Process(doc, out message); } }这样的好处是你后续把它改成按钮命令时只需替换Execute里的调用业务方法可以直接搬到自己的类库里。判断一个样例值不值得抄就看它是否满足这个“薄命令层厚逻辑层”的结构。凡是把所有代码塞进Execute的一般建议自己重写。2.3 编译前置条件引用 RevitAPI 时的三个细节Revit 2019.2 环境下多数样例只需要三个引用RevitAPI.dll提供文档、元素、几何等基础模型RevitAPIUI.dll提供 Ribbon、面板、对话框等 UI 能力RevitAddInUtility.dll是加载配置辅助。工程目标框架统一选 .NET Framework 4.7这是 2019 这一代对应版本选 4.8 不是不行但没必要引入额外变量。PropertyGroup TargetFrameworkVersionv4.7/TargetFrameworkVersion /PropertyGroup ItemGroup Reference IncludeRevitAPI SpecificVersionFalse/SpecificVersion HintPath$(ProgramFiles)\Revit 2019\RevitAPI.dll/HintPath PrivateFalse/Private /Reference Reference IncludeRevitAPIUI SpecificVersionFalse/SpecificVersion HintPath$(ProgramFiles)\Revit 2019\RevitAPIUI.dll/HintPath PrivateFalse/Private /Reference /ItemGroup这里有一个新手很容易忽视的坑PrivateFalse/Private的意思是“不要把这个程序集复制到本地输出目录”。官方推荐的惯例就是只引用不复制因为 Revit 启动时会从安装目录加载自己的 RevitAPI如果你把同名 DLL 复制到插件目录就容易出现“程序集加载冲突”或者“类型放在两个程序集里”的诡异报错。第二个细节是SpecificVersion设为 False。官方样例中引用特定的 2019 版本但实际工厂环境里可能装的是 2019 加上 2019.2 升级包。程序集的版本号在升级后会变如果写死编译没问题运行时却可能因为强签名版本不匹配而拒绝加载。设成 False 的意义就在于让 CLR 按名字去找不纠结次版本差异。第三个细节是 32 位与 64 位。只要 Revit 是 64 位项目平台的 AnyCPU 通常没问题但如果有依赖的原生库建议显式改成 x64避免在 Debug 下“坏映像”或者“试图加载格式不正确的程序”。把这些前置条件处理完就可以开始跑第一个例子了。3. 先跑通“外部命令”样例从源码到 Revit 面板只要四个操作3.1 挑一个最小命令空壳替换成自己的逻辑官方案例里最常见的入门样本就是这样一个建墙命令。它足够短能完整看到命令入口、事务处理和返回值三段结构。我把典型实现整理成下面这样建议你新建一个类库项目后直接贴进去using Autodesk.Revit.DB; using Autodesk.Revit.UI; using Autodesk.Revit.Attributes; [Transaction(TransactionMode.Manual)] public class CreateWallSample : IExternalCommand { public Result Execute( ExternalCommandData commandData, ref string message, ElementSet elements) { Document doc commandData.Application.ActiveUIDocument?.Document; if (doc null) { message 请先打开一个项目文档。; return Result.Failed; } using (Transaction tx new Transaction(doc, 建一面测试墙)) { tx.Start(); Wall.Create(doc, Line.CreateBound(new XYZ(0, 0, 0), new XYZ(10, 0, 0)), null, false); tx.Commit(); } return Result.Succeeded; } }解读几个关键参数[Transaction(TransactionMode.Manual)]表示这个命令自己管理事务你必须在代码里显式调用 Start 和 Commit。ref string message是向 Revit 回传的报错信息界面下方状态栏会直接显示这段文字。Wall.Create的第三个参数是所在标高的 ElementId传null表示用默认标高很多刚入门的人在这里直接取doc.ActiveView.GenLevel结果在没有可用标高的三维视图里调用时直接抛空引用。new Line.CreateBound(...)里的两个 XYZ第一个是起点第二个是终点。Revit 数据库里的长度单位是英尺所以(10, 0, 0)是 10 英尺不是 10 毫米。这一点在刚接触 API 时最容易翻车看到墙上数值大得离谱多半是单位没换算。3.2 编译后挂载 .addin 文件并调试项目编译通过之后要让 Revit 认识你的命令核心是写一个 .addin 清单文件。我一般不用 Revit 的自动加载器而是手工放到插件目录这样团队分发时也方便复制。?xml version1.0 encodingutf-16? AddIn TypeCommand NameCreateWallSample/Name AssemblyC:\dev\CreateWallSample\bin\Debug\CreateWallSample.dll/Assembly FullClassNameCreateWallSample.CreateWallCommand/FullClassName AddInId4f2f4277-1b43-4a6f-9a6c-5e1234abc001/AddInId VendorIdSampleVendorId/VendorId /AddIn路径%APPDATA%\Autodesk\Revit\Addins\2019下放一份即可。其中AddInId必须是 GUID 字符串每个命令在当前电脑上要唯一。经验是哪怕只改这个 IDRevit 都会把它当成新按钮原先配置好的快捷键会全部失效所以生产环境里 ID 一旦发布就别再动。调试时不需要每次手点复制。在 Visual Studio 里把“调试 启动外部程序”指向 Revit.exe 路径命令行参数写/language CHS重新编译后按 F5它会启动一个独立的 Revit 进程来加载你最新输出的 DLL。注意如果电脑上还开着别的 Revit调试进程加载的可能是被占用的 DLL提示“文件被另一进程使用”先关掉其他窗口再试。3.3 把命令挂到 Ribbon 面板上官方案例里不少样例同时提供了IExternalApplication它的作用是在 Revit 启动时注册按钮。这里贴一个最简版本。public class App : IExternalApplication { public Result OnStartup(UIControlledApplication application) { RibbonPanel panel application.CreateRibbonPanel(样例工具); PushButtonData btn new PushButtonData( CreateWallBtn, // 按钮唯一标识 建墙示例, // 按钮显示文字 typeof(CreateWallSample).Assembly.Location, // 程序集路径 typeof(CreateWallSample).FullName); // 完整类名 panel.AddItem(btn); return Result.Succeeded; } public Result OnShutdown(UIControlledApplication application) { return Result.Succeeded; } }注意CreateRibbonPanel(样例工具)里的面板名是全局可见的如果两个插件都用同一个名字Revit 会把它们归到同一面板下。按钮的Assembly.Location在运行时取的是插件 DLL 当前位置不要提前拼一个写死的路径否则换个电脑就找不到程序集。这个阶段跑通之后你已经具备把一个官方案例复制成自己插件的能力新建类库、写命令、写 .addin、点按钮。下一章开始改造几何类算法那才是二次开发真正体现价值的地方。4. 把官方几何样例搬进自己的算法体积统计的改造过程与单位陷阱4.1 从实例几何拿到 SolidOptions 参数怎么给拿到一个元素后要想算体积常规路径是用get_Geometry(Options)取到GeometryElement再遍历里面的Solid。官方案例通常不会告诉你 Options 某些参数影响具体这恰恰是改写时最容易踩的地方。private static double GetVolumeInCubicMeter(Element e) { Options opt new Options { DetailLevel ViewDetailLevel.Fine, ComputeReferences true }; GeometryElement ge e.get_Geometry(opt); if (ge null) return 0.0; double sum 0.0; foreach (GeometryObject o in ge) { if (o is Solid solid) { sum solid.Volume; // Revit 内部单位立方英尺 } } return sum * 0.0283168; // 立方英尺转立方米 }DetailLevel ViewDetailLevel.Fine表示按精细视图模式取几何如果默认 Coarse很多复杂构件只返回一个边界盒算出来体积完全不对。ComputeReferences true会生成每个面的引用信息用来后续做面选择很方便但代价是耗时明显增加。如果你的目标只是算体积建议改成 false能让遍历快一截。这里可以根据自己的任务灵活调。还要特别注意Solid.Volume的单位在 Revit 数据库里永远是立方英尺不是项目设置的毫米。项目单位只是 UI 层的显示不改变底层数值。所以批量导出前一定要统一换算逻辑。4.2 批量导出 CSV读操作不需要事务但文件写入要避开 UI 线程体积算出来后接下来通常是把结果落成表格。很多从官方案例改过来的开发者在读取参数时也会包一层Transaction去做“保险”这属于错误直觉。读取几何、读参数、读构件属性都是只读操作不需要开启事务事务唯一的作用是修改文档。这里我截图分享一下平时在项目里使用的批量导出流程。string filePath C:\temp\volume_report.csv; var lines new Liststring { ElementId,Volume_m3 }; foreach (Element e in selectedElements) { double vol GetVolumeInCubicMeter(e); lines.Add(${e.Id.IntegerValue},{vol.ToString(F4)}); } File.WriteAllLines(filePath, lines, Encoding.UTF8);这段代码里没有任何Transaction调用因为它既不改元素也不创建新元素。把文件写入放到命令末尾让整个Execute只做“取数-算数-写文件”三件事可以在很大程度上避免事务超时。如果数据量很大建议用StringBuilder拼行而不是Liststring内存占用会更可控。边界情况如果文档是只读的或者元素在视图中被裁剪GeometryElement可能会返回空。此时不要直接返回 0容易误把“没取到数据”当成“体积为 0”。常见做法是记录一条日志把 ElementId 收集起来等命令跑完再统一提示“有 N 个构件未取到几何”。4.3 族文档环境差异FamilyInstance 与实例几何官方案例里有相当一部分是在项目文档上演示的但实际工具经常要处理族文档。族文档里没有 Level很多按标高建墙的代码会直接报错。处理构件几何时还有一个差异普通图元用get_Geometry能直接拿到 Solid但FamilyInstance需要区分“实例几何”和“符号几何”。GeometryElement ge element.get_Geometry(opt); if (ge null element is FamilyInstance fi) { ge fi.GetInstanceGeometry(); // 取按当前尺寸生成的实例几何 }GetInstanceGeometry会把族参数拉伸后的真实形状算出来适合用来标注、测量、碰撞检查而GetSymbolGeometry返回的是族定义的原始几何不随实例参数变化。这两种几何的坐标空间也不同实例几何在项目坐标系里符号几何还在族坐标系。如果不加区分把符号几何导出到项目坐标里位置会偏移得很离谱。这里还要留个心眼Options里面有一个IncludeNonVisibleObjects选项默认 false。计算体积时保持 false 没问题但如果你同时想统计虚线、参照平面之类的辅助几何就需要单独再开一个 Options。不要试图一个配置跑全部场景几何选项不能省。5. 避坑实录编译通过但运行报错的五个常见原因5.1 错误加载程序集时拒绝访问或提示“文件正在被另一进程使用”现象编译完成后点 Revit 里面的按钮界面无反应打开日志发现程序集加载失败或者启动调试时 Visual Studio 提示 DLL 被占用。原因Revit 在启动时会把插件 DLL 加载进自身进程同时还会保持文件锁定。如果你在调试状态下重新编译输出目录里的 DLL 被上一个 Revit 进程占用会写到一半失败形成残留文件后面每次加载都报“尝试读取或写入受保护的内存”之类的玄学错误。解决先彻底关闭所有 Revit 进程再清理 bin/obj 目录后重新生成。如果用了 .addin 指向临时目录建议统一把输出路径设到%APPDATA%下一个固定插件目录避免频繁换路径导致锁定残留。从那以后我每接一个新插件都会先检查有没有残留锁定文件这个习惯能省下大量排错时间。5.2 错误插件菜单是灰的按钮点击无效果现象Ribbon 面板能看到按钮但按钮一直是灰色或者点下去无反应。原因按钮的PushButtonData指定的类和程序集路径对不上。最常见是用了typeof(Class).Assembly.Location但类名在复制样例后没有同步改名导致 Revit 只能通过反射找不到目标类。解决检查 .addin 里的FullClassName确保和实际类的完全限定名一致包含命名空间前缀。例如类写的是GeometryTools.Commands.CreateWallSample那配置也必须是完整字符串少一层命名空间都算失败。5.3 错误在族编辑器里调用建墙命令抛异常现象打开族文档后运行命令Revit 直接弹出“不支持该操作”或“事务已被内部处理”。原因族文档和项目文档是两种不同模型。墙、楼板、屋顶这类型构件必须在项目环境里创建族编辑器里只允许创建属于该族类型的构件和参照平面。很多官方案例没有处理这种差异直接拿项目文档的用例去族环境运行自然翻车。解决在命令入口用doc.IsFamilyDocument做判断是族文档就提示用户切回项目环境或者走另一套“在族内创建参照面”的逻辑。我一般在第一时间就在Execute里拦截掉非法文档类型不让错误拖到中间流程才暴露。5.4 错误算出来体积全部为零现象批量统计时某些构件体积是 0有些构件正常。原因一是没设DetailLevel ViewDetailLevel.Fine粗模式下只给简化几何二是对 FamilyInstance 没走GetInstanceGeometry返回的是空壳三是构件在当前视图被裁切掉Options默认会排除不可见部分。解决遍历前固定Options的三个关键参数DetailLevel、ComputeReferences、IncludeNonVisibleObjects。同时把GetInstanceGeometry作为回退分支。还要注意如果拿的是链接模型的元素需要先通过GetLinkedDocument拿到对应文档再取几何否则获取到的都是零。5.5 错误命令执行时间过长Revit 界面变白然后被系统判定无响应现象遍历几百个构件做体积统计进度条没动界面卡死十秒后提示“已停止工作”。原因外部命令Execute是运行在 Revit UI 线程上的。你在里面写了长循环意味着 Revit 整个界面线程被占住Windows 会判断窗口失去响应。Revit 本身不是多线程安全的不能在后台线程直接操作 Document。解决把耗时的数据读取拆成小块用一个IExternalEventHandler配合Idle事件分批执行。每次处理完 20 个元素就调用一次RaiseIdle把控制权交还给界面刷新然后再继续下一批。这个“批处理让位”模型在官方案例里其实出现过很多人没注意到它的用途。6. 把 147 例沉淀成私有工具库重命名、裁切与二次封装的三个习惯一次完整地把官方案例跑完最大的收获不该只是熟悉 API而是学会“剪裁”参考资料变成自己的代码基础设施。我的习惯是分三步走。第一步是重命名命名空间。复制官方样例代码后我不会保留原来的命名空间而是统一改成项目内部的Company.RevitTools.Geometry。表面看这只是组织代码但实际影响很大当解决方案里同时存在官方样例、第三方库和自己的代码时模糊的命名空间会让反射调用和日志定位变得特别费劲。全解决方案替换一次顺带把using也理顺后续维护成本立减。第二步是裁掉与核心逻辑无关的 UI 代码。官方案例为了演示方便经常混入对话框、选择逻辑和状态提示。这些代码在样例里很完整但搬进生产工具时反而是负担。原则是命令层保留 50 行以内业务逻辑保留 10 年以后还能看懂的注释UI 相关全部踢出公共类。第三步是固定 GUID 之后再改名。命令 ID、AddInId 和按钮 ID 这三个标识符一旦发布就不要再动否则 Revit 会把已配置的快捷键和面板位置全部重置。我踩过这个坑上线两周的插件改了一次按钮 ID用户全部反应按钮跑到别的地方去了重新拖一次面板又花了不少时间。从那以后我在开发期就把 GUID 生成好写进代码常量后面只改显示名不改标识。把官方案例沉淀成一个私有工具库之后日常写新功能的速度会明显加快。就拿单位换算来说我从 147 例里抽了一个FootToMm常量扩展成下面这个工具类几乎每个导出命令都会用到public static class RevitUnits { public const double FootToMm 304.8; public static double FtToM(double feet) feet * 0.3048; public static double Ft2ToM2(double squareFeet) squareFeet * 0.092903; public static double Ft3ToM3(double cubicFeet) cubicFeet * 0.0283168; public static double MmToFt(double mm) mm / 304.8; }这段代码的逻辑一目了然单位变换集中在一处。新版项目里再也不用到处写* 0.3048这种魔法数字也不会出现前面第六节提到的“导出体积带 6 个小数位”这类单位事故。整体上把这套 147 例当作参考资料而不是成品来用可以很快形成自己的一套二次开发惯例。希望帮到你。本文还有配套的精品资源点击获取