[營建知訊轉載]Revit 2012 API初學筆記(01) 郭榮欽 (2012.03)

國立臺灣大學土木工程學系　工程資訊模擬與管理研究中心　郭榮欽執行長
 
許多工程界朋友試圖使用Autodesk Revit系列產品進行工程專案建模工作，做為踏入BIM技術領域的實作工具，有些人大概很快就會想進一步學Revit API(Application Programming Interface)，原因是BIM技術理念所揭櫫的願景和目前Revit系列產品能呈現的功能之間，似乎有些落差(雖然看起來潛力仍大)，期望透過Revit API工具開發應用程式的途徑，來補強自己在工程作業上的需求。
從這幾年來Autodesk對BIM相關技術的工具改善及推展動作之積極，可以看出全世界工程界對此期待之殷切，也可看出市場競爭的白熱化。Autodesk深知工程資訊技術涵蓋面之龐雜與區域特性之迥異，不易用一套固定的軟體工具來滿足大家，故提供API來彌補與應急。
Autodesk為了爭取BIM的市場，在Revit工具的推廣方面下了非常大的功夫，包括自家網站在BIM理念與相關工具、實作案例的介紹外，大量的AU(Autodesk University)課程與頻頻舉辦之研討會、Youtube教學視訊、許多專家的部落格等等，還有新推出的Autodesk WikiHelp使用導覽，管道之多，涉及層面之廣，真可謂撲天蓋地、勢在必得。
2012版的Revit Platform API可用Microsoft .NET Framework 4.0相容的任何語言來執行，例如Visual Basic .NET或Visual C#、C++等。通常Visual C# 和 VB.NET是較常見到被使用來開發Revit Platform API應用程式； 而我個人的學習之旅係以Visual C#語言及Revit Architecture API為主。整個學習除了參考上述許多文獻說明資料以外，主要係以「Revit 2012 API Developer Guide」[01]為藍本，為考慮國人習慣，因此操作步驟之說明圖文皆以繁體中文作業環境為主。

一、準備工作
要開始學習Revit Platform API，需要先準備好下列幾件工作：
(一)、安裝Microsoft Visual Studio 2010[02]

圖1、繁體中文版的Microsoft Visual Studio 2010起始畫面

圖2、繁體中文版的Autodesk Revit Architecture 2012 起始畫面

(二)、安裝Autodesk_Revit_Architecture_2012_Traditional_Chinese_Win_32-64bit.exe

二、創建一個新專案
首先我嘗試使用Revit Platform API 和 Visual Studio 2010的C#，依照「Revit 2012 API Developer Guide」所指示的步驟來創建第一個練習程式：Hello World程式。第一個動作是開啟Microsoft的Visual Studio 2010：
(一)、從檔案功能表裡，選按新增 > 專案 …(如圖3)，會出現『新增專案』視窗(圖4)。

圖3、在Microsoft Visual Studio新增一專案

(二)、在『新增專案』視窗的左側，已安裝的範本頁框下，選按 Visual C#語言(如圖4)。
(三)、在中央頁框處，點按類別庫(如圖4)。這個演練假設專案位置在D:\Sample。

圖4、在Microsoft Visual Studio『新增專案』視窗的操作

(四)、在下方名稱(N):欄框中，鍵入HelloWorld，做為專案名稱。然後按確定進入VS.NET編輯畫面。
​
三、加入「參考」(這是個關鍵動作)
(一)、將RevitAPI.dll的「參考」檔案加進專案中

1. 若右上角的方案總管視窗沒打開，可以從檢視功能表裡點選方案總管功能項。
2. 在方案總管視窗裡，方案的項目樹中參考處按右鍵會顯示一個文字小功能表(如圖5)。
3. 在此文字小功能表中，選按加入參考功能項。

圖5、加入「參考」

4 在加入參考對話方塊裡，點選瀏覽標籤，再找到C:\Program Files\Autodesk\Revit Architecture 2012\Program\RevitAPI.dll.，選上RevitAPI.dll檔。(如圖6)

圖6、將RevitAPI.dll的「參考」檔案加進HelloWorld專案中

5.點按確定，選此.dll檔並關閉對話方塊，RevitAPI會出現在方案總總管\參考的樹狀架構內。並且將複製到本機的屬性改為False，可以節省磁碟空間。(如圖7)​

圖7、將複製到本機的屬性改為False

(二)、重複上述(一)的每個動作，將另一個「參考」檔案RevitAPIUI.dll加進專案中。
 
四、開始撰寫程式碼
(一)、加入下列程式碼來創建第一個增益集功能。
第一個練習程式很單純，只為了能在Revit Architecture環境內執行一個對話框，在對話框中只出現” Revit 2012 API初學上路 – 郭榮欽”字樣，下列程式先如法泡製複製到VS.NET的HelloWorld專案中，先確保流程順利完成，內容細節的道理再慢慢從後續的範例發展回頭來理解。

由於每一個Revit增益集都必須有一個進入點的類別，以實作這個IExternalCommand介面，而我們必須執行這個Execute()方法。這個Execute()方法就是增益集的進入點，就好像一般程式的Main()方法一樣。

(二)、建置方案
完成程式碼撰寫之後，必須進行建置方案的動作。從建置功能表上，點按建置方案(B)功能，VS.NET會產生HelloWorld.dll的檔案。我們可以從檢視的輸出顯示，該專案編譯是否有錯誤。(如圖8所示)

圖8、建置方案並用檢視 > 輸出 來檢查編譯過程是否有錯

五、創建一個 .addin 的清單(manifest)檔案
專案經過建置完成無誤後，會輸出一個HelloWorld.dll檔案到專案目錄裡。如果我們想要在Revit中呼叫使用這個應用程式，就必需再做一個動作，就是創建一個清單(manifest)檔案，並放置在指定的路徑。

例如本例，需利用記事本，在其中創建一個純文字檔(即HelloWorld.addin檔)，內容如下：

將此檔儲存，取名為 HelloWorld.addin 。並且將此檔移到下述磁碟路徑：
·      若為Windows XP作業系統：
C:\Documents and Settings\All Users\Application Data\Autodesk\Revit\Addins\2012\ 
·      若為Vista / Windows 7 / Windows Server ：
C:\ProgramData\Autodesk\Revit\Addins\2012\
上述之C:\ProgramData路徑通常係隱藏狀態，需從資料夾選項 > 檢視 裡點選顯示所有檔案和資料夾一項(如圖9)，即可顯示。

圖9、從資料夾選項 > 檢視 裡打開隱藏檔與資料夾

六、開始使用增益集的外部工具程式
完成了前述(1).主程式建置，並產出HelloWorld.dll檔案，以及(2).HelloWorld.addin清單檔案，並移到指定的路徑後。我們可以執行Autodesk Revit Architecture軟體，進入編輯主畫面，此時，帶狀功能表中出現增益集功能表，點選後，下方左側出現外部工具按鍵，點按後，會出現HelloWorld功能標籤(如圖10)。

圖10、依序選按增益集 > 外部工具 > HelloWorld

如圖10點按HelloWorld的按鈕，一切都順利的話，螢幕中央會出現如圖11的小對話框，這就是為Revit API學習之旅踏出成功的第一步。

圖11、執行結果

.addin清單檔案不能取中文檔名，Autodesk無法解讀中文碼，若取中文檔名將出現如圖12所示之亂碼。

七、心得
看過一些Revit API應用的文獻資料，發現API雖能幫忙彌補許多Revit系統不足的地方，但似乎也有其力有未逮之處，而且API只能寄存於主軟體之下才能運作，施展的彈性會大打折扣，也是不得不考慮的現實。
雖然在Revit Architecture 2011版就曾學過API，但多以閱讀討論為主；正值新年初始，Autodesk Revit 2012版的建模工具與相關文獻也看了一些，親自操作學習的體驗與感受還是大不同。由於對Revit Architecture 2012所建的BIM模型有進一步應用之研究需求，就起了親自操作學習的念頭，確有不少的收穫。Revit軟體在近幾年，為因應營建業界的要求，與對BIM技術理想境界之追求，其功能應會繼續擴充與改善，相信其API的內涵亦會持續跟進發展(例如2012版的API將資料庫DB與使用者介面UI分開)。利用自修的機會將會持續將實作過程筆記整理成詳細的步驟內容，供讀者分享。
 
參考文獻
[01] Autodesk,”Revit 2012 API Developer’s Guide”
[02] 歐亘修, “Visual Studio 2010 Ultimate軟體工程實戰手冊(附範例檔) “,  碁峰 ，2010.12.13

圖12、.addin清單檔案若取中文檔名將出現亂碼