RevitGen 2.0.0

RevitGen

A powerful Roslyn source generator that accelerates Revit add-in development by automatically generating boilerplate code for external commands, ribbon buttons, and application registration.

一个基于 Roslyn 的强大源生成器，通过自动生成外部命令、功能区按钮和应用注册所需的样板代码，大幅加速 Revit 插件开发。

Project Architecture / 项目架构

Prerequisites / 前置条件

• The consuming project must use the new SDK-style .csproj format.
  If your project is not SDK-style, install the .NET Upgrade Assistant extension from
  https://marketplace.visualstudio.com/vs (or via Visual Studio → Extensions → Manage Extensions),
  then right-click the project → Upgrade → Convert project to SDK style.

• 使用该包的项目必须采用新的 .Net SDK 样式。如不是，可通过 VS 扩展市场搜索安装 .NET Upgrade Assistant，然后右键项目 → 升级 → 将项目转换为 SDK 样式。

Getting Started / 快速开始

1. Install the NuGet Package / 安装 NuGet 包

Local development (from source) / 本地开发（从源代码）：

1. Right-click the RevitGen project → Pack to generate a .nupkg.
2. Update nuget.config to point at the folder containing the generated package.

Published package:

<PackageReference Include="RevitGen" Version="2.0.0" />

2. Decorate Your Command Class / 标记命令类

using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using RevitGen.Attributes;
using RevitGenDemo.Properties;

namespace MyAddin
{
    // Example 1 – icon loaded from a .resx resource (embedded resource)
    // 示例 1 – 图标来自 .resx 资源（嵌入式资源）
    [RevitCommand("My First Command",
        ToolTip    = "An auto-generated Revit command!",
        PanelName  = "Core Features",
        Icon       = nameof(Resources.CodeList_32px))]
    public partial class RevitAddinOne
    {
        [CommandHandler]
        private void Run()
        {
            var walls = new FilteredElementCollector(Document)
                .OfCategory(BuiltInCategory.OST_Walls)
                .WhereElementIsNotElementType()
                .ToElements();

            if (walls.Count == 0)
            {
                this.ErrorMessage = "No walls found in the project.";
                this.Result = Result.Failed;
                return;
            }

            TaskDialog.Show("Success", $"Found {walls.Count} wall(s).");
        }
    }

    // Example 2 – icon loaded from an embedded file path
    // 示例 2 – 图标来自嵌入式文件路径
    [RevitCommand("My Second Command",
        ToolTip    = "Another auto-generated command!",
        PanelName  = "Core Features",
        Icon       = "Resources/CodeList_32px.png")]
    public partial class RevitAddinTwo
    {
        [CommandHandler]
        private void Run()
        {
            TaskDialog.Show("Hello", "Command executed!");
        }
    }
}

Attribute Reference / 特性参数说明

[RevitCommand(text, ...)]

[CommandHandler]

Mark exactly one parameterless void method per class as the command entry point.
每个命令类中标记一个无参数、返回 void 的方法作为命令执行入口。

[CommandAvailability]

Optionally mark one instance method returning bool. It may be parameterless or accept one UIApplication. The command automatically implements IExternalCommandAvailability.

可选标记一个返回 bool 的实例方法；方法可以无参数，或接收一个 UIApplication。命令会自动实现 IExternalCommandAvailability。

[CommandAvailability]
private bool CanExecute(UIApplication application)
{
    return application.ActiveUIDocument != null;
}

Additional Generators / 其他生成器

ExternalEvent

[RevitExternalEvent(Name = "Refresh model")]
public partial class RefreshExternalEvent
{
    [ExternalEventHandler]
    private void Run(UIApplication application) { }
}

// Must be called from a valid Revit UI context.
var handler = new RefreshExternalEvent();
var externalEvent = handler.CreateExternalEvent();

The handler method returns void and accepts zero parameters or one UIApplication. ExternalEvent.Create is never executed from a generated static initializer.

处理方法返回 void，接收零个参数或一个 UIApplication。生成器不会在静态初始化阶段创建 ExternalEvent。

Updater

[RevitUpdater("Wall geometry updater", "DC7C2E9A-F242-4DFD-BB0C-52B7E5B0B940")]
[UpdaterTrigger((int)BuiltInCategory.OST_Walls, RevitChangeType.Geometry)]
public partial class WallUpdater
{
    [UpdaterHandler]
    private void Run(UpdaterData data) { }
}

The generated Bootstrap registers and unregisters the updater. Multiple [UpdaterTrigger] attributes are supported. An updater without a trigger produces REVITGEN105 and is not given an implicit whole-model trigger.

Bootstrap 自动注册和注销 Updater。支持多个 [UpdaterTrigger]；未配置触发器时给出 REVITGEN105，不会隐式监听整个模型。

Revit events

[RevitEventContainer]
public partial class ApplicationEvents
{
    [RevitEvent(RevitEventKind.Idling)]
    private void OnIdling(object sender, IdlingEventArgs args) { }
}

Bootstrap creates one container instance at startup and performs symmetric unsubscribe at shutdown. Supported events are listed by RevitEventKind.

Bootstrap 在启动时创建一个事件容器实例，并在关闭时对称取消订阅。支持范围以 RevitEventKind 为准。

DockablePane

[RevitDockablePane("A19756A4-2A3A-4488-A3AF-AE15D8698795", "My Pane")]
public partial class MyPane : UserControl
{
}

The class must derive from a WPF FrameworkElement and be constructible without arguments. RevitGen generates IDockablePaneProvider and startup registration.

类型必须继承 WPF FrameworkElement，并可通过无参数构造。RevitGen 自动生成 IDockablePaneProvider 和启动注册代码。

Extensible Storage

[RevitSchema("31578522-277A-4F10-BAD7-43C68B36AF50", "ComponentData", VendorId = "SZMD")]
public partial class ComponentData
{
    [RevitSchemaField]
    public string Code { get; set; }

    [RevitSchemaField]
    public int Version { get; set; }
}

var entity = data.ToEntity();
var restored = ComponentData.FromEntity(entity);

The generated GetOrCreateSchema() is idempotent. The first release supports Revit simple field types; unit-bearing and map fields are intentionally excluded from the cross-version baseline.

生成的 GetOrCreateSchema() 可重复调用。首版覆盖 Revit 简单字段类型；带单位字段和 Map 字段暂不进入跨版本基线。

Shared parameters

public partial class SharedParameters
{
    [RevitSharedParameter(
        "6DB4557F-69B7-4665-86A7-C821158AC763",
        "Component code",
        Categories = new[] { (int)BuiltInCategory.OST_Walls })]
    public static readonly string ComponentCode = "Component code";
}

GetSharedParameterDefinitions() returns generated metadata. EnsureSharedParameterBindings(...) scans BindingMap once and binds every missing definition found in the supplied shared-parameter file. It reports missing external definitions instead of modifying the file silently.

GetSharedParameterDefinitions() 返回生成的描述表。EnsureSharedParameterBindings(...) 只遍历一次 BindingMap，批量绑定共享参数文件中已有的缺失定义；不会静默修改共享参数文件。

Revit Version Compatibility / Revit 版本兼容

• RevitGen 2.x uses Roslyn 4.8 and requires Visual Studio 2022 or an equivalent compiler.
• The generator itself targets netstandard2.0 and runs only at compile time.
• RevitGenDemo verifies Revit 2020 on .NET Framework.
• RevitGenDemo2025 verifies Revit 2025 on .NET 8.
• Generated code avoids a compile-time System.Drawing dependency, so ResX icons work across the runtime boundary.

RevitGen 2.x 使用 Roslyn 4.8，需要 Visual Studio 2022 或等价编译器。生成器本身仍为 netstandard2.0 且只在编译期运行；仓库分别使用 Revit 2020 与 Revit 2025 Demo 验证 .NET Framework 和 .NET 8。

Generated Bootstrap / 生成的启动入口

The default manifest entry remains RevitGen.Runtime.RevitGenApplication. Existing projects do not need to change it. Projects with their own IExternalApplication can call:

默认清单入口仍为 RevitGen.Runtime.RevitGenApplication，旧项目无需修改。已有自定义 IExternalApplication 的项目可调用：

return RevitGen.Runtime.RevitGenBootstrap.Startup(application);
// and in OnShutdown:
return RevitGen.Runtime.RevitGenBootstrap.Shutdown(application);

Auto-Generated Members / 自动生成的成员

The generator produces a second partial half of your class that exposes:

生成器会为你的 partial 类自动生成以下成员：

Building and Testing / 构建与测试

# Restore all projects
dotnet restore RevitGen.sln

# Build the source generator and common library
dotnet build RevitGen.Generator/RevitGen.Generator.csproj
dotnet build RevitGen.Common/RevitGen.Common.csproj

# Run all unit tests
dotnet test RevitGen.Tests/RevitGen.Tests.csproj

FAQ

Q: Why don't I see any generated files in my project?
A: Make sure your class is declared partial and is decorated with [RevitCommand(...)]. The generator only processes partial classes. Also verify that RevitGen.Common and RevitGen.Generator are both referenced (the NuGet package handles this automatically).

Q: Can I use RevitGen with a non-SDK-style project (.csproj)?
A: Source generators require the SDK-style project format. Use the .NET Upgrade Assistant Visual Studio extension to convert your project (right-click → Upgrade → Convert project to SDK style).

Q: My command runs but no Ribbon button appears. What should I check?
A: Make sure the generated RevitGenApplication class is registered as an IExternalApplication in your .addin manifest. The generator produces RevitGenApplication.g.cs in the RevitGen.Runtime namespace; reference it from your manifest file.

Q: UsingTransaction = false — when should I use it?
A: Set UsingTransaction = false for read-only commands (e.g., selecting elements, showing dialogs, reporting data) that do not modify the Revit model. This avoids the overhead of starting an unnecessary transaction.

Q: How do I load an icon for my button?
A: Two approaches are supported:

• Embedded file – set Icon to a relative file path with an extension, e.g. Icon = "Resources/MyIcon.png", and mark the file as an Embedded Resource in your project.
• ResX resource – add the image to a .resx file and set Icon to the resource name (no extension), e.g. Icon = nameof(Resources.MyIcon).

Contributing / 贡献指南

1. Fork the repository and create a feature branch from main.
2. Make your changes and add or update unit tests in RevitGen.Tests.
3. Ensure all tests pass with dotnet test RevitGen.Tests/RevitGen.Tests.csproj.
4. Open a Pull Request targeting the dev branch for review.

License / 许可证

This project is licensed under the terms in the LICENSE file.