Dynamo 的原始碼託管在 Github,可供任何人複製並提出貢獻。在本章中,我們將逐步瞭解如何使用 git 複製儲存庫、使用 Visual Studio 編譯原始碼檔案、執行本端建置版本並除錯,以及從 Github 提取任何新變更。
Github 是一種以 git 為基礎的託管服務,是一種可追蹤變更並協調不同使用者工作的版本控制系統。Git 是一種工具,我們可以利用它來下載 Dynamo 的原始碼檔案,並透過一些指令保持更新。使用此方法可避免每次更新時都要手動下載和取代原始碼檔案這些不必要且繁雜的工作。Git 版本控制系統會追蹤本端和遠端程式碼儲存庫之間的任何差異。
Dynamo 的原始碼託管在 DynamoDS Github 上的 https://github.com/DynamoDS/Dynamo 儲存庫
Dynamo 原始碼檔案。
複製或下載整個儲存庫
檢視其他 DynamoDS 儲存庫
Dynamo 的原始碼檔案
Git 特有的檔案
在複製儲存庫之前,必須先安裝 git。請遵循此簡短指南以瞭解安裝步驟,以及如何設定 Gihub 使用者名稱和電子郵件。在此範例中,我們將在指令行使用 git。本指南假設您使用 Windows,但您也可以在 mac 或 Linux 上使用 git 複製 Dynamo 原始碼。
我們需要 Dynamo 儲存庫的 URL 才能從中複製。您可以在儲存庫頁面的「Clone or download (複製或下載)」按鈕中找到。複製要貼至指令提示的 URL。
選取「Clone or download」
複製 URL
安裝 git 後,我們可以複製 Dynamo 儲存庫。先開啟指令提示。然後,使用變更目錄指令 cd
瀏覽到要將原始碼檔案複製到的資料夾。在此範例中,我們在 Documents
中建立了一個名為 Github
的資料夾。
cd C:\Users\username\Documents\GitHub
將「username」取代為您的使用者名稱
下一步,我們要執行 git 指令,將 Dynamo 儲存庫複製到我們指定的位置。在 Github 上按一下「Clone or Download」按鈕,取得指令中的 URL。在指令終端機中執行此指令。請注意,這會複製 Dynamo 儲存庫主分支,主分支是 Dynamo 最新的程式碼,包含最新版本的 Dynamo 程式碼。此分支每天都會變更。
git clone https://github.com/DynamoDS/Dynamo.git
如果複製作業成功完成,我們就知道 git 正在運作。在檔案總管中,瀏覽到您複製的目錄以查看原始碼檔案。目錄結構應該與 Github 上 Dynamo 儲存庫的主分支相同。
Dynamo 的原始碼檔案
Git 檔案
將原始碼檔案複製到本端電腦後,我們可以建置 Dynamo 的可執行檔。要執行此作業,我們需要設定 Visual Studio IDE,並確保已安裝 .NET Framework 和 DirectX。
下載並安裝 Microsoft Visual Studio Community 2015,這是一款免費且功能齊全的 IDE (整合式開發環境 - 更高版本也同樣能運作)
下載並安裝 Microsoft .NET Framework 4.5 或更高版本
從本端 Dynamo 儲存庫安裝 Microsoft DirectX (Dynamo\tools\install\Extra\DirectX\DXSETUP.exe
)
.NET 和 DirectX 可能已經安裝。
所有檔案安裝完成後,我們可以啟動 Visual Studio,並開啟位於 Dynamo\src
的 Dynamo.All.sln
方案。
選取「
File > Open > Project/Solution
」瀏覽至 Dynamo 儲存庫並開啟
src
資料夾選取
Dynamo.All.sln
方案檔選取「
Open
」
在建置方案之前,必須先指定一些設定。我們要先建置 Dynamo 的除錯版本,讓 Visual Studio 在除錯時可以收集更多資訊協助我們開發,而且我們要以 AnyCPU 作為目標。
這些設定會變成
bin
資料夾內的資料夾
在此範例中,我們選擇「
Debug
」做為「Solution Configuration (方案組態)」將「Solution Platform (方案平台)」設定為「
Any CPU
」
開啟專案後,我們可以建置方案。此處理序將會建立一個可以執行的 DynamoSandbox.exe 檔案。
建置專案會還原 NuGet 相依性。
選取「
Build > Build Solution
」在「Output (輸出)」視窗中確認建置成功,看起來應該類似
==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====
如果 Dynamo 建置成功,Dynamo 儲存庫中會建立一個包含 DynamoSandbox.exe 檔案的 bin
資料夾。在我們的範例中,我們使用「Debug (除錯)」選項建置,因此可執行檔位於 bin\AnyCPU\Debug
。執行此檔案將開啟 Dynamo 的本端建置版本。
我們剛剛建置的 DynamoSandbox 可執行檔。執行此檔案以啟動 Dynamo。
我們現在已經幾乎設定好,可以開始開發 Dynamo。
如需有關為其他平台 (例如 Linux 或 OS X) 建置 Dynamo 的指示,請造訪此 Wiki 頁面。
除錯是識別、隔離和修正錯誤或問題的一個過程。從原始碼成功建置 Dynamo 後,我們可以使用 Visual Studio 中的數種工具為執行中的應用程式 (例如 DynamoRevit 增益集) 除錯。我們可以分析其原始程式碼以尋找問題的根本原因,或監看目前正在執行的程式碼。如需有關如何在 Visual Studio 中除錯和瀏覽程式碼的更詳細說明,請參閱 Visual Studio 文件。
對於單機版 Dynamo 應用程式 DynamoSandbox,我們將介紹兩個用於除錯的選項:
直接從 Visual Studio 建置並啟動 Dynamo
將 Visual Studio 附加到 Dynamo 正在執行的處理序
從 Visual Studio 啟動 Dynamo 時,如果需要,會為每個除錯階段作業重新建置方案,因此如果我們對原始碼做了變更,除錯時會納入這些變更。在 Dynamo.All.sln
方案仍開啟的情況下,從下拉功能表中選取「Debug
」、「AnyCPU
」和「DynamoSandbox
」,然後按一下「Start
」。這會建置 Dynamo 並啟動一個新的處理序 (DynamoSandbox.exe),並將 Visual Studio 的除錯程式附加到該處理序。
直接從 Visual Studio 建置並啟動應用程式
將組態設定為「
Debug
」將平台設定為「
Any CPU
」將啟動專案設定為「
DynamoSandbox
」按一下「
Start
」以開始為處理序除錯
或者,我們可能想要為已在執行的 Dynamo 處理序除錯,以疑難排解特定圖表開啟或套件的問題。基於這個原因,我們會在 Visual Studio 中開啟專案的原始碼檔案,並使用「Attach to Process
」除錯功能表項目附加到執行中的 Dynamo 處理序。
將正在執行的處理序附加到 Visual Studio
選取「
Debug > Attach to Process...
」選擇「
DynamoSandbox.exe
」選取「
Attach
」
在這兩種情況下,我們都會將除錯程式附加到要除錯的處理序。我們可以在啟動除錯程式之前或之後設定程式碼中的中斷點,這會導致處理序在執行該行程式碼之前立即暫停。如果在除錯時擲回未攔截的例外狀況,Visual Studio 會跳到原始程式碼中發生該例外狀況的位置。這是一種尋找簡單當機、未處理例外狀況,以及瞭解應用程式執行流的有效方法。
為 DynamoSandbox 除錯時,我們在 Color.ByARGB 節點的建構函式中設定一個中斷點,這會導致 Dynamo 處理序在節點具現化時暫停。如果此節點擲出例外狀況或導致 Dynamo 當機,我們可以逐步執行建構函式中的每一行,以尋找發生問題的位置。
中斷點
顯示目前正在執行之函式和先前函式呼叫的呼叫堆疊。
在下一節〈從原始碼建置 DynamoRevit〉中,我們將逐步介紹除錯的特定範例,並說明如何設定中斷點、逐步執行程式碼,以及解讀呼叫堆疊。
由於 Dynamo 原始碼託管在 Github 上,因此讓本端原始碼檔案保持更新最簡單的方式是使用 git 指令提取變更。
使用指令行,將目前目錄設定為 Dynamo 儲存庫:
cd C:\Users\username\Documents\GitHub\Dynamo
將
"username"
取代為您的使用者名稱
使用下列指令提取最新變更:
git pull origin master
在此,我們可以看到本端儲存庫已經以遠端的變更更新。
除了提取更新,還有四個 git 工作流程需要熟悉。
Fork (分岔) Dynamo 儲存庫,建立一份與原始儲存庫分開的複本。此處所做的任何變更都不會影響原始儲存庫,也可以從中擷取更新或利用提取請求來提交更新。Fork 不是 git 指令,而是 github 新增的一個工作流程 - 分岔-提取請求模型是參與線上開放原始碼專案其中一個最常見的工作流程。如果您想要為 Dynamo 做出貢獻,請學習這項功能。
Branch (分支) - 在分支內容中獨立於其他工作進行實驗或新功能。這可讓您更輕鬆地傳送提取請求。
在完成一部分工作之後,以及做了可能想要退回的變更之後,請經常進行 commit (認可)。認可動作會記錄對儲存庫的變更,在對主要 Dynamo 儲存庫提出提取請求時,也會看到該筆認可內容。
當準備好正式將變更提出到主要 Dynamo 儲存庫時,請建立 pull request (提取請求)。
Dynamo 團隊對於建立提取請求有特定指示。請參閱本文件中的〈提取請求〉一節,以瞭解要處理的更多詳細項目。
請參閱此文件頁面,以取得 git 指令的參考清單。
DynamoRevit 原始碼檔案也託管在 DynamoDS Github 上,開發人員可以參與並建置 Beta 版本。從原始碼建置 DynamoRevit 的程序通常與 Dynamo 相同,但有一些重要的細節例外:
DynamoRevit 參考 Dynamo 組合,因此應使用相符的 NuGet 套件建置這些組合。例如,DynamoRevit 2.x 不會載入至 Dynamo 1.3。
DynamoRevit 與 Revit 版本有關,例如:DynamoRevit 2018 分支應在 Revit 2018 上執行。
本指南將使用下列項目:
Revit 2023
在分支 Revit2023
上的最新 DynamoRevit 建置版本
最新的 Dynamo 建置版本
為確保能成功建置,我們將複製並建置 Dynamo 和 DynamoRevit 兩個儲存庫在此逐步解說中使用。
注意事項:只有當您建置 Dynamo 1.x 和 DynamoRevit 1.x 時,才需要在 DynamoRevit 之前手動建置 Dynamo - 較新版本的 DynamoRevit 儲存庫依賴 NuGet 套件管理員,才能獲得建置所需的 Dynamo 相依性。雖然 DynamoRevit 2.x 的建置版本不需要手動提取 Dynamo,但您在其他位置仍然需要核心 dlls
才能真正執行 DynamoRevit addin
- 因此無論如何還是要提取和建置 Dynamo。參閱更多資訊:使用 Visual Studio 建置儲存庫
DynamoRevit 專案的程式碼與核心 Dynamo 原始程式碼在 Github 是位在不同的儲存庫中。此儲存庫包含 Revit 特定節點的原始碼檔案,以及載入 Dynamo 的 Revit 增益集。適用於不同 Revit 版本 (例如 2016、2017 或 2018) 的 DynamoRevit 建置版本在儲存庫中會整理成不同的分支。
DynamoRevit 的原始碼託管在此:https://github.com/DynamoDS/DynamoRevit
複製或下載儲存庫
DynamoRevit 的分支參考 Revit 版本
在與提取 Dynamo 儲存庫類似的過程中,我們將使用 git clone 指令來複製 DynamoRevit,並指定與 Revit 版本相符的分支。首先,我們開啟指令行介面,將目前目錄設定為要將檔案複製到的位置。
cd C:\Users\username\Documents\GitHub
會變更目前目錄
將
username
取代為您的使用者名稱
現在,我們可以將儲存庫複製到此目錄中。雖然我們需要指定儲存庫的分支,但可以在複製後切換到此分支。
git clone https://github.com/DynamoDS/DynamoRevit.git
會從遠端 URL 複製儲存庫,然後依預設切換到主分支。
儲存庫完成複製後,將目前目錄變更為儲存庫資料夾,並切換至與所安裝 Revit 版本相符的分支。在此範例中,我們使用 Revit RC2.13.1_Revit2023。在 Github 頁面上的「Branch」下拉式功能表中可以檢視所有遠端分支。
cd C:\Users\username\Documents\GitHub\DynamoRevit
會將目錄變更為 DynamoRevit。
git checkout RC2.13.1_Revit2023
會將目前分支設定為 RC2.13.1_Revit2023
。
git branch
會確認我們所在的分支,並顯示本端存在的其他分支。
有星號的分支是目前出庫使用的分支。畫面顯示的是
Revit2018
分支,因為我們先前已將其出庫使用,因此它位於本端。
選擇正確的儲存庫分支很重要,這樣才能確保專案在 Visual Studio 中建置時,會參考 Revit 安裝目錄正確版本 (尤其是 RevitAPI.dll
和 RevitAPIUI.dll
) 中的組合。
在建置儲存庫之前,我們需要使用 src
資料夾中的 restorepackages.bat
檔案還原 NuGet 套件。此 bat 檔案使用 nuget 套件管理員提取 DynamoRevit 所需的 Dynamo 核心已建置二進位檔案。您也可以選擇手動建置這些元件,但如果您只是對 DynamoRevit (而不是 Dynamo 核心) 進行變更,這樣可以更快開始。請務必以管理員身分執行此檔案。
以右鍵按一下
restorepackages.bat
,然後選取「Run as administrator
」
如果成功還原套件,則會在 src
資料夾中新增一個 packages
資料夾,當中包含最新的 Beta 版 NuGet 套件。
最新的 Beta 版 Dynamo NuGet 套件
還原套件後,開啟 src
中的 DynamoRevit.All.sln
Visual Studio 方案檔,然後建置方案。建置作業一開始可能找不到 AssemblySharedInfo.cs
。如果是,重新執行建置可以解決此問題。
選取「
Build > Build Solution
」在「Output (輸出)」視窗中確認建置成功。訊息應為
===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====
。
Revit 需要增益集檔案才能辨識 DynamoRevit,安裝程式會自動建立此檔案。在開發過程中,我們需要手動建立一個指向我們要使用的 DynamoRevit 建置版本的增益集檔案,明確來說是 DynamoRevitDS.dll
組合。我們還需要將 DynamoRevit 指向 Dynamo 的建置版本。
在 Revit 的增益集資料夾 C:\ProgramData\Autodesk\Revit\Addins\2023
中建立 Dynamo.addin
檔案。我們已經安裝 DynamoRevit 版本,因此我們只要編輯既有檔案以指向新的建置版本。
在 <Assembly>...</Assembly>
內指定 DynamoRevitDS.dll
的檔案路徑。
或者,我們可以使用增益集載入版本選取器,而非特定組合。
將 <Assembly>...</Assembly>
檔案路徑設定為 DynamoRevitVersionSelector.dll
<FullClassName>...</FullClassName>
使用上面的組合元素路徑,指定要從我們所指向的組合實體化的類別。此類別將是我們增益集的進入點。
此外,我們需要移除 Revit 隨附的既有 Dynamo。若要執行,請移至 C:\\Program Files\Autodesk\Revit 2023\AddIns
並移除包含 Dynamo 的兩個資料夾 - DynamoForRevit
和 DynamoPlayerForRevit
。如果需要恢復原始的 Dynamo for Revit,您可以刪除這兩個資料夾,或備份到單獨的資料夾中。
第二步是在 DynamoRevit 的 bin
資料夾中的 Dynamo.config
檔案新增 Dynamo 核心組合的檔案路徑。在 Revit 中開啟增益集時,DynamoRevit 將載入這些組合。此規劃檔可讓您將 DynamoRevit 增益集指向不同版本的 Dynamo 核心,供您同時在核心和 DynamoRevit 中開發和測試變更。
程式碼應如下所示:
將 bin
資料夾的目錄路徑加到 <add key/>
中
我們在此逐步解說之前才複製並建置 Dynamo,確保能與 DynamoRevit 順利搭配運作。目錄路徑指向此建置版本。
現在開啟 Revit 時,「管理」頁籤中應該有 Dynamo 增益集。
選取「
Manage
」按一下 Dynamo 增益集圖示
一個 DynamoRevit 例證
如果出現錯誤對話方塊視窗顯示缺少組合,可能是您建置所依據的 DynamoCore 版本與您在執行時期載入的 DynamoCore 版本不相符。例如,如果您嘗試使用 Dynamo 1.3 dll 啟動 DynamoCore,則 DynamoRevit 搭配最新的 DynamoCore 2.0 Beta 套件將無法運作。請確保兩個儲存庫的版本相同,且 DynamoRevit 提取的是相符版本的 nuget 相依性。這些版本定義在 DynamoRevit 儲存庫的 package.json
檔案中。
在上一節〈從原始碼建置 Dynamo〉中,我們簡單介紹了在 Visual Studio 中進行除錯,以及如何將 Visual Studio 附加到處理序。以 Wall.ByCurveAndHeight 節點中的例外狀況為例,我們將逐步瞭解如何附加到處理序、設定中斷點、逐步執行程式碼,以及使用呼叫堆疊來判斷例外狀況的來源。這些除錯工具通常適用於 .net 開發工作流程,值得您在參考本指南之餘進行探索。
附加至處理序可將執行中的應用程式連結至 Visual Studio 進行除錯。如果我們要為 DynamoRevit 建置版本中發生的行為進行除錯,可以在 Visual Studio 中開啟 DynamoRevit 原始碼檔案,然後附加 Revit.exe
處理序,這是 DynamoRevit 增益集的父處理序。Visual Studio 使用符號檔 (.pbd
) 來連接 DynamoRevit 正在執行的組合與原始程式碼。
中斷點會在原始程式碼中建立幾行程式碼,應用程式會在這幾行暫停後再執行。如果某個節點導致 DynamoRevit 當機或傳回非預期結果,我們可以在節點的原始碼中加入中斷點暫停處理序、逐步檢查程式碼,以及檢查變數的即時值,直到找到問題的根本原因
逐行執行程式碼會逐行執行原始碼。我們可以逐一執行函數、逐步檢查函數呼叫,或跳出目前執行的函數。
呼叫堆疊會顯示處理序目前正在執行且與叫用此函數呼叫的前一個函數呼叫相關的函數。Visual Studio 有一個「呼叫堆疊」視窗可顯示此內容。例如,如果在原始程式碼外遇到例外狀況,可以查看呼叫堆疊中呼叫程式碼的路徑。
您應該瞭解 C# 的 2,000 件事對呼叫堆疊有更深入的說明
Wall.ByCurveAndHeight 節點在給定一條 PolyCurve 做為其曲線輸入時擲出例外狀況並顯示以下訊息:「未實施目標 BSPlineCurve」。透過除錯,我們可以找出節點為什麼不接受此幾何圖形類型做為曲線參數的輸入。在此範例中,我們假設 DynamoRevit 已成功建置,並可做為 Revit 的增益集執行。
Wall.ByCurveAndHeight 節點擲出例外狀況
首先開啟 DynamoRevit.All.sln
方案檔,啟動 Revit,然後啟動 DynamoRevit 增益集。然後使用「Attach to Process
」視窗將 Visual Studio 附加到 Revit 處理序。
Revit 和 DynamoRevit 必須執行才能顯示為可用處理序
選取「
Debug > Attach to Process...
」以開啟「Attach to Process
」視窗將「
Transport
」設定為「Default
」選取
Revit.exe
選取「
Attach
」
將 Visual Studio 附加到 Revit 後,開啟 Wall.cs
中的 Wall.ByCurveAndHeight 原始程式碼。我們可以在「方案總管」的「Libraries > RevitNodes > Elements
」下,在檔案的 Public static constructors
區域找到這段程式碼。在牆類型的建構函式中設定中斷點,以便在 Dynamo 中執行節點時,處理序會中斷,我們可以逐行執行程式碼。Dynamo zero touch 類型的建構函式通常以 By<parameters>
開頭。
具有 Wall.ByCurveAndHeight 建構函式的類別檔案
按一下行號的左側,或在程式碼行上按一下右鍵並選取「
Breakpoint > Insert Breakpoint
」可設定中斷點。
設定中斷點後,我們需要處理序逐步執行 Wall.ByCurveAndHeight 函數。在 Dynamo 中將配線重新連接至其中一個埠 (這會強制節點重新執行),可再次執行此函數。在 Visual Studio 中會叫用中斷點。
中斷點圖示在叫用時會變更
「呼叫堆疊」視窗顯示下一個即將執行的方法
現在,請逐步檢查建構函式中的每一行,直到遇到例外狀況。以黃色亮顯的程式碼是下一個要執行的陳述式。
用於瀏覽程式碼的除錯工具
按「
Step Over
」以執行亮顯的程式碼,然後在函數傳回後暫停執行要執行的下一個陳述式,以黃色亮顯和箭頭指示
如果我們繼續逐步執行函數,將會遇到 DynamoRevit 視窗中顯示的例外狀況。查看「呼叫堆疊」視窗,我們可以看到例外狀況一開始是從名為 Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve
的方法所擲出。多虧這裡已經處理了例外狀況,因此 Dynamo 沒有當機。除錯程序將我們引導到原始式碼中的另一個方法,提供發生問題的脈絡。
由於這不是開放原始碼資源庫,因此我們無法在該處進行變更 - 現在,我們擁有更多資訊,可以透過提交 Github 問題回報問題更多內容,或者我們可以針對此問題提出提取請求以提供解決方法。
當我們叫用導致
Walls.cs
中發生例外狀況的陳述式時,除錯程序會盡可能將我們引導到使用者程式碼中ProtoToRevitCurve.cs
內發生問題的根本所在位置導致
ProtoToRevitCurve.cs
中例外狀況的陳述式在「呼叫堆疊」中,我們可以看到例外狀況是來自非使用者程式碼
提供例外狀況相關資訊的快顯視窗
此程序可套用至我們處理的任何原始碼檔案。如果我們要開發 Dynamo Studio 的 Zero-Touch 節點資源庫,可以開啟資源庫的原始碼並附加 Dynamo 處理序,為節點資源庫除錯。即使一切正常,除錯也是探索程式碼並瞭解其運作方式的絕佳方式。
此程序幾乎與提取 Dynamo 的變更相同,但是需要確保位於正確的分支。在 DynamoRevit 儲存庫中使用 git branch
指令,查看哪些分支可在本端使用,哪些分支目前已出庫使用。
cd C:\Users\username\Documents\GitHub\DynamoRevit
將目前目錄設定為 DynamoRevit 儲存庫。
git branch
確認我們位於正確的分支RC2.13.1_Revit2023
。
git pull origin RC2.13.1_Revit2023
會從遠端的原點 RC2.13.1_Revit2023
分支提取變更。
原點只是指向我們複製的原始 URL。
我們希望在此注意目前所在的分支,以及我們要從哪個分支提取,以避免將變更從
RC2.13.1_Revit2023
提取到例如Revit2018
。
如〈從原始碼建置 Dynamo〉中所述,當我們準備好將變更提交到 DynamoRevit 儲存庫時,可以按照 Dynamo 團隊在〈提取請求〉一節所列的指導方針建立提取請求。