AutoRevit.2021 0.2.0-rc

AutoRevit

Revit 二次开发框架，让你能快速且轻松地使用 Revit API，告别冗长的样板代码。

特性

• 源代码生成器 — 通过 [AutoExternalCommand] 和 [AutoExternalEventHandler] 特性自动生成 IExternalCommand / IExternalEventHandler 样板代码
• 模块化架构 — 基于 IExternalModule 的插件化模块系统
• 命令扩展管道 — 支持热更新（IHotUpdateExtend）和拦截器（IInterceptorExtend）
• 异步事件系统 — ExternalEventTask 让你在 Revit 外部事件中方便地使用 async/await
• Fluent Ribbon API — 链式 API 快速构建 Revit 插件面板界面
• 丰富的扩展方法 — 对 Transaction、Curve、XYZ、Document 等常用类型提供便捷扩展
• 多版本支持 — 覆盖 Revit 2016 ~ 2026

安装

通过 NuGet 安装对应 Revit 版本的包：

# Revit 2026
dotnet add package AutoRevit.2026

# Revit 2025
dotnet add package AutoRevit.2025

# ...以此类推

如果要使用 [AutoExternalCommand] 和 [AutoExternalEventHandler] 源代码生成器，还需额外安装：

dotnet add package AutoRevit.Generator

快速开始

1. 创建命令

用 [AutoExternalCommand] 标记一个静态方法，生成器会自动创建 IExternalCommand 实现类：

using Autodesk.Revit.UI;
using AutoRevit;

public class MyCommands
{
    [AutoExternalCommand(TransactionMode = nameof(TransactionMode.Manual))]
    public static Result SayHello()
    {
        TaskDialog.Show("AutoRevit", "Hello, Revit!");
        return Result.Succeeded;
    }
}

生成的类名默认为 {方法名}AutoExternalCommand，可通过 ClassName 属性自定义。

2. 创建外部事件处理

用 [AutoExternalEventHandler] 标记静态方法，用于在命令外部触发 Revit API 调用：

using Autodesk.Revit.UI;
using AutoRevit;

public class MyEvents
{
    [AutoExternalEventHandler]
    public static void DoSomething(UIApplication uiapp)
    {
        // 在 Revit 主线程中执行
        TaskDialog.Show("Event", "Done!");
    }
}

3. 注册模块和 Ribbon

实现 IExternalModule 接口，在 OnStartup 中构建 Ribbon 面板：

using Autodesk.Revit.UI;
using AutoRevit.Entry.Application;
using AutoRevit.Ribbon;
using AutoRevit.Ribbon.Ribbon.Mapper;

public class MyModule : IExternalModule
{
    public Result OnStartup(UIControlledApplication application)
    {
        var panel = new PanelMapper("MyPlugin")
        {
            Items =
            [
                new PushButtonMapper<SayHelloAutoExternalCommand>("Say Hello"),
            ]
        };

        new ControlManager(application).Map([panel]);
        return Result.Succeeded;
    }

    public Result OnShutdown(UIControlledApplication application) => Result.Succeeded;
}

4. 注册入口

继承 ExternalApplication，通过 AddModuleClasses 扫描程序集自动发现模块：

using System.Reflection;
using AutoRevit.Entry.Application;

public class App : ExternalApplication
{
    protected override Result OnStartup(UIControlledApplication application)
    {
        AddModuleClasses(Assembly.GetExecutingAssembly());
        return base.OnStartup(application);
    }
}

5. 配置 .addin 清单

在 Revit 插件目录创建 .addin 文件，指向编译后的程序集和入口类：

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Application">
    <Name>MyPlugin</Name>
    <Assembly>path\to\YourPlugin.dll</Assembly>
    <AddInId>YOUR-GUID-HERE</AddInId>
    <FullClassName>YourNamespace.App</FullClassName>
    <VendorId>YOUR-NAME</VendorId>
  </AddIn>
</RevitAddIns>

详细指南

AutoExternalCommand 特性参数

方法签名

[AutoExternalCommand] 标记的方法必须满足：

• 必须为 static
• 返回值必须为 Autodesk.Revit.UI.Result
• 访问修饰符为 public 或 internal

可选参数类型：

• 无参数
• ExternalCommandData
• ref string message
• ElementSet elements
• IRevitData（封装了上述所有参数）

命令扩展

继承 AutoCommand 基类而非直接使用特性，可获得扩展能力：

// 热更新 — 不重启 Revit 重新加载程序集
public class HotUpdateCommand : AutoCommand, IHotUpdateExtend
{
    protected override Result Execute(IRevitData revitData)
    {
        return Result.Succeeded;
    }
}

// 拦截器 — 在命令执行前拦截
public class InterceptorCommand : AutoCommand, IInterceptorExtend
{
    protected override Result Execute(IRevitData revitData)
    {
        return Result.Succeeded;
    }
}

如果不需要被拦截，可标记 [IgnoreInterceptor]。

异步外部事件

var task = new ExternalEventTask();

await task.RunAsync(uiapp =>
{
    // 在 Revit 上下文中执行
    var doc = uiapp.ActiveUIDocument.Document;
    // ...
});

// 带返回值
var result = await task.RunAsync<int>(uiapp =>
{
    return 42;
});

Ribbon 构建

var tabMapper = new TabMapper("CustomTab");
tabMapper.AddPanel(new PanelMapper("MyPanel")
{
    Items =
    [
        new PushButtonMapper<MyCommand>("按钮文字"),
        new SplitButtonMapper("分组按钮")
        {
            Items =
            [
                new PushButtonMapper<CmdA>("A"),
                new PushButtonMapper<CmdB>("B"),
            ]
        }
    ]
});

new ControlManager(application).Map([tabMapper]);

工具方法

// 选择过滤器
var element = doc.SelectElement(new SelectionFilter<Element>());

// Transaction 扩展
using (var trans = new Transaction(doc, "My Operation"))
{
    trans.StartWithFailureHandling(); // 自动处理失败
    // ...
    trans.CommitWithFailurePreprocessor();
}

// XYZ 扩展
var midpoint = xyz1.Mid(xyz2);
var distance = xyz1.DistanceTo(xyz2);

// Curve 扩展
var line = new Line(startPoint, endPoint); // 替代 Revit 冗长的 API

项目结构

src/
├── AutoRevit/              # 共享代码库 (.projitems)
│   ├── Entry/              # 入口：ExternalApplication, AutoCommand
│   ├── Event/              # 异步外部事件系统
│   ├── Ribbon/             # Fluent Ribbon API
│   ├── DB/Extensions/      # Revit 类型扩展方法
│   ├── Selection/          # 选择过滤
│   ├── Storage/            # 元素数据存储
│   ├── Shortcut/           # 快捷键
│   ├── Tool/               # 用户交互工具
│   └── Utils/              # 工具类
├── AutoRevit.2016~2026/    # 各 Revit 版本包装项目
├── AutoRevit.Generator/    # Roslyn 源代码生成器
└── Demo/                   # 示例项目

版本兼容性

构建

# 构建全部项目
dotnet build src/AutoRevit.slnx

# 构建特定版本
dotnet build src/AutoRevit.2026/AutoRevit.2026.csproj

# 打包 NuGet
dotnet pack src/AutoRevit.2026/AutoRevit.2026.csproj -c Release

许可

MIT License