這系列是衛武資訊研發部的公司內部訓練教材，無私公開教大家基礎的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前面加上
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的程式碼了。
再來就是要來進行程式碼得測試啦。測試也是需要做一些設定的，我們再次一步一步來：
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在那邊等我們了。以上就是我們的所有步驟，感謝大家的收看，我們下次再見!
Leave a Reply