برنامه‌نویسی Revit API، آنچه می‌توان ساخت و آنچه افزونه‌ی قابل‌اتکا لازم دارد

Revit API یک کتابخانه‌ی .NET است که همراه رویت نصب می‌شود. Autodesk آن را رابطی معرفی می‌کند که امکان خودکارسازی کارهای تکراری و گسترش قابلیت‌های اصلی نرم‌افزار را فراهم می‌کند. افزونه درون فرآیند خود رویت بارگذاری می‌شود و با همان اشیایی کار می‌کند که رویت برای مدل باز استفاده می‌کند.

تقریباً همه‌چیز در مدل یک Element است: دیوارها، درها، ویوها، شیت‌ها و حتی تایپ‌هایی که آن‌ها را تعریف می‌کنند. کد، المان‌ها را با FilteredElementCollector پیدا می‌کند، پارامترهای آن‌ها را می‌خواند و می‌نویسد و المان‌های جدید می‌سازد. هر تغییر در مدل درون یک Transaction انجام می‌شود و همین تراکنش به‌صورت یک مرحله در فهرست Undo رویت نمایش داده می‌شود.

رویت طول‌ها را به‌صورت داخلی بر حسب فوت اعشاری ذخیره می‌کند. در نتیجه، دفتری که هرگز چیزی را با فوت اندازه نگرفته است نیز طول همه‌ی دیوارها را از API بر حسب فوت دریافت می‌کند و افزونه باید پیش از نمایش هر عدد، آن را تبدیل کند.

همه‌ی کارهای رویت به افزونه‌ی کامپایل‌شده نیاز ندارند. Revit API از پنج مسیر در دسترس است و انتخاب مسیر مناسب به این بستگی دارد که چه کسی ابزار را اجرا می‌کند و هر چند وقت یک‌بار:

• Macro: کدهای C# که در Macro Manager خود رویت نوشته و همراه مدل یا برنامه ذخیره می‌شوند. برای کارهای کوچک شخصی مناسب هستند و اشتراک‌گذاری آن‌ها دشوار است.
• Dynamo: گراف‌های بصری همراه با نودهای Python که کاربر نیازمند نتیجه، خود آن‌ها را اجرا می‌کند. توسعه‌ی اسکریپت اختصاصی Dynamo توضیح می‌دهد چه زمانی یک گراف کافی است.
• pyRevit: چارچوبی متن‌باز که اسکریپت‌های Python را به دکمه‌های ریبون تبدیل می‌کند و برای نوار ابزار اختصاصی دفاتر رایج است.
• افزونه‌ی کامپایل‌شده: پروژه‌ی C# که در Visual Studio ساخته و با یک فایل manifest نصب می‌شود و ریبون، پنجره‌ها و تنظیمات خود را دارد. منظور بیشتر افراد از پلاگین رویت همین گزینه است.
• Design Automation for Revit: بخشی از Autodesk Platform Services، سکویی که پیش‌تر Forge نام داشت. این سرویس رویت را بدون رابط کاربری در فضای ابری Autodesk اجرا می‌کند، به‌گونه‌ای که افزونه بتواند مدل‌ها را از یک صفحه‌ی وب یا یک پردازش دسته‌ای پردازش کند و ورودی‌ها را به‌جای پنجره‌های گفت‌وگو از فایل بخواند.

کارهایی که پیش‌تر با نام توسعه‌ی Autodesk Forge API شناخته می‌شدند، امروز با نام APS انجام می‌شوند. برای رویت، این کار معمولاً به معنای Design Automation است و افزونه‌ای که در آن اجرا می‌شود، از همان قواعد API نسخه‌ی دسکتاپ پیروی می‌کند.

هر فرمان، کلاسی است که رابط IExternalCommand را پیاده‌سازی می‌کند. رویت با کلیک کاربر روی دکمه، متد Execute آن را فراخوانی می‌کند و پس از پایان متد، شیء فرمان را کنار می‌گذارد. یک فایل manifest با پسوند ‎.addin در پوشه‌ی Addins رویت، وجود فرمان را به رویت اعلام می‌کند و بدون آن، رویت کد را شناسایی نمی‌کند.

افزونه‌ای که زبانه‌ی ریبون اختصاصی دارد، یک IExternalApplication نیز دارد که هنگام شروع رویت، پنل‌ها و دکمه‌ها را می‌سازد. ویژگی TransactionMode روی هر فرمان مشخص می‌کند چه کسی تراکنش‌ها را باز می‌کند. در حالت Manual، فرمان تراکنش‌های خود را باز می‌کند و می‌تواند چند تراکنش را در یک مرحله‌ی Undo گروه‌بندی کند.

یک قاعده بیشتر نخستین افزونه‌ها را متوقف می‌کند: API فقط از رشته‌ی اجرایی خود رویت و زمانی که رویت آماده‌ی پذیرش درخواست است، قابل‌فراخوانی است. پنجره‌ای که در کنار مدل باز می‌ماند، باید کار خود را از طریق یک ExternalEvent به رویت بسپارد. فراخوانی مستقیم API از چنین پنجره‌ای با خطا متوقف می‌شود.

درخواست‌هایی که به برنامه‌نویس رویت می‌رسند، معمولاً در این گروه‌ها قرار می‌گیرند:

• کنترل‌ها: افزونه‌هایی که مدل را می‌خوانند و گزارش می‌دهند، از نام‌گذاری و پارامترهای خالی تا هشدارها و اتاق‌های بدون مرز. کنترل‌کننده مدل رویت بخش قاعده‌محور این کار را توضیح می‌دهد.
• ویرایش دسته‌ای: شماره‌گذاری دوباره‌ی شیت‌ها و ویوها، تغییر نام فمیلی‌ها و پرکردن فیلدهای کادر نقشه در یک مجموعه.
• ساخت مدل از داده‌های دیگر: دیوارها از خطوط CAD، اسکلت سازه از مدل تحلیلی و نازک‌کاری از مرز اتاق‌ها.
• تبادل داده: اسکجوال‌ها به Excel و بازگشت آن‌ها به مدل، پارامترها به پایگاه داده و گزارش‌ها به داشبورد.
• افزونه‌های اختصاصی تأسیسات: نام‌گذاری سیستم‌ها، کنترل کانکتورها، قواعد سایزبندی و جانمایی آویزها، در جایی که ابزارهای MEP رویت با استاندارد دفتر هم‌خوانی ندارند.

تبدیل خودکار CAD به رویت نمونه‌ی ساخت مدل از داده‌های دیگر را با جزئیات بررسی می‌کند.

Autodesk هر سال یک نسخه‌ی جدید رویت منتشر می‌کند و هر افزونه برای نسخه‌ی مشخصی از API کامپایل می‌شود. بیشتر کد به نسخه‌ی بعد منتقل می‌شود، اما متدهای منسوخ حذف می‌شوند و هر نسخه به ساخت، تست و فایل نصب جداگانه نیاز دارد.

Revit 2025 بزرگ‌ترین تغییر سال‌های اخیر بود. به گفته‌ی مستندات API، این نسخه روی .NET 8 ساخته شده و افزونه‌ها باید برای .NET 8 دوباره کامپایل شوند. Revit 2024 روی .NET Framework 4.8 اجرا می‌شد، در نتیجه دفتری که از هر دو نسخه استفاده می‌کند، به دو خروجی نیاز دارد. یک پروژه با چند Target Framework، هر دو خروجی را از یک کد واحد می‌سازد.

هنگام سفارش افزونه بپرسید این کار در هر نسخه‌ی جدید بر عهده‌ی چه کسی است و چه هزینه‌ای دارد.

مدل آزمایشی تمیز است، اما مدل‌های واقعی این‌گونه نیستند. بیشترین زمان توسعه صرف این موارد می‌شود:

• کار اشتراکی (Worksharing): المانی که کاربر دیگری در اختیار دارد قابل‌ویرایش نیست و افزونه باید اعلام کند کدام المان‌ها را کنار گذاشته است.
• مدل‌های لینک‌شده: المان‌های درون لینک از مدل میزبان فقط‌خواندنی هستند و در دستگاه مختصات دیگری قرار دارند.
• هشدارها و خطاها: تغییری که نمونه‌های تکراری یا دیوارهای هم‌پوشان ایجاد می‌کند، خطاهایی به وجود می‌آورد که افزونه باید خود آن‌ها را مدیریت کند و پنجره‌ی هشدار را برای کاربر باقی نگذارد.
• مقیاس: جست‌وجویی که همه‌ی المان‌ها را با فیلتری کند بررسی می‌کند، در فایل آزمایشی سریع و در مدل یک بیمارستان کند است. فیلترهای سریع بر اساس کلاس و دسته باید پیش از بقیه اجرا شوند.
• گزارش: هر المانی که افزونه نتوانسته پردازش کند، همراه با دلیل آن.

هیچ‌کدام از این موارد در نمایش اولیه‌ی افزونه دیده نمی‌شود و همه‌ی آن‌ها در هفته‌ی نخست استفاده روی پروژه‌های واقعی ظاهر می‌شوند.

اگر با C# آشنا هستید، مسیر یادگیری مشخص است: نمونه‌های Revit SDK، مستندات API در سایت revitapidocs.com و افزونه‌ی RevitLookup برای بررسی داده‌هایی که هر المان در خود دارد. با یک Macro یا یک فرمان ساده شروع کنید و ساخت ریبون را به مرحله‌ی بعد بسپارید.

اگر کار فقط یک‌بار انجام می‌شود یا یک گراف Dynamo همین حالا آن را انجام می‌دهد، سفارش افزونه ضرورتی ندارد و برای آن به ما یا شرکتی مانند ما نیازی ندارید. خدمات برنامه‌نویسی Revit API زمانی ارزش هزینه‌ی خود را دارند که ابزار در پروژه‌های مختلف، توسط افرادی غیر از سازنده‌ی آن و در چند نسخه‌ی رویت استفاده شود. نوشته‌ی توسعه پلاگین رویت چقدر هزینه دارد عوامل مؤثر بر قیمت را شرح می‌دهد و این کار در قالب خدمات توسعه پلاگین رویت انجام می‌شود.