7 Bước căn bản để xây dựng một add-in Revit

Nếu bạn định hướng nghề nghiệp bản thân theo con đường B.I.M, chắc hẳn bạn nên biết khái quát về cách xây dựng một add-in Revit bằng Revit API. Đối với những ai đã, đang và sẽ là Revit Developer, các bước sau đây phải được học nằm lòng. Sau đây bimdev.vn xin giới thiệu 7 bước căn bản để xây dựng một add-in Revit.

Bây giờ, bạn hãy ngồi ngay ngắn và hít một hơi thật sâu trước khi tiếp tục bài viết này. Bạn phải sốc lại tinh thần một tí vì mình chia sẻ bài viết này khá dài để trình bày một chi tiết và cụ thể các bước xây dựng add-in Revit.

stay focus

Bước 0: Chuẩn bị công cụ

Để xây dựng add-in Revit, chắc chắn bạn cần phải cài đặt tối thiểu 2 phần mềm: Autodesk Revit và Visual Studio.

Autodesk Revit dùng để chạy thử add-in trên máy cá nhân, để mô phỏng, kiểm tra lỗi, trường hợp phát sinh và hoàn thiện sản phẩm. Do mỗi phiên bản sẽ có một số thay đổi, bạn nên sử dụng phiên bản Autodesk Revit phù hợp với phiên bản sẽ chạy thực tế project bằng add-in.
Visual Studio dùng để xây dựng dự án add-in của bạn. Visual Studio cung cấp các cung cụ mạnh mẽ để xây dựng và phát triển dự án lập trình (intellisense, debug, nugget …). Bạn có thể download và sử dụng phiên bản Visual Studio để tận dụng các tính năng mới nhất của nó.

autodesk revit and visual studio

Ngoài 2 phần mềm chính yếu kể trên, một số add-in ngoài của Revit phục vụ tốt trong quá trình xây dựng và hoàn thiện add-in Revit có thể kể đến là Addin Manager và Revit Lookup.

Sử dụng các add-in ngoài như Addin Manager hoặc Revit Lookup

Bước 1: Tạo dự án thuộc loại Class Library

Phần mềm Autodesk Revit đọc hiểu các add-in Revit format theo định dạng thư viện động (.dll). Các dự án add-in này có thể được xây dựng trong Visual Studio khi chọn Project Type là Class Library.

Class Library project to DLL file

Chọn ngôn ngữ C# hoặc Visual Basic để phát triển dự án phù hợp với ngôn ngữ lập trình bạn đang sử dụng.

Ở đây sẽ có hai thư viện framework bạn có thể lựa chọn như: .NET Framework và .NET Core phù hợp với các loại dự án. Khi xây dựng add-in Revit, bạn nên sử dụng bộ thư viện .NET Framework đề phù hợp với framework của Revit API và dễ dàng debug bằng Addin Manager.

.NET framework vs .NET Core

Đặt tên dự án, chọn đường dẫn, tên Solution và phiên bản Framework phù hợp

Tên Solution nên trùng tên với tên dự án cho dễ quản lý. Tuy nhiên bạn có thể đổi tên Solution tùy thích sau khi khởi tạo dự án.
Mỗi phiên bản Framework sẽ có sự thay đổi so với các phiên bản trước đó, thông thường Framework mới sẽ cải tiến và tương thích với phiên bản cũ. Bạn phải chọn phiên bản Framewok tương thích với Framework của phần mềm Autodesk Revit đang sử dụng (bằng hoặc cao hơn Frameowork của phần mềm Autodesk Revit)

Các bước khởi tạo dự án Class Library

Ở đây mình đang demo khởi tạo dự án trên phần mềm Visual Studio 2019 Preview:

Tùy chỉnh Framework version dự án

Bạn cũng có thể kiểm tra .NET Framework version và thiết lập lại cho phù hợp như sau:

Bước 2: Thêm các file *.dll định nghĩa thư viện Revit API

Autodesk đã xây dựng một hệ thống các class, interface có tổ chức, mạnh mẽ và phức tạp với các file *.dll để phục vụ các lập trình viên. Hai file *.dll cần thiết để phát triển add-in Revit là RevitAPI.dll và RevitAPIUI.dll.

Revit API

RevitAPI.dll : thư viện chứa các class và interface để xử lý các đối tượng trong dữ liệu dự án và ứng dụng (Dầm, sàn, Level, View, Document …)
RevitAPIUI.dll : thư viện chứa các class và interface để xử lý giao diện người dùng Revit (hộp thoại, thanh Ribbon, nút lệnh …)

Các bước thêm file thư viện Revit API

Bước 3: Tạo các class thực thi interface IExternalCommand

Phần mềm Autodesk Revit sẽ tìm kiếm trong file *.dll của bạn các class thực thi interface IExternalCommand. Các class thõa mãn điều kiện trên sẽ có thể trở thành các nút lệnh (command) trên thanh công cụ Revit sau khi hoàn thành.

interface and class

Ví dụ, bạn muốn tạo ra 3 nút lệnh trên thanh công cụ, bạn phải tạo ra 3 class thực thi interface IExternalCommand.

implement interface IExternalCommnad

Để một class thực thi interface hợp lệ, class cần chứa các phương thức và thuộc tính bên trong interface, với từ khóa truy cập là public.

Interface IExternalCommand có chứa một phương thức là Execute:

Execute là khối lệnh quy định kịch bản thực hiện khi người dùng click vào nút lệnh.
Execute cần 3 tham số truyền vào ExternalCommandData commandData, ref string message và ElementSet elements. Bạn hãy viết lại phương thức với từ khóa truy cập public một cách chính xác và đầy đủ.
Execute cần trả về một giá trị thuộc kiểu enum là Result. Bạn có thể thêm vào return Result.Succeeded; nghĩa là nút lệnh thực thi thành công.

Các bước xây dựng class thực thi interface IExternalCommand:

Bước 4: Xây dựng kịch bản, sửa lỗi và hoàn thiện sản phẩm

Sau khi đã nắm được các kĩ thuật và kiến thức cốt lõi, đây là phần quan trọng nhất trong quá trình xây dựng add-in Revit. Bạn phải đầu tư không ít chất xám để xây dựng kịch bản người dùng và sửa lỗi.

Thông thường một add-in Revit tốt nên thoả mãn các tiêu chí sau:

Có kịch bản rõ ràng, dễ hiểu và dễ thực hiện, người dùng nắm được concept của add-in
Có giao diện người dùng (User Interface) và giao diện phải rõ ràng, dễ hiểu
Khả năng tùy chỉnh các thông số thiết lập, gợi ý thông số mặc định và template người dùng
Giải quyết các trường hợp điển hình và một số ngoại lệ. Nếu chưa giải quyết được một trường hợp phức tạp, phải thông báo người dùng và có kế hoạch xử lý
Hạn chế và có biện pháp phòng ngừa khi lỗi xảy ra

Revit addin concepts and content thinking

Để xây dựng tốt một dự án lập trình, bạn cần phải có một ý tưởng kịch bản khả thi trước khi bắt đầu viết code. Bạn cần các kiến thức nền tảng của ngôn ngữ lập trình (C#) cũng như kĩ năng tư duy lập trình, các bộ thư viện ngoài cần thiết.

Đoạn code minh họa: Chọn đối tượng dầm trong view và xuất thông tin Level của nó

Trong quá trình hoàn thiện sản phẩm, nên test dự án trên nhiều dạng bài toán mô phỏng với các điều kiện khác nhau, thỏa mãn dự án thực tế sau này.

Sử dụng các add-in ngoài như Addin Manager và Revit Lookup để viết code hiệu quả hơn.

Sử dụng các add-in ngoài như Addin Manager hoặc Revit Lookup

Bước 5: Tạo class thực thi interface IExternalApplication (tùy chọn)

Đây là một bước tùy chọn trong quá trình xây dựng add-in Revit, bạn có thể bỏ qua.

Xây dựng class thực thi interface IExternalApplication để có thể can thiệp vào quá trình tắt mở ứng dụng Autodesk Revit. Đồng thời bạn cũng có thể can thiệp vào các sự kiện (event) trong quá trình thao tác trên ứng dụng.

interface and class

Các dự án add-in Revit tốt thường đi kèm với bộ nút lệnh (Button) trên thanh Ribbon Revit. Điều đó có thể can thiệp bằng cách xây dựng class thực thi IExternalApplication.

implement IExternalApplication and add Tab Panel Button

Interface IExternalApplication có chứa một phương thức là OnStartup và OnShutdown:

OnStartup là phương thức dùng để can thiệp vào quá trình khởi động ứng dụng Revit. OnShutdown dùng để can thiệp vào quá trình tắt ứng dụng Revit.
Cả hai phương thức đều nhận tham số là UIControlledApplication application. Đây là tham số để thiết lập các thông tin liên quan ứng dụng hoặc các sự kiện bên trong.
Cả hai phương thức cần trả về một giá trị thuộc kiểu enum là Result. Bạn nên thêm vào return Result.Succeed; nghĩa là phương thức thực thi thành công.

Các bước xây dựng class thực thi interface IExternalApplication:

Bước 6: Thiết lập file thông tin *.addin

Phần mềm Autodesk Revit quản lý các add-in ngoài bằng các file có định dạng *.addin gọi là các file thông tin. Các file thông tin quy định các thông tin về addin (tên, mô tả, mã addin, đường dẫn, code thực thi …). Khi khởi động ứng dụng Autodesk Revit, ứng dụng sẽ tra cứu và đọc các file thông tin để xác định các thông tin trước khi tích hợp vào giao diện.

Xây dựng một **file thông tin (*.addin)**

File *.addin được viết theo ngôn ngữ xml và đọc hiểu bởi phần mềm Autodesk Revit.

Trong ngôn ngữ xml, mỗi thẻ tag <a></a> ứng với một đối tượng được tạo ra thuộc kiểu tương ứng:

Thể hiện kiểu dữ liệu của đối tượng: <a></a> tạo đối tượng thuộc kiểu a
Chứa các thông tin thuộc tính đối tượng: <a ten_thuoc_tinh = “gia_tri_thuoc_tinh”></a>
Có thể chưa các đối tượng con bên trong. Ví dụ, <a> <b></b> </a> nghĩa là đối tượng kiểu a có một thuộc tính thuộc kiểu dữ liệu b.

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Application">
    <Name>RevitAddin_1</Name>
    <Name>Demo Revit Addin</Name>
    <Assembly>RevitAddin_1.dll</Assembly>
    <FullClassName>RevitAddin_1.App</FullClassName>
    <ClientId>b7f7b3f9-a601-47b1-a4ad-2391115e26ad</ClientId>
    <VendorId>BIM-Dev</VendorId>
    <VendorDescription>BIM-Dev Việt Nam, Giải pháp triển khai và ứng dụng B.I.M</VendorDescription>
  </AddIn>
</RevitAddIns>

Bạn có thể tải về file *.addin theo template mẫu tại đây.

tag Addin

tag Addin trong file *.addin định nghĩa một add-in bao gồm một hay một tập hợp nút lệnh được tích hợp vào phần mềm Autodesk Revit. Một file *.addin có thể định nghĩa nhiều tag Addin.

addin tag

tag Addin có thuộc tính Type quy định 2 loại Addin:

Command: Nút lệnh tích hợp vào phần External Tools trong tab Add-Ins trên giao diện Revit.
Application: Nút lệnh tích hợp dưới dạng Button và nằm trong 1 tab bất kỳ trên thanh Ribbon Revit, tùy thuộc vào tùy chỉnh người dùng.

Ngoài ra, tag Addin còn có một số thuộc tính cần thiết khác. Thiết lập thuộc tính Type là Command hay Application sẽ ảnh hưởng đến giá trị của các thuộc tính khác.

addin tag information

Name: tên add-in
Text: mô tả thông tin add-in
Assembly: đường dẫn file *.dll chứa nút lệnh
FullClassName: tên đầy đủ của class thực thi.
Đối với Addin loại Command, trỏ đến class thực thi interface IExternalCommand
Đối với Addin loại Application, trỏ đến class thực thi interface IExternalApplication
ClientId: mã Add-in, sử dụng bộ mã GUID, mỗi add-in được nhận diện bằng một mã GUID duy nhất, bạn có thể lấy một mã GUID duy nhất trên website: https://www.guidgenerator.com/online-guid-generator.aspx

addin guid binding

VendorId: tên tác giả
VendorDescription: mô tả về tác giả

Thiết lập Build Action

Mục đích thiết lập Build Action trong trường hợp này để copy file trong folder Output để thuận tiện trong quản lý.

Các bước xây dựng file *.addin thiết lập thông tin add-in

Bước 7: Đóng gói add-in

Sau khi thực hiện đầy đủ 6 bước căn bản kể trên, bạn đã tiến tới bước cuối cùng trong chu trình xây dựng một add-in Revit.

class library project combine

Ở bước cuối cùng này, bạn sẽ load dự án add-in của bạn vào ứng dụng Autodesk Revit. Click button để chạy thử add-in và kiểm tra có lỗi phát sinh hay không.

Nếu có lỗi xảy ra, bạn hãy kiểm tra lại các bước thực hiện của mình đã đúng với các bước trên đây không nhé.

Các bước đóng gói và chạy thử add-in

Kết luận

Trên đây, bimdev.vn đã giới thiệu các bạn 7 bước căn bản để xây dựng một add-in Revit. Mình hi vọng bài viết sẽ hữu ích cho những ai đang và sẽ phát triển con đường B.I.M. Hãy thực hành ngay bây giờ để có được kết quả như mong muốn.

Cảm ơn bạn đã quan tâm bài viết của mình, nếu thấy hữu ích, bạn có thể chia sẻ đến những người khác.

Chúc bạn thành công!

success