EnglishRevit
Xây Dựng Revit Addin Bằng AI: ChatGPT hoặc Claude
Tôi là kiến trúc sư chuyển sang làm phần mềm, và gần như tuần nào cũng có người nhờ viết một Revit add-in nhỏ. Từ 2024, phần khó của yêu cầu đó đã đổi. AI sẵn sàng viết C# cho plugin Revit của bạn; nhưng nó cũng sẵn sàng viết đoạn C# mà Revit lặng lẽ từ chối nạp. Bài này là danh sách ngắn những dữ kiện đặc thù Revit bạn phải đưa cho AI ngay từ đầu, kèm một add-in tối giản chạy được ngay.
Công cụ AI làm được gì trên máy bạn
Cửa sổ chat trên trình duyệt không hợp với việc lập trình Revit add-in, vì bạn sẽ phải tự copy file bằng tay. Thứ dùng được là các công cụ AI chạy ngay tại nơi chứa code. Anthropic mô tả Claude Code là công cụ “đọc codebase, sửa file, chạy lệnh và tích hợp với công cụ phát triển của bạn”, có mặt trong terminal, IDE, ứng dụng desktop và trình duyệt. Codex CLI của OpenAI chạy “trên repository local của bạn” và cho phép “sửa file, chạy các công cụ đã cài sẵn trên máy”, kèm lệnh /permissions để đặt giới hạn “khi nào Codex được sửa file hoặc chạy lệnh mà không cần hỏi”.
Chỉ cần thế: một công cụ như vậy, một thư mục trống, và một bản Revit đã cài. Nút thắt không bao giờ nằm ở chuyện sinh code — nó nằm ở chỗ Revit API gắn chặt với phiên bản Revit, trong khi dữ liệu huấn luyện của mô hình trộn lẫn sáu năm mẫu code không tương thích nhau. Mọi thứ bên dưới chính là phần context lấp khoảng trống đó.
Một bước kiểm tra trước khi bắt đầu, vì nó giúp phần lớn mọi người khỏi phải làm project luôn: nếu thứ bạn cần là công cụ sửa tham số hàng loạt, đổi tên sheet hay dọn dữ liệu room, add-in đó đã có sẵn. Dùng thử Metasheet miễn phí trước — nó đưa tham số và schedule của Revit vào lưới bảng tính sửa trực tiếp, hỗ trợ Revit 2022–2027, không mất phí. Chỉ tự viết phần nào chưa công cụ nào phủ.
Bốn dữ kiện phải đưa cho AI trước khi nó viết dòng đầu tiên
1. Phiên bản Revit quyết định runtime .NET
Đây là nguyên nhân số một của tình huống “build sạch mà chẳng thấy gì hiện ra”. Trang Development Requirements của Autodesk cho Revit 2024 ghi: “The Autodesk Revit API requires the Microsoft .NET Framework 4.8.” Cũng trang đó cho Revit 2026 ghi: “The Autodesk Revit API requires Microsoft .NET 8.0.” Còn Revit 2027 “đã được cập nhật để dùng runtime .NET 10 bản chính thức cho cả việc chạy Revit lẫn build add-in”, cần cài SDK 10.0.100.
- Revit 2022–2024 →
net48(.NET Framework 4.8) - Revit 2025–2026 →
net8.0-windows - Revit 2027 →
net10.0-windows
DLL build sai dòng runtime không báo lỗi ở bất kỳ đâu: Revit bỏ qua nó, nút trên ribbon không bao giờ xuất hiện, và bạn chẳng có gì để gắn debugger vào. Ghi chú chuyển sang .NET 8 của chính Autodesk thực chất chỉ là một thuộc tính project — đặt <TargetFramework>net8.0-windows</TargetFramework>, thêm <UseWPF>true</UseWPF> nếu add-in có cửa sổ WPF. Nói rõ năm Revit ngay câu đầu của prompt thì AI không có lý do gì để đoán.
2. Tham chiếu hai assembly của Revit — và đừng copy chúng
Hướng dẫn Hello World của Autodesk yêu cầu tham chiếu RevitAPI.dll và RevitAPIUI.dll từ thư mục cài Revit, rồi đặt thuộc tính “Copy Local property of RevitAPI.dll and RevitAPIUI.dll to No”. Hãy nói thẳng điều này với AI. Nếu để Copy Local bật, thư mục output sẽ mang theo một bản Revit API riêng, bản này nạp song song với bản Revit đang có sẵn — nguồn gốc của những lỗi ép kiểu đọc vào thấy vô lý (“không convert được type X sang type X”).
Có một đường lười hơn mà AI không tự nghĩ ra: dùng các gói NuGet reference-assembly mô phỏng Revit API. Add-in Metasheet của chúng tôi build theo cách đó, pin phiên bản gói riêng cho từng target framework, nên máy build không cần cài Revit. Mẹo này dùng cho CI cũng được.
3. Attribute transaction là bắt buộc và không có giá trị mặc định
Autodesk nói rất thẳng: attribute Autodesk.Revit.Attributes.TransactionMode “must be applied to your implementation class of the IExternalCommand interface”, và “There is no default for this option.” Thực tế chỉ hai giá trị đáng quan tâm: Manual cho mọi thứ thay đổi model, ReadOnly cho thứ chỉ đọc.
Cái đó khác với bản thân transaction. Developer Guide ghi rõ “Any change to a document can only be made while there is an active transaction open for that document” và “Attempting to change the document outside of a transaction will throw an exception”. Thay đổi “không trở thành một phần của model cho tới khi transaction đang mở được commit”, và “Only one transaction per document can be open at any given time”. Tên transaction chính là dòng người dùng nhìn thấy sau đó trên menu Undo của Revit.
4. File manifest .addin đặt ở đâu
Một add-in gồm file DLL đã biên dịch cộng một file XML nhỏ đuôi .addin. Revit đọc manifest từ hai thư mục: thư mục chung C:\ProgramData\Autodesk\Revit\Addins\<năm>\ và thư mục riêng từng user %AppData%\Autodesk\Revit\Addins\<năm>\. File ở cả hai nơi được xét chung và nạp theo thứ tự alphabet. Bạn không cần file MSI để test — thả một file XML vào thư mục user là xong phần cài đặt, lại không cần quyền admin.
Một Revit add-in tối giản, đủ từ đầu đến cuối
Ba file. Đưa cho AI đúng khung này, nó sẽ điền logic thật của bạn vào thay vì tự bịa ra cấu trúc project.
File project (Welcome.csproj), nhắm Revit 2026:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0-windows</TargetFramework>
<PlatformTarget>x64</PlatformTarget>
<UseWPF>true</UseWPF>
</PropertyGroup>
<ItemGroup>
<Reference Include="RevitAPI">
<HintPath>C:\Program Files\Autodesk\Revit 2026\RevitAPI.dll</HintPath>
<Private>false</Private>
</Reference>
<Reference Include="RevitAPIUI">
<HintPath>C:\Program Files\Autodesk\Revit 2026\RevitAPIUI.dll</HintPath>
<Private>false</Private>
</Reference>
</ItemGroup>
</Project><Private>false</Private> chính là tên gọi của Copy Local = No trong MSBuild.
File lệnh (TagSelectionCommand.cs). Nó ghi vào tham số Comments của những gì đang chọn — đủ để dùng một transaction thật:
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
namespace Welcome
{
[Transaction(TransactionMode.Manual)]
public class TagSelectionCommand : IExternalCommand
{
public Result Execute(ExternalCommandData commandData,
ref string message,
ElementSet elements)
{
var uiDocument = commandData.Application.ActiveUIDocument;
var document = uiDocument.Document;
var selected = uiDocument.Selection.GetElementIds();
if (selected.Count == 0)
{
message = "Select at least one element first.";
return Result.Cancelled;
}
// The transaction name is what appears on Revit's Undo menu.
using (var transaction = new Transaction(document, "Tag selection"))
{
transaction.Start();
foreach (var id in selected)
{
var parameter = document.GetElement(id).LookupParameter("Comments");
// Revit 2024+: ElementId.Value is a 64-bit long.
// On Revit 2022-2023 this line is id.IntegerValue instead.
parameter?.Set("Tagged " + id.Value);
}
transaction.Commit();
}
TaskDialog.Show("Welcome", selected.Count + " element(s) updated.");
return Result.Succeeded;
}
}
}File manifest (Welcome.addin). Hãy sinh GUID mới cho AddInId — hai add-in trùng id là xung đột thật, không phải thủ tục hình thức:
<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
<AddIn Type="Command">
<Text>Tag Selection</Text>
<Assembly>D:\welcome\bin\Debug\net8.0-windows\Welcome.dll</Assembly>
<AddInId>f1a2b3c4-1111-4222-8333-abcdef123456</AddInId>
<FullClassName>Welcome.TagSelectionCommand</FullClassName>
<VendorId>YOURCO</VendorId>
<VendorDescription>Your Company, yourcompany.com</VendorDescription>
</AddIn>
</RevitAddIns>Với IExternalCommand, các phần tử bắt buộc là Assembly, AddInId, FullClassName, Text và VendorId. Dùng Type="Application" cùng phần tử Name thay cho Text khi bạn cài đặt IExternalApplication — đây mới là thứ cần để tự thêm tab và nút riêng lên ribbon.
Cài trong mười giây, debug trong hai mươi
Chép Welcome.addin vào %AppData%\Autodesk\Revit\Addins\2026\ rồi mở Revit. Lệnh xuất hiện ở Add-Ins > External Tools. Vì manifest trỏ thẳng bằng đường dẫn tuyệt đối tới thư mục output, mỗi lần build lại là bản mới có hiệu lực ngay lần mở Revit kế tiếp — không installer, không bước copy, đây là khác biệt giữa vòng lặp hai phút và vòng lặp hai mươi giây.
Về debug, hướng dẫn của Autodesk rất gọn: mở Revit trước, rồi trong Visual Studio chọn Debug > Attach To Process và chọn Revit.exe. Breakpoint trong lệnh của bạn sẽ dừng bình thường. Autodesk ghi yêu cầu là Visual Studio 2022 Professional hoặc Community cho C# và VB.NET, và lưu ý bản Express không hỗ trợ debug DLL. Không phải mua thêm gì: Revit API đi kèm chính Revit.
Năm lỗi AI hay mắc khi viết code Revit add-in
Đây là những điều đáng dán thẳng vào prompt như ràng buộc, vì mỗi cái đều tạo ra một plugin trông như đã xong mà thực ra chưa.
- Dùng
ElementId.IntegerValuethay vìElementId.Value. Revit 2024 mở rộng kiểu lưu trữ bên trong của ElementId từ 32-bit lên 64-bit.IntegerValuebị deprecated và “sẽ ném exception nếu gọi trên một ElementId có giá trị đủ lớn cần hơn 32 bit để mô tả”, còn constructor giờ nhậnSystem.Int64. Hầu hết mã mẫu Revit công khai có trước thay đổi đó, nên đây là lời gọi API lỗi thời dễ gặp nhất trong code AI sinh ra — và nó hỏng lúc chạy trên model lớn, không phải lúc biên dịch. - Sửa model ngoài transaction. AI viết xong vòng lặp nhưng quên bọc
using (var transaction = new Transaction(document, "...")), và bạn nhận exception ngay lầnSetđầu tiên. Hãy yêu cầu transaction một cách rõ ràng. - Thiếu hoặc sai attribute
[Transaction(...)]. Không có giá trị mặc định, nên bỏ trống không phải là “phương án an toàn”. Và lệnh khaiReadOnlythì sau đó không mở được transaction. - Sai target framework. Bạn yêu cầu Revit 2024 mà nhận về
net8.0-windows, add-in sẽ không bao giờ nạp. Đây là kiểu hỏng không hề có thông báo lỗi, nên cũng là kiểu ngốn của bạn cả buổi chiều. - Để Copy Local bật cho hai assembly Revit. Không triệu chứng gì, cho tới ngày một phép ép kiểu hỏng mà không rõ lý do.
Thêm một thói quen rút ra từ việc phát hành add-in thương mại: biên dịch theo phiên bản Revit API THẤP NHẤT trong mỗi dòng runtime, không phải bản mới nhất. Binary build theo API Revit 2022 nạp được cho cả 2022–2024; bản build theo 2025 phủ 2025–2026. Build theo 2024 là bạn đã âm thầm bỏ rơi người dùng 2022 và 2023. Plugin Metasheet của chúng tôi làm đúng như vậy: mỗi dòng runtime một bản build (net48, net8.0-windows, net10.0-windows), phủ Revit 2022 đến 2027 từ một cây mã nguồn duy nhất.
Khi câu trả lời không phải là viết add-in
Cách làm Revit add-in bằng AI phủ được khá nhiều yêu cầu công cụ nội bộ nhỏ trong một văn phòng thiết kế. Nó phủ ít hơn kỳ vọng với geometry, tạo family, và bất cứ thứ gì có cấu trúc dữ liệu lớn phía sau; ở đó bạn cần một lập trình viên điều khiển AI, mở sẵn RevitLookup để soi element, chứ không phải ngược lại.
Và phần lớn các yêu cầu kiểu này thật ra không phải yêu cầu plugin. Sửa tham số hàng loạt, đổi tên sheet, dọn dữ liệu room — đó là việc bảng tính được ai đó mô tả thành plugin. Metasheet, trình sửa tham số Revit miễn phí của chúng tôi đã làm sẵn: đủ mọi tính năng kể cả tìm và thay thế hàng loạt, Revit 2022–2027, chỉ cần tài khoản 3dshouse miễn phí để đăng nhập. Nó cũng chính là add-in mà các ví dụ bên trên rút ra, nên bạn thấy được hình hài một add-in đã phát hành. Các lựa chọn khác được so sánh trong bài plugin Revit nhập xuất Excel. Nếu công cụ bạn cần thật sự chưa tồn tại, chúng tôi cũng nhận viết Revit add-in theo yêu cầu.
Câu hỏi thường gặp
Plugin Revit viết bằng ChatGPT hay Claude có chạy thật không?
Có, với một lệnh độc lập. Cả hai hãng đều có công cụ dạng agent tự sửa file và chạy lệnh build ngay trên máy, nên mô hình có thể tạo project, biên dịch, và tự đặt file manifest .addin. Thứ nó không đoán được là phiên bản Revit của bạn — mà riêng dữ kiện đó quyết định target framework, tập API và việc plugin có nạp được hay không.
Revit 2024 add-in cần .NET Framework nào?
.NET Framework 4.8, theo trang Development Requirements của Autodesk cho bản đó — moniker net48. Revit 2025 và 2026 cần .NET 8 (net8.0-windows), Revit 2027 cần .NET 10 (net10.0-windows). Dòng 4.8 dừng ở Revit 2024.
Cần gì để bắt đầu lập trình plugin Revit?
Bản thân Revit, Visual Studio 2022 Professional hoặc Community, và tham chiếu tới RevitAPI.dll cùng RevitAPIUI.dll trong thư mục cài Revit. Autodesk hỗ trợ C# và VB.NET. API không tốn thêm chi phí, và trong lúc phát triển bạn có thể bỏ hẳn installer bằng cách đặt file .addin vào thư mục Addins của user.
