Skip to content
C#
Revit
环境搭建

环境搭建

Revit API 允许通过 C# 编写插件来自动化 Revit 操作、创建自定义命令和修改建筑信息模型。

版本与引用

Revit 版本 → .NET Framework

Revit 版本 .NET Framework RevitAPI.dll 路径
2019~2024 4.8 {Revit安装目录}\RevitAPI.dll, RevitAPIUI.dll
2025+ .NET 8 转向跨平台（具体版本验证中）

必须引用的 DLL

DLL 命名空间 用途
RevitAPI.dll Autodesk.Revit.DB 数据库层：元素、族、参数、事务
RevitAPIUI.dll Autodesk.Revit.UI UI 层：Ribbon、对话框、选择、外部命令

🚨 Copy Local = False（和 AutoCAD 一样）。RevitAPI 随 Revit 安装，不应复制到输出目录。

Visual Studio 项目创建

步骤

  1. 新建项目 → Class Library (.NET Framework) → 选择 .NET Framework 4.8
  2. 添加引用 → 浏览 → 导航到 Revit 安装目录（如 C:\Program Files\Autodesk\Revit 2024\）
  3. 添加 RevitAPI.dll 和 RevitAPIUI.dll
  4. 引用的 Copy Local 设为 False

.csproj 参考 

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <LangVersion>8.0</LangVersion>
    <CopyLocalLockFileAssemblies>false</CopyLocalLockFileAssemblies>
  </PropertyGroup>

  <ItemGroup>
    <Reference Include="RevitAPI">
      <HintPath>C:\Program Files\Autodesk\Revit 2024\RevitAPI.dll</HintPath>
      <Private>False</Private>
    </Reference>
    <Reference Include="RevitAPIUI">
      <HintPath>C:\Program Files\Autodesk\Revit 2024\RevitAPIUI.dll</HintPath>
      <Private>False</Private>
    </Reference>
  </ItemGroup>
</Project>

第一个命令：Hello Revit

Revit 插件的基本单位是实现 IExternalCommand 接口的类：

using Autodesk.Revit.UI;
using Autodesk.Revit.DB;
using Autodesk.Revit.Attributes;

namespace MyRevitAddin
{
    [Transaction(TransactionMode.Manual)]         // 声明事务模式
    [Regeneration(RegenerationOption.Manual)]      // 声明再生模式
    public class HelloCommand : IExternalCommand
    {
        public Result Execute(
            ExternalCommandData commandData,
            ref string message,
            ElementSet elements)
        {
            // commandData 包含 Application 和 Document 引用
            UIApplication uiApp = commandData.Application;
            UIDocument uiDoc = uiApp.ActiveUIDocument;
            Document doc = uiDoc.Document;

            TaskDialog.Show("Hello Revit", $"当前文档：{doc.Title}");

            return Result.Succeeded;
        }
    }
}

关键特性说明 

// TransactionMode 含义
[Transaction(TransactionMode.Automatic)]    // Revit 自动创建事务（简单场景）
[Transaction(TransactionMode.Manual)]       // 开发者手动管理事务（推荐）

// RegenerationOption 含义
[Regeneration(RegenerationOption.Manual)]   // 命令结束时手动再生（推荐）
[Regeneration(RegenerationOption.Automatic)] // Revit 自动再生（慎用，影响性能）

💡 推荐组合：TransactionMode.Manual + RegenerationOption.Manual。这给你最大的控制权，避免 Revit 自动创建不需要的事务。

Result 返回值

值 含义
Result.Succeeded 命令成功执行
Result.Failed 命令失败（Revit 可能回滚事务）
Result.Cancelled 用户取消操作（不视为错误）

IExternalApplication —— 应用级入口

用于在 Revit 启动时注册 Ribbon 按钮和事件处理器：

[Transaction(TransactionMode.Manual)]
public class MyApplication : IExternalApplication
{
    // Revit 启动时调用
    public Result OnStartup(UIControlledApplication application)
    {
        // 创建 Ribbon 面板和按钮
        string tabName = "我的工具";
        application.CreateRibbonTab(tabName);

        RibbonPanel panel = application.CreateRibbonPanel(tabName, "绘图");

        // 创建按钮
        PushButtonData buttonData = new PushButtonData(
            "HelloCommand",              // 内部名称（唯一）
            "Hello",                     // 显示文本
            typeof(HelloCommand).Assembly.Location,
            typeof(HelloCommand).FullName
        );
        buttonData.ToolTip = "向 Revit 问好";
        panel.AddItem(buttonData);

        // 注册事件
        application.ControlledApplication.DocumentOpened += OnDocOpened;

        return Result.Succeeded;
    }

    // Revit 关闭时调用
    public Result OnShutdown(UIControlledApplication application)
    {
        application.ControlledApplication.DocumentOpened -= OnDocOpened;
        return Result.Succeeded;
    }

    private void OnDocOpened(object sender, DocumentOpenedEventArgs e)
    {
        TaskDialog.Show("提示", $"打开了：{e.Document.Title}");
    }
}

插件清单 (.addin 文件)

Revit 发现插件的方式是读取 .addin 清单文件（而非 NETLOAD）：

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Command">
    <Name>My Hello Command</Name>
    <Assembly>C:\MyAddins\MyRevitAddin.dll</Assembly>
    <ClientId>12345678-1234-1234-1234-123456789abc</ClientId>
    <FullClassName>MyRevitAddin.HelloCommand</FullClassName>
    <Description>向 Revit 问好</Description>
    <VendorId>MyCompany</VendorId>
    <VendorDescription>MyCompany Inc.</VendorDescription>
  </AddIn>

  <AddIn Type="Application">
    <Name>My Application</Name>
    <Assembly>C:\MyAddins\MyRevitAddin.dll</Assembly>
    <ClientId>12345678-1234-1234-1234-123456789abd</ClientId>
    <FullClassName>MyRevitAddin.MyApplication</FullClassName>
    <VendorId>MyCompany</VendorId>
  </AddIn>
</RevitAddIns>

清单文件位置

将 .addin 文件放到以下目录之一：

# 用户级别（推荐开发时使用）
C:\ProgramData\Autodesk\Revit\Addins\{版本号}\

# 或用户 AppData
C:\Users\{用户名}\AppData\Roaming\Autodesk\Revit\Addins\{版本号}\

💡 ClientId 必须是唯一的 GUID，用 Visual Studio 的 Tools → Create GUID 生成。每个命令和 Application 使用不同的 GUID。

调试配置

Visual Studio 调试设置

  1. 项目属性 → Debug → Start external program → C:\Program Files\Autodesk\Revit 2024\Revit.exe
  2. F5 启动 Revit
  3. Revit 启动时自动加载 .addin 清单中的插件
  4. 断点即刻生效

附加到已运行的 Revit

  1. Debug → Attach to Process
  2. 勾选 “Show processes from all users”
  3. 选择 Revit.exe
  4. Attach — 选择 “Managed (.NET Framework 4.x)” 代码类型

关键命名空间速查 

// 数据库层（RevitAPI.dll）
using Autodesk.Revit.DB;               // Document, Element, Parameter, Transaction...
using Autodesk.Revit.DB.Architecture;  // Wall, Floor, Roof, Room...
using Autodesk.Revit.DB.Structure;     // Rebar, BeamSystem...
using Autodesk.Revit.DB.Mechanical;    // Duct, Pipe, MEP...
using Autodesk.Revit.DB.Plumbing;      // Fixture...
using Autodesk.Revit.Attributes;       // TransactionAttribute, RegenerationAttribute

// UI 层（RevitAPIUI.dll）
using Autodesk.Revit.UI;               // IExternalCommand, IExternalApplication
using Autodesk.Revit.UI.Selection;     // Selection, ISelectionFilter

ExternalCommandData 核心对象 

public Result Execute(ExternalCommandData commandData, ...)
{
    // 获取 Application
    UIApplication uiApp = commandData.Application;
    Autodesk.Revit.ApplicationServices.Application app = uiApp.Application;

    // 获取文档
    UIDocument uiDoc = uiApp.ActiveUIDocument;     // UI 层（含选择集）
    Document doc = uiDoc.Document;                  // 数据库层

    // 当前视图
    View activeView = uiDoc.ActiveView;
}

项目结构最佳实践 

MyRevitAddin/
├── MyRevitAddin.csproj
├── MyApplication.cs              # IExternalApplication 入口
├── Commands/
│   ├── HelloCommand.cs
│   ├── CreateWallCommand.cs
│   └── ExportDataCommand.cs
├── EventHandlers/
│   ├── DocumentEventHandler.cs   # IExternalEventHandler 实现
│   └── IdleEventHandler.cs
├── Helpers/
│   ├── ElementHelper.cs
│   ├── ParameterHelper.cs
│   └── FilterHelper.cs
├── Models/
│   └── ExportConfig.cs
└── MyRevitAddin.addin             # 清单文件（设 Copy to Output = Always）

💡 和 AutoCAD 一样，命令方法保持简短（< 50 行），逻辑提取到 Helpers 中。将 .addin 文件设为 “Copy to Output Directory = Copy always”，便于一键部署。

API 概览与核心概念