這系列是衛武資訊研發部的公司內部訓練教材,無私公開教大家基礎的API開發,將持續分享!

作者 | 葉人豪

在現今這個BIM概念越來越普遍的業界,BIM建模軟體已經慢慢成為我們製圖時主力工具。而在台灣,Revit更是BIM建模的主流軟體。當我們使用Revit建模的時候,常常會有一些相當零碎又重複性的工作出現或者Revit目前還沒有功能來達成我們的需求。當我們無法通過Revit的功能來解決我們的需求時,我們就需要找一些快速的方法來達成我們的目的。這時Revit API就是我們的好幫手。

Revit API是Revit提供予使用者的應用程式函式庫,聽不懂?沒關係!讓我們來用一個例子來比喻一下,簡單來說Revit就像是一間餐廳,Revit API就像是餐廳裡的服務生,我們可以通過跟服務生說我們想吃什麼來向餐廳點菜。而服務生就會幫我們跟餐廳說我們需要什麼,並拿來給我們。所以其實Revit API就是一個傳遞我們需求的角色,幫助我們與Revit做資訊上的傳遞(如圖一所示)。

圖一、使用者透過AP與Revit做資訊上的傳遞

不過,實際上的運作當然沒有上述的這麼簡單,我們需要具備一些能力及工具。首先我們要會說Revit API聽得懂的語言,也就是程式語言。這邊先說明一下Revit API聽得懂的程式語言,也就是C#或VB等基於.Net Framework的程式語言。在這系列中小編都會使用C#當作範例。再來我們需要一個可以寫程式的工具,這邊小編用的是Visual Studio。最後還需要我們的餐廳與服務生-Revit跟Revit API。Revit API可以到Autodesk Developer Network來下載,安裝後就會得到Revit API啦。在Revit API的資料夾裡,大家可以看看裡面所包含的東西,裡面的工具都相當的有用,有Autodesk所提供的範例檔,提供我們了解Revit API程式。也有Revit API的手冊讓我們了解各API的詳細功能。最後最重要的就是Add-in Manager這工具。在開發Revit API時,如果沒有Add-in Manager的幫助,我們會需要自行製作Revit API的addin文檔。
這邊我們先解釋一下文檔(.addin)的概念。addin其實是一個讓Revit去讀的檔案,其內部結構如下面的程式碼所示。

當Revit讀取addin時,Revit會了解到他現在需要加入這個外掛。addin本身包含了外掛程式的XML格式相關資訊,例如:程式的名稱、程式的類型、程式(.dll)的實體位置、程式的GUID、程式裡面的函式名稱等等的資訊。以下將用表格方式介紹。

表一、addin內部屬性註釋表

現在回到我們剛剛提到的在沒有Add-in Manager的幫助,我們需要自行製作addin的問題。自行製作addin相當的麻煩,我們首先要把上面提到的程式碼複製貼上一個文字檔中,再來依據我們Revit API程式的資訊更改Xml中內部的各項屬性資料。完成後將文字檔更改副檔名為addin,即完成了Revit API程式的addin製作。自行製作完addin後,還要再把addin部屬到Revit Addins資料夾中對應的版本資料夾,才可以進行測試,以上整個操作流程的示意圖如圖二所示。

圖二、無透過Add-in Manager狀態下製作與部屬addin

而若是addin中的API資料有錯誤,Revit就無法載入Revit API程式已進行測試。來來回回的檢查與開啟Revit相當的繁複,很容易浪費我們寶貴的時間。所以我們才需要Add-in Manager來幫助我們開發Revit API程式。Add-in Manager提供我們快速執行我們API程式的服務,而不需事先部署addin,也可以幫我們快速產生我們的API程式的addin等方便的功能。因此我們只要等到程式完成開發後來進行部屬,而不須在程式開發過程中進行部屬。在有Add-in Manager的幫助下進行部屬得流程大致如下:

圖三、透過Add-in Manager狀態下製作與部屬addin

所以說開發Revit API真是少不了Add-in Manager。那就先來介紹一下Revit API開發好朋友 – Add-in Manager。
Add-in Manager是一個Revit提供我們來快速測試我們自己編譯API程式與產生Revit API外掛資訊的.addin等功能的外掛工具。而要如何使用Add-In Manager呢? 本質上Add-In Manager也屬於Revit 的外掛,所以他的部屬方式跟一般Revit API一樣。需要把addin放進Revit Addins資料夾中對應的版本資料夾。
在 Revit SDK中的Add-In Manager資料夾裡,我們可以看到幾個檔案:AddInManager.dll、Autodesk.AddInManager.addin等。首先把Autodesk.AddInManager.addin用文字編輯器打開,這時我們可以看到像是如圖四一樣的文字。我們只要把下圖紅框處的文字改為AddInManager.dll於本機電腦中的實體位置就可以進行儲存。

圖四、Autodesk.AddInManager.addin文檔

然後再把Autodesk.AddInManager.addin這個檔案(附檔名須為addin)放到C:\ProgramData\Autodesk\Revit\Addins\Revit\中對應版本的資料夾中,我們就完成了Add-In Manager的addin部屬了。然後我們只要開啟Revit,Revit就會跟我們說他偵測到了一個新的.addin,並詢問是否載入這個檔案。這時只要點選永遠載入,就可以在Revit工具列的增益集的外部工具中看到Add-in Manager被加入了。
現在讓我們進入Revit來看看Add-in Manager到底長怎樣吧。進入Revit專案後,到外部工具中我們就可以看到Add-in Manager,開啟Add-in Manager就會開啟如圖五的視窗出現。

圖五、Add-in Manager畫面

在Add-in Manager的視窗中,我們可以看到有Command和Application兩個頁籤,在這邊我們可以把這兩頁頁籤視為Revit API的兩種形式-外部命令與外部應用程式。在本文中我們測試API程式時,都使用Command形式方便執行我們的API程式。而這兩種形式的分別,我們在本文中就不多做討論,等到以後有機會再跟大家分享。接下來就讓我們來實做一個Revit API程式,並應用Add-in Manager來做測試與文檔(.addin)的產生吧。
第一步我們先把程式的環境設定好。開啟Visual Studio建立一個新專案。這邊我們的專案類型要選擇類別庫(如下圖六所示),接著把專案名稱改為Hello World,並按下確定後,就成功建一個新的類別庫專案了。

圖六、新增專案畫面

那麼接下來我們要來把這個專案變成RevitAPI外掛程式。首先,在方案總管的參考中點選右鍵,並選擇加入參考(如下圖七所示)。

圖七、於專案中加入參考畫面

參考管理員的視窗就會出現,在視窗左邊的瀏覽頁籤中,按下右下角瀏覽的按鈕,並找到RevitAPI參考檔。參考檔的位置就在Revit安裝資料夾中,選擇RevitAPI.dll與RevitAPIUI.dll後,並按下確定。接下來就可以看到兩個參考檔出現在參考管理員的視窗中(如下圖八所示),按下確定就完成把參考檔加入程式步驟了。

圖八、加入Revit參考檔畫面

在這邊我們需要幫專案參考做一下設定來節省硬碟空間,點選我們剛剛加入的參考檔,也就是RevitAPI.dll與RevitAPIUI.dll。然後在屬性的視窗中把複製到本機的選項改成False(如下圖九所示)。這樣在建置API程式時,程式就會去找Revit本體中的參考檔,而不會產生一些額外的參考檔到API程式的資料夾中。

圖九、將參考檔複製到本機的選項改成False畫面

接下來就是寫程式的時間了,這次的程式非常的基礎。是大家的可以輕鬆完成的Hello World。不過,是用Revit API的環境來寫。所以,在程式碼中我們還需要加上一些設定。讓我們一步一步來:
1. 於最上面的參考中加入 using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
2. 在public class Class1前面加上[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)]
3. 把public class Class1加上: IExternalCommand
4. 在public class Class1: IExternalCommand{}裡面貼上
public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements) { }
5. 在Execute函式裡面貼上
TaskDialog.Show(“Test", “Hello World");
return Result.Succeeded;
這時你的程式碼應該會與下列程式碼一樣,這樣我們就完成了Hello World的程式碼了。

using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
namespace Hello_World
{
[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)]
    public class Class1 : IExternalCommand
    {
        public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
        {
            TaskDialog.Show("Test", "Hello World");
            return Result.Succeeded;
        }
    }
}

再來就是要來進行程式碼得測試啦。測試也是需要做一些設定的,我們再次一步一步來:
1. 於方案總管中的專案上點選右鍵(如下圖十所示),並選屬性(R)。

圖十、開啟專案屬性畫面

2. 於左側的頁籤中選擇偵錯,並於起始動作的區域點選啟動外部程式後按下瀏覽(如下圖十一所示)。

圖十一、設置專案啟動時外部程式畫面

3. 這此處我們要選擇Revit.exe,來當作啟動外部程式的目標。Revit.exe位置跟參考檔一樣,位置就在Revit安裝資料夾中。
這時雖然完成了測試的設定。但由於Visual Studio的設定,按下開始偵錯方案後,會無法進行偵錯。所以我們接著要更改Visual Studio的設定。
4. 按下Visual Studio上方選單的工具(T),並點選選項。這時會出現選項視窗。
5. 於選項視窗的右側列表中,點選偵錯,並於左側的選單中找到使用Managed相容性模式,把該選項勾選(如下圖十二所示),並按下確定。

圖十二、勾選使用Managed相容性模式畫面

這樣就可以成功的偵錯專案了。接下來讓我們來使用Add-in Manager執行我們的Hello World外掛吧。進入Revit專案後,點選增益集並點選外部工具的Add-In Manager(Manual Mode)。接著於Add-In Manager的視窗中點選Load的按鈕,並選擇我們編譯的Hello World專案的偵錯.dll檔,其路徑如下(~\ClassLibrary1\ClassLibrary1\bin\Debug\ClassLibrary1.dll)。並按下開啟。
這時Add-in Manager就會載入我們的Hello World專案,點選專案下的Class並按下Run(如下圖十三所示)。

圖十三、執行Revit外掛畫面

此時Add-in Manage就會執行我們的程式碼。在下圖十四中,可以看到Hello World的視窗,這樣我們的第一支Hello World測試就完成了。

圖十四、Hello World成功執行畫面

不過,如果我們的API程式只能透過Add-in Manager執行的話,那也太不像一支正常的程式了。所以讓我們來在Revit中部屬Hello World吧,首先先來製作Hello World的addin檔。一樣開啟Add-in Manager後,只勾選我們的Hello World的dll檔,接著按下右下Save鍵。按鍵就會出現下拉式選單,點選第二個Save checked items to Local .addin file(如下圖十五所示)。

圖十五、製作Hello World外掛之addin畫面

這時Add-in Manager就會幫我們把外掛程式的addin做出來了。做出來的addin會跟我們dll檔一樣的位置了。
在這邊有些朋友可能會想問Save checked items to Addins folder這個選項是什麼?小編在這邊說明一下,這個選項可以產生當前選擇的Revit API外掛的addin,並送進Revit的Addins資料夾中。不過實際上是送進哪一個版本的Revit Addins資料夾可能因人而異。大家如果想知道自己的電腦預設的儲存資料夾在哪,可以把滑鼠移至Save checked items to Addins folder選項上方。這時就可以看到選項上出現說明,在說明中即可知道實際上是送進哪一個版本的Revit Addins資料夾中了(如下圖十六所示)。

圖十六、Save checked items to Addins folder選項說明畫面

接下來的步驟就與本文一開始部署Add-in Manager的addin一樣,把 Hello World的addin用文字編輯器打開,將Assembly處的文字改為Hello World dll檔於本機電腦中的實體位置就可以儲存。接下來把addin檔放到C:\ProgramData\Autodesk\Revit\Addins\Revit\中對應版本的資料夾中,我們就完成了Hello World的.addin部屬了。

最後讓我們執行我們第一個Revit外掛程式吧。開啟Revit,一樣點選永遠載入外掛程式。進入專案後,到增益集的外部工具中。就可以看到我們的Hello World在那邊等我們了。以上就是我們的所有步驟,感謝大家的收看,我們下次再見!

延伸閱讀 | 【原創文章】BIM於跨平台整合應用的新篇章-以Forge技術運用於物料管理
延伸閱讀 | 【原創文章】引領 BIM 走向高擬真視覺呈現 (三)