無論經驗程度為何，Dynamo 平台專為所有使用者成為貢獻者而設計。針對不同的能力和技能程度有幾種開發選項，每種能力和技能程度的優缺點視目標而定。下面我們將概述不同的選項，以及如何選擇。

三種開發環境：Visual Studio、Python 編輯器和 Code Block DesignScript

我有哪些選擇？

Dynamo 的開發選項主要分為兩個類別：為 Dynamo，以及 在 Dynamo。這兩個類別可視為：「在」Dynamo 表示使用 Dynamo IDE 建立要在 Dynamo 中使用的內容；「為」Dynamo 表示使用外部工具建立要匯入 Dynamo 中進行使用的內容。雖然本指南著重在 為 Dynamo 的開發，但下面會描述所有程序的資源。

為 Dynamo

這些節點允許最高程度的自訂。許多套件都使用此方法建置，因此要對 Dynamo 的原始碼做出貢獻也需要此方法。本指南將涵蓋建置這些節點的程序。

• Zero-Touch 節點

• NodeModel 衍生的節點

• 延伸

Primer 在匯入 Zero-Touch 資源庫提供了指南。

下面的討論使用 Visual Studio 當作 Zero-Touch 和 NodeModel 節點的開發環境。

Visual Studio 介面，以及我們將開發的專案

在 Dynamo

雖然這些程序都在視覺程式設計工作區中，相對而言也簡單易懂，但它們都是自訂 Dynamo 的可行選項。Primer 廣泛涵蓋這些內容，並在指令碼撰寫策略一章中提供撰寫指令碼的秘訣和最佳實踐。

• 「程式碼區塊」可在視覺程式設計環境中顯示 DesignScript，提供靈活的文字腳本和節點工作流程。程式碼區塊中的函數可被工作區中的任何內容呼叫。

  下載程式碼區塊範例 (按一下右鍵後另存)，或在 Primer 中查看詳細的逐步解說。

• 「自訂節點」是節點集合 (甚至整個圖表) 的容器。是收集常用常式並與社群分享的有效方式。

  下載自訂節點範例 (按一下右鍵後另存)，或在 Primer 中查看詳細的逐步解說。

• 「Python 節點」是視覺程式設計工作區中的腳本撰寫介面，與程式碼區塊類似。Autodesk.DesignScript 資源庫使用與 DesignScript 類似的點標記法。

  下載 Python 節點範例 (按一下右鍵後另存)，或在 Primer 中查看詳細的逐步解說。

在 Dynamo 工作區中開發是一個能立即得到回饋的強大工具。

在 Dynamo 工作區中使用 Python 節點開發

每種方法有哪些優點/缺點？

Dynamo 的開發選項已設計為可解決自訂需求的複雜性。無論目標是以 Python 撰寫遞迴指令碼，還是建置一個完全自訂的節點使用者介面，都有一些選項可實作只包含啟動和執行所需的程式碼。

Dynamo 中的程式碼區塊、Python 節點和自訂節點

這些是在 Dynamo 視覺程式設計環境中撰寫程式碼的簡單選項。Dynamo 視覺程式設計工作區可讓您存取 Python、DesignScript，並且能在自訂節點內包含多個節點。

使用這些方法，我們可以：

• 開始撰寫 Python 或 DesignScript，幾乎不用進行設定。

• 將 Python 資源庫匯入 Dynamo。

• 將程式碼區塊、Python 節點和自訂節點做為套件的一部分與 Dynamo 社群分享。

Zero-Touch 節點

「Zero-Touch」是指匯入 C# 資源庫所使用的一個簡易點選方法。Dynamo 將讀取 .dll 檔案的公開方法，並將其轉換為 Dynamo 節點。您可以使用 Zero-Touch 開發自己的自訂節點與套件

使用此方法，我們可以：

• 匯入不一定是針對 Dynamo 開發的資源庫，並自動建立一組新節點，例如 Primer 中的 A-Forge 範例

• 撰寫 C# 方法，並輕鬆使用這些方法做為 Dynamo 中的節點

• 將 C# 資源庫以節點方式透過套件與 Dynamo 社群分享

NodeModel 衍生的節點

這些節點更深入 Dynamo 結構。它們以 NodeModel 類別為基礎，並以 C# 撰寫。雖然此方法提供最大的靈活性和功能，但節點的絕大多數層面必須明確定義，且函數必須位於單獨的組合中。

使用此方法，我們可以：

• 使用滑棒、影像、顏色等建立完全可自訂的節點使用者介面 (例如 ColorRange 節點)

• 存取並影響 Dynamo 圖元區中發生的結果

• 自訂交織

• 載入 Dynamo 中成為套件

瞭解 Dynamo 版本管理和 API 變更 (1.x → 2.x)

由於 Dynamo 會定期更新，因此可能會變更套件所使用的 API 部分。追蹤這些變更非常重要，以確保既有套件能持續正常運作。

Dynamo Github Wiki 會追蹤 API 變更。這包括對 DynamoCore、資源庫和工作區的變更。

一個即將實施的重大變更範例是，在 2.0 版中從 XML 檔案格式轉換為 JSON 檔案格式。NodeModel 衍生的節點現在需要 JSON 建構函式，否則無法在 Dynamo 2.0 中開啟。

Dynamo 的 API 文件目前涵蓋核心功能：http://dynamods.github.io/DynamoAPI

以套件散發二進位檔案的權限

請注意要上傳到 Package Manager 的套件中是否包含 .dll。如果套件作者未建立 .dll，他們必須具有分享該 .dll 的權限。

如果套件包含二進位檔案，則必須在使用者下載包含二進位檔案的套件時加以提示。

在 Zero-Touch 節點中執行 Python 指令碼 (C#)

如果您能輕鬆地以 Python 撰寫指令碼，也想要從標準 Dynamo Python 節點獲得更多功能，我們可以使用 Zero-Touch 建立自己的指令碼。我們先從一個簡單的範例開始，我們將一個 Python 指令碼做為字串傳入執行指令碼並傳回結果的 Zero-Touch 節點。此案例研究以「入門」區段中的逐步解說和範例為基礎，如果您是初次建立 Zero-Touch 節點，請參閱這些內容。

將執行 Python 指令碼字串的 Zero-Touch 節點

Python 引擎

此節點依賴一個 IronPython 指令碼引擎例證。若要執行，我們需要參考一些其他組合。請遵循以下步驟，在 Visual Studio 中設定基本樣板：

• 建立新的 Visual Studio 類別專案

• 在位於 C:\Program Files (x86)\IronPython 2.7\IronPython.dll 的 IronPython.dll 中加入參考

• 在位於 C:\Program Files (x86)\IronPython 2.7\Platforms\Net40\Microsoft.Scripting.dll 的 Microsoft.Scripting.dll 中加入參考

• 在您的類別中包括 IronPython.Hosting 和Microsoft.Scripting.Hosting 兩個 using 陳述式

• 加入一個空的私用建構函式，以防止額外的節點隨著我們的套件被加到 Dynamo 資源庫

• 建立一個採用單一字串做為輸入參數的新方法

• 在此方法中，我們將實體化新的 Python 引擎，並建立空的指令碼範圍。您可以將此範圍想像為 Python 解譯器例證內的全域變數

• 接下來，在引擎呼叫 Execute，並傳入輸入字串和範圍做為參數

• 最後，在範圍呼叫 GetVariable，並從包含您嘗試傳回之值的 Python 指令碼傳入變數名稱，來擷取並傳回指令碼的結果。(請參閱以下範例，以取得進一步的詳細資料)

以下程式碼提供上述步驟的範例。建置方案會在專案的 bin 資料夾中建立一個新的 .dll。現在，此 .dll 可匯入至 Dynamo 做為套件的一部分，或瀏覽至「File < Import Library...」

using IronPython.Hosting;
using Microsoft.Scripting.Hosting;

namespace PythonLibrary
{
    public class PythonZT
    {
        // Unless a constructor is provided, Dynamo will automatically create one and add it to the library
        // To avoid this, create a private constructor
        private PythonZT() { }

        // The method that executes the Python string
        public static string executePyString(string pyString)
        {
            ScriptEngine engine = Python.CreateEngine();
            ScriptScope scope = engine.CreateScope();
            engine.Execute(pyString, scope);
            // Return the value of the 'output' variable from the Python script below
            var output = scope.GetVariable("output");
            return (output);
        }
    }
}

Python 指令碼傳回變數 output，這表示我們在 Python 指令碼中需要一個 output 變數。請使用此範例指令碼測試 Dynamo 中的節點。如果您曾在 Dynamo 中使用過 Python 節點，以下內容應該看起來很熟悉。如需更多資訊，請參閱 Primer 的 Python 部分。

import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

cube = Cuboid.ByLengths(10,10,10);
volume = cube.Volume
output = str(volume)

多個輸出

標準 Python 節點的一個限制是它們只有單一輸出埠，因此，如果我們希望傳回多個物件，則必須建構清單並擷取其中的每個物件。如果我們修改上述範例以傳回字典，就可以加入任意數目的輸出埠。請參閱〈深入瞭解 Zero-Touch〉中的〈傳回多個值〉一節，以取得有關字典的更多詳細資料。

此節點可讓我們傳回立方體的體積及其形心。

接下來使用以下步驟修改先前的範例：

• 從 NuGet 套件管理員加入 DynamoServices.dll 的參考

• 除了先前的組合，還包括 System.Collections.Generic 和 Autodesk.DesignScript.Runtime

• 修改方法的傳回類型，以傳回包含輸出的字典

• 每個輸出都必須從範圍中單獨擷取 (請考慮為較大的輸出集設定簡單迴路)

using IronPython.Hosting;
using Microsoft.Scripting.Hosting;
using System.Collections.Generic;
using Autodesk.DesignScript.Runtime;

namespace PythonLibrary
{
    public class PythonZT
    {
        private PythonZT() { }

        [MultiReturn(new[] { "output1", "output2" })]
        public static Dictionary<string, object> executePyString(string pyString)
        {
            ScriptEngine engine = Python.CreateEngine();
            ScriptScope scope = engine.CreateScope();
            engine.Execute(pyString, scope);
            // Return the value of 'output1' from script
            var output1 = scope.GetVariable("output1");
            // Return the value of 'output2' from script
            var output2 = scope.GetVariable("output2");
            // Define the names of outputs and the objects to return
            return new Dictionary<string, object> {
                { "output1", (output1) },
                { "output2", (output2) }
            };
        }
    }
}

我們也在範例 Python 指令碼中加入其他輸出變數 (output2)。請記住，這些變數可以使用任何合法的 Python 命名慣例，在此範例中是為了清楚起見，所以只使用 output。

import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

cube = Cuboid.ByLengths(10,10,10);
centroid = Cuboid.Centroid(cube);
volume = cube.Volume
output1 = str(volume)
output2 = str(centroid)

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 建置儲存庫

在 Github 上找出 DynamoRevit 儲存庫

DynamoRevit 專案的程式碼與核心 Dynamo 原始程式碼在 Github 是位在不同的儲存庫中。此儲存庫包含 Revit 特定節點的原始碼檔案，以及載入 Dynamo 的 Revit 增益集。適用於不同 Revit 版本 (例如 2016、2017 或 2018) 的 DynamoRevit 建置版本在儲存庫中會整理成不同的分支。

DynamoRevit 的原始碼託管在此：https://github.com/DynamoDS/DynamoRevit

1. 複製或下載儲存庫

2. DynamoRevit 的分支參考 Revit 版本

使用 git 複製儲存庫

在與提取 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) 中的組合。

使用 Visual Studio 建置儲存庫

在建置儲存庫之前，我們需要使用 src 資料夾中的 restorepackages.bat 檔案還原 NuGet 套件。此 bat 檔案使用 nuget 套件管理員提取 DynamoRevit 所需的 Dynamo 核心已建置二進位檔案。您也可以選擇手動建置這些元件，但如果您只是對 DynamoRevit (而不是 Dynamo 核心) 進行變更，這樣可以更快開始。請務必以管理員身分執行此檔案。

1. 以右鍵按一下 restorepackages.bat，然後選取「Run as administrator」

如果成功還原套件，則會在 src 資料夾中新增一個 packages 資料夾，當中包含最新的 Beta 版 NuGet 套件。

1. 最新的 Beta 版 Dynamo NuGet 套件

還原套件後，開啟 src 中的 DynamoRevit.All.sln Visual Studio 方案檔，然後建置方案。建置作業一開始可能找不到 AssemblySharedInfo.cs。如果是，重新執行建置可以解決此問題。

1. 選取「Build > Build Solution」

2. 在「Output (輸出)」視窗中確認建置成功。訊息應為 ===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====。

在 Revit 中執行 DynamoRevit 的本端建置版本

Revit 需要增益集檔案才能辨識 DynamoRevit，安裝程式會自動建立此檔案。在開發過程中，我們需要手動建立一個指向我們要使用的 DynamoRevit 建置版本的增益集檔案，明確來說是 DynamoRevitDS.dll 組合。我們還需要將 DynamoRevit 指向 Dynamo 的建置版本。

在 Revit 的增益集資料夾 C:\ProgramData\Autodesk\Revit\Addins\2023 中建立 Dynamo.addin 檔案。我們已經安裝 DynamoRevit 版本，因此我們只要編輯既有檔案以指向新的建置版本。

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>Dynamo For Revit</Name>
<Assembly>"C:\Users\username\Documents\GitHub\DynamoRevit\bin\AnyCPU\Debug\Revit\DynamoRevitDS.dll"</Assembly>
<AddInId>8D83C886-B739-4ACD-A9DB-1BC78F315B2B</AddInId>
<FullClassName>Dynamo.Applications.DynamoRevitApp</FullClassName>
<VendorId>ADSK</VendorId>
<VendorDescription>Dynamo</VendorDescription>
</AddIn>
</RevitAddIns>

• 在 <Assembly>...</Assembly> 內指定 DynamoRevitDS.dll 的檔案路徑。

或者，我們可以使用增益集載入版本選取器，而非特定組合。

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>Dynamo For Revit</Name>
<Assembly>"C:\Users\username\Documents\GitHub\DynamoRevit\bin\AnyCPU\Debug\Revit\DynamoRevitVersionSelector.dll"</Assembly>
<AddInId>8D83C886-B739-4ACD-A9DB-1BC78F315B2B</AddInId>
<FullClassName>Dynamo.Applications.VersionLoader</FullClassName>
<VendorId>ADSK</VendorId>
<VendorDescription>Dynamo</VendorDescription>
</AddIn>
</RevitAddIns>

• 將 <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 中開發和測試變更。

程式碼應如下所示：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
     <add key="DynamoRuntime" value="C:\Users\username\Documents\GitHub\Dynamo\bin\AnyCPU\Debug"/>
  </appSettings>
</configuration>

• 將 bin 資料夾的目錄路徑加到 <add key/> 中

我們在此逐步解說之前才複製並建置 Dynamo，確保能與 DynamoRevit 順利搭配運作。目錄路徑指向此建置版本。

現在開啟 Revit 時，「管理」頁籤中應該有 Dynamo 增益集。

1. 選取「Manage」

2. 按一下 Dynamo 增益集圖示

3. 一個 DynamoRevit 例證

如果出現錯誤對話方塊視窗顯示缺少組合，可能是您建置所依據的 DynamoCore 版本與您在執行時期載入的 DynamoCore 版本不相符。例如，如果您嘗試使用 Dynamo 1.3 dll 啟動 DynamoCore，則 DynamoRevit 搭配最新的 DynamoCore 2.0 Beta 套件將無法運作。請確保兩個儲存庫的版本相同，且 DynamoRevit 提取的是相符版本的 nuget 相依性。這些版本定義在 DynamoRevit 儲存庫的 package.json 檔案中。

使用 Visual Studio 為 DynamoRevit 除錯

在上一節〈從原始碼建置 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 的增益集執行。

1. Wall.ByCurveAndHeight 節點擲出例外狀況

首先開啟 DynamoRevit.All.sln 方案檔，啟動 Revit，然後啟動 DynamoRevit 增益集。然後使用「Attach to Process」視窗將 Visual Studio 附加到 Revit 處理序。

Revit 和 DynamoRevit 必須執行才能顯示為可用處理序

1. 選取「Debug > Attach to Process...」以開啟「Attach to Process」視窗

2. 將「Transport」設定為「Default」

3. 選取 Revit.exe

4. 選取「Attach」

將 Visual Studio 附加到 Revit 後，開啟 Wall.cs 中的 Wall.ByCurveAndHeight 原始程式碼。我們可以在「方案總管」的「Libraries > RevitNodes > Elements」下，在檔案的 Public static constructors 區域找到這段程式碼。在牆類型的建構函式中設定中斷點，以便在 Dynamo 中執行節點時，處理序會中斷，我們可以逐行執行程式碼。Dynamo zero touch 類型的建構函式通常以 By<parameters> 開頭。

1. 具有 Wall.ByCurveAndHeight 建構函式的類別檔案

2. 按一下行號的左側，或在程式碼行上按一下右鍵並選取「Breakpoint > Insert Breakpoint」可設定中斷點。

設定中斷點後，我們需要處理序逐步執行 Wall.ByCurveAndHeight 函數。在 Dynamo 中將配線重新連接至其中一個埠 (這會強制節點重新執行)，可再次執行此函數。在 Visual Studio 中會叫用中斷點。

1. 中斷點圖示在叫用時會變更

2. 「呼叫堆疊」視窗顯示下一個即將執行的方法

現在，請逐步檢查建構函式中的每一行，直到遇到例外狀況。以黃色亮顯的程式碼是下一個要執行的陳述式。

1. 用於瀏覽程式碼的除錯工具

2. 按「Step Over」以執行亮顯的程式碼，然後在函數傳回後暫停執行

3. 要執行的下一個陳述式，以黃色亮顯和箭頭指示

如果我們繼續逐步執行函數，將會遇到 DynamoRevit 視窗中顯示的例外狀況。查看「呼叫堆疊」視窗，我們可以看到例外狀況一開始是從名為 Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve 的方法所擲出。多虧這裡已經處理了例外狀況，因此 Dynamo 沒有當機。除錯程序將我們引導到原始式碼中的另一個方法，提供發生問題的脈絡。

由於這不是開放原始碼資源庫，因此我們無法在該處進行變更 - 現在，我們擁有更多資訊，可以透過提交 Github 問題回報問題更多內容，或者我們可以針對此問題提出提取請求以提供解決方法。

1. 當我們叫用導致 Walls.cs 中發生例外狀況的陳述式時，除錯程序會盡可能將我們引導到使用者程式碼中 ProtoToRevitCurve.cs 內發生問題的根本所在位置

2. 導致 ProtoToRevitCurve.cs 中例外狀況的陳述式

3. 在「呼叫堆疊」中，我們可以看到例外狀況是來自非使用者程式碼

4. 提供例外狀況相關資訊的快顯視窗

此程序可套用至我們處理的任何原始碼檔案。如果我們要開發 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 團隊在〈提取請求〉一節所列的指導方針建立提取請求。

Dynamo 的原始碼託管在 Github，可供任何人複製並提出貢獻。在本章中，我們將逐步瞭解如何使用 git 複製儲存庫、使用 Visual Studio 編譯原始碼檔案、執行本端建置版本並除錯，以及從 Github 提取任何新變更。

在 Github 上找出 Dynamo 儲存庫

Github 是一種以 git 為基礎的託管服務，是一種可追蹤變更並協調不同使用者工作的版本控制系統。Git 是一種工具，我們可以利用它來下載 Dynamo 的原始碼檔案，並透過一些指令保持更新。使用此方法可避免每次更新時都要手動下載和取代原始碼檔案這些不必要且繁雜的工作。Git 版本控制系統會追蹤本端和遠端程式碼儲存庫之間的任何差異。

Dynamo 的原始碼託管在 DynamoDS Github 上的 https://github.com/DynamoDS/Dynamo 儲存庫

Dynamo 原始碼檔案。

1. 複製或下載整個儲存庫

2. 檢視其他 DynamoDS 儲存庫

3. Dynamo 的原始碼檔案

4. Git 特有的檔案

使用 git 提取 Dynamo 儲存庫

在複製儲存庫之前，必須先安裝 git。請遵循此簡短指南以瞭解安裝步驟，以及如何設定 Gihub 使用者名稱和電子郵件。在此範例中，我們將在指令行使用 git。本指南假設您使用 Windows，但您也可以在 mac 或 Linux 上使用 git 複製 Dynamo 原始碼。

我們需要 Dynamo 儲存庫的 URL 才能從中複製。您可以在儲存庫頁面的「Clone or download (複製或下載)」按鈕中找到。複製要貼至指令提示的 URL。

1. 選取「Clone or download」

2. 複製 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 儲存庫的主分支相同。

1. Dynamo 的原始碼檔案

2. Git 檔案

使用 Visual Studio 建置儲存庫

將原始碼檔案複製到本端電腦後，我們可以建置 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 方案。

1. 選取「File > Open > Project/Solution」

2. 瀏覽至 Dynamo 儲存庫並開啟 src 資料夾

3. 選取 Dynamo.All.sln 方案檔

4. 選取「Open」

在建置方案之前，必須先指定一些設定。我們要先建置 Dynamo 的除錯版本，讓 Visual Studio 在除錯時可以收集更多資訊協助我們開發，而且我們要以 AnyCPU 作為目標。

這些設定會變成 bin 資料夾內的資料夾

1. 在此範例中，我們選擇「Debug」做為「Solution Configuration (方案組態)」

2. 將「Solution Platform (方案平台)」設定為「Any CPU」

開啟專案後，我們可以建置方案。此處理序將會建立一個可以執行的 DynamoSandbox.exe 檔案。

建置專案會還原 NuGet 相依性。

1. 選取「Build > Build Solution」

2. 在「Output (輸出)」視窗中確認建置成功，看起來應該類似 ==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====

執行本端建置版本

如果 Dynamo 建置成功，Dynamo 儲存庫中會建立一個包含 DynamoSandbox.exe 檔案的 bin 資料夾。在我們的範例中，我們使用「Debug (除錯)」選項建置，因此可執行檔位於 bin\AnyCPU\Debug。執行此檔案將開啟 Dynamo 的本端建置版本。

1. 我們剛剛建置的 DynamoSandbox 可執行檔。執行此檔案以啟動 Dynamo。

我們現在已經幾乎設定好，可以開始開發 Dynamo。

如需有關為其他平台 (例如 Linux 或 OS X) 建置 Dynamo 的指示，請造訪此 Wiki 頁面。

使用 Visual Studio 為本端建置版本除錯

除錯是識別、隔離和修正錯誤或問題的一個過程。從原始碼成功建置 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 建置並啟動應用程式

1. 將組態設定為「Debug」

2. 將平台設定為「Any CPU」

3. 將啟動專案設定為「DynamoSandbox」

4. 按一下「Start」以開始為處理序除錯

或者，我們可能想要為已在執行的 Dynamo 處理序除錯，以疑難排解特定圖表開啟或套件的問題。基於這個原因，我們會在 Visual Studio 中開啟專案的原始碼檔案，並使用「Attach to Process」除錯功能表項目附加到執行中的 Dynamo 處理序。

將正在執行的處理序附加到 Visual Studio

1. 選取「Debug > Attach to Process...」

2. 選擇「DynamoSandbox.exe」

3. 選取「Attach」

在這兩種情況下，我們都會將除錯程式附加到要除錯的處理序。我們可以在啟動除錯程式之前或之後設定程式碼中的中斷點，這會導致處理序在執行該行程式碼之前立即暫停。如果在除錯時擲回未攔截的例外狀況，Visual Studio 會跳到原始程式碼中發生該例外狀況的位置。這是一種尋找簡單當機、未處理例外狀況，以及瞭解應用程式執行流的有效方法。

為 DynamoSandbox 除錯時，我們在 Color.ByARGB 節點的建構函式中設定一個中斷點，這會導致 Dynamo 處理序在節點具現化時暫停。如果此節點擲出例外狀況或導致 Dynamo 當機，我們可以逐步執行建構函式中的每一行，以尋找發生問題的位置。

1. 中斷點

2. 顯示目前正在執行之函式和先前函式呼叫的呼叫堆疊。

在下一節〈從原始碼建置 DynamoRevit〉中，我們將逐步介紹除錯的特定範例，並說明如何設定中斷點、逐步執行程式碼，以及解讀呼叫堆疊。

提取最新建置版本

由於 Dynamo 原始碼託管在 Github 上，因此讓本端原始碼檔案保持更新最簡單的方式是使用 git 指令提取變更。

使用指令行，將目前目錄設定為 Dynamo 儲存庫：

cd C:\Users\username\Documents\GitHub\Dynamo

將 "username" 取代為您的使用者名稱

使用下列指令提取最新變更：

git pull origin master

1. 在此，我們可以看到本端儲存庫已經以遠端的變更更新。

除了提取更新，還有四個 git 工作流程需要熟悉。

• Fork (分岔) Dynamo 儲存庫，建立一份與原始儲存庫分開的複本。此處所做的任何變更都不會影響原始儲存庫，也可以從中擷取更新或利用提取請求來提交更新。Fork 不是 git 指令，而是 github 新增的一個工作流程 - 分岔-提取請求模型是參與線上開放原始碼專案其中一個最常見的工作流程。如果您想要為 Dynamo 做出貢獻，請學習這項功能。

• Branch (分支) - 在分支內容中獨立於其他工作進行實驗或新功能。這可讓您更輕鬆地傳送提取請求。

• 在完成一部分工作之後，以及做了可能想要退回的變更之後，請經常進行 commit (認可)。認可動作會記錄對儲存庫的變更，在對主要 Dynamo 儲存庫提出提取請求時，也會看到該筆認可內容。

• 當準備好正式將變更提出到主要 Dynamo 儲存庫時，請建立 pull request (提取請求)。

Dynamo 團隊對於建立提取請求有特定指示。請參閱本文件中的〈提取請求〉一節，以瞭解要處理的更多詳細項目。

請參閱此文件頁面，以取得 git 指令的參考清單。

本指南的目的是什麼？

本指南的目的是協助您瀏覽使用 C# 開發 Dynamo 的可能範圍，從如何建立 zero-touch 節點到建立延伸。

GitHub 上的 Dynamo 原始碼

我們提供哪些額外的開發資源？

Dynamo：下載 Dynamo 最新的穩定建置版本和每日建置版本

https://dynamobuilds.com/

Dynamo GitHub：Dynamo 是 Github 上的一個開放原始碼開發專案。

https://github.com/DynamoDS/Dynamo

Dynamo Github Wiki：這是開發人員文件的主要資源。

https://github.com/DynamoDS/Dynamo/wiki

節點命名標準提供在 Dynamo 中命名品類、節點以及輸入埠和輸出埠的標準和準則。

https://github.com/DynamoDS/Dynamo/wiki/Naming-Standards

Dynamo 語言/API 指南：Dynamo 的 API 文件目前涵蓋核心功能

https://dynamods.github.io/DynamoAPI/

DynamoBIM：其他資訊、學習內容和論壇的最佳來源是 DynamoBIM 網站。

https://dynamobim.org

Dynamo 字典：所有 Dynamo 節點的可搜尋資料庫

https://dictionary.dynamobim.com/

DesignScript Language Guide：撰寫 DesignScript 的 PDF 指南

PDF

如何對本指南提出變更的建議？

本文件開放提供建議。您可以直接在 Github 中建立變更請求來進行。

延伸是 Dynamo 生態系統中功能強大的開發工具。這些工具可讓開發人員根據 Dynamo 的互動和邏輯驅動自訂功能。延伸可以分為兩個主要品類：延伸和視圖延伸。如同字面意思，視圖延伸架構可讓您透過註冊自訂功能表項目的方式來延伸 Dynamo 使用者介面。一般延伸則以非常相似的方式 (除了使用者介面之外) 運作。例如，我們可以建置一個延伸，將特定資訊記錄到 Dynamo 主控台。此情況不需要自訂使用者介面，因此也可以使用延伸完成。

延伸案例研究

按照 DynamoSamples Github 儲存庫的 SampleViewExtension 範例，我們將逐步瞭解建立簡單的共存式視窗即時在圖表中顯示作用中節點所需的步驟。視圖延伸會要求我們為視窗建立使用者介面，並將值與視圖模型繫結。

1. 按照 Github 儲存庫中 SampleViewExtension 範例而開發的視圖延伸視窗。

雖然我們將從頭開始建置範例，但您也可以下載並建置 DynamoSamples 儲存庫做為參考。

此逐步解說將明確參考在 DynamoSamples/src/ 中名為 SampleViewExtension 的專案。

如何實作視圖延伸

視圖延伸有三個基本部分：

• 一個組合，其中包含實作 IViewExtension 的類別，以及建立視圖模型的類別

• 一個 .xml 檔案，告訴 Dynamo 在執行時期應在何處尋找此組合，以及延伸的類型

• 一個 .xaml 檔案，將資料與圖形顯示繫結，並決定視窗的外觀

1.建立專案結構

首先，建立一個名為 SampleViewExtension 的新 Class Library 專案。

1. 選取「File > New > Project」建立新專案

2. 選取「Class Library」

3. 將專案命名為 SampleViewExtension

4. 選取「Ok」

在此專案中，我們需要兩個類別。一個類別將實作 IViewExtension，另一個類別將實作 NotificationObject.。IViewExtension 包含有關如何部署、載入、參考和處置延伸的所有資訊。NotificationObject 提供 Dynamo 和 IDisposable 中發生變更的通知。發生變更時，計數將相應更新。

1. 名為 SampleViewExtension.cs 的類別檔案，將實作 IViewExtension

2. 名為 SampleWindowViewMode.cs 的類別檔案，將實作 NotificationObject

若要使用 IViewExtension，我們需要 WpfUILibrary NuGet 套件。安裝此套件會自動安裝 Core、Services 和 ZeroTouchLibrary 等套件。

1. 選取 WpfUILibrary

2. 選取「Install」以安裝所有相依套件

2.實作 IViewExtension 類別

從 IViewExtension 類別，我們將決定 Dynamo 啟動時、載入延伸時，以 及Dynamo 關閉時會發生什麼情況。在 SampleViewExtension.cs 類別檔案中，加入以下程式碼：

SampleViewExtension 類別建立可點選的功能表項目，以開啟視窗並連接至視圖模型和視窗。

• public class SampleViewExtension : IViewExtension SampleViewExtension 從 IViewExtension 介面繼承，提供建立功能表項目所需的一切。

• sampleMenuItem = new MenuItem { Header = "Show View Extension Sample Window" }; 建立 MenuItem，並加入「View」功能表。

1. 功能表項目

• sampleMenuItem.Click += (sender, args) 觸發在按一下功能表項目時將開啟新視窗的事件

• MainGrid = { DataContext = viewModel } 參考我們將建立的 .xaml 檔案中的 Main Grid，設定視窗中主格線的資料內容

• Owner = p.DynamoWindow 將彈出視窗的擁有者設定為 Dynamo。這表示新視窗依賴於 Dynamo，因此動作 (例如最小化、最大化和還原 Dynamo) 將導致新視窗遵循此相同行為

• window.Show(); 顯示已設定其他視窗性質的視窗

3.實作視圖模型

現在，我們已建立視窗的某些基本參數，我們將加入回應各種 Dynamo 相關事件的邏輯，並指示使用者介面根據這些事件進行更新。將以下程式碼複製到 SampleWindowViewModel.cs 類別檔案：

此視圖模型類別實作會監聽 CurrentWorkspaceModel，並在節點加入工作區或從工作區中移除時觸發事件。這會引發性質變更，通知使用者介面或已繫結的元素，資料已變更而需要更新。呼叫 ActiveNodeTypes getter，這會在內部呼叫其他協助函數 getNodeTypes()。此函數會逐一查看圖元區上所有作用中的節點，填入包含這些節點名稱的字串，然後將此字串傳回 .xaml 檔案中的繫結，以顯示在快顯視窗中。

定義延伸的核心邏輯後，我們現在將使用 .xaml 檔案指定視窗的外觀詳細資料。我們只需要一個簡單的視窗，透過 TextBlock Text 中的 ActiveNodeTypes 性質繫結顯示字串。

1. 在專案上按一下右鍵，然後選取「Add > New Item...」

2. 選取我們將做變更以建立視窗的「使用者控制項」樣板

3. 將新檔案命名為 SampleWindow.xaml

4. 選取「Add」

在視窗 .xaml 程式碼中，我們需要將 SelectedNodesText 繫結到文字區塊。將以下程式碼加入 SampleWindow.xaml：

• Text="{Binding ActiveNodeTypes}" 將 SampleWindowViewModel.cs 中 ActiveNodeTypes 的性質值繫結到視窗中的 TextBlock Text 值。

我們現在要初始化 .xaml C# 支援檔案 SampleWindow.xaml.cs 中的範例視窗。將以下程式碼加入 SampleWindow.xaml：

視圖延伸現在已準備好建置並加到 Dynamo 中。Dynamo 需要 xml 檔案，才能將輸出 .dll 註冊為延伸。

1. 在專案上按一下右鍵，然後選取「Add > New Item...」

2. 選取 XML 檔案

3. 將檔案命名為 SampleViewExtension_ViewExtensionDefinition.xml

4. 選取「Add」

• 檔名會遵循 Dynamo 標準，以參考如下的延伸組合："extensionName"_ViewExtensionDefinition.xml

在 xml 檔案中，加入以下程式碼，以告訴 Dynamo 在何處尋找延伸組合：

• 在此範例中，我們將組合建置到預設的 Visual Studio 專案資料夾。將 <AssemblyPath>...</AssemblyPath> 目標取代為組合位置。

最後一步是將 SampleViewExtension_ViewExtensionDefinition.xml 檔案複製到 Dynamo 位於 Dynamo Core 安裝目錄 C:\Program Files\Dynamo\Dynamo Core\1.3\viewExtensions 中的視圖延伸資料夾。請務必注意，extensions 和 viewExtensions 是不同的資料夾。將 xml 檔案放在不正確的資料夾中，可能會導致在執行時期無法正確載入。

1. 我們複製到 Dynamo 的視圖延伸資料夾中的 .xml 檔案

這是視圖延伸的基本簡介。如需更複雜的案例研究，請參閱 Github 上的開放原始碼專案 DynaShape 套件。該套件使用可在 Dynamo 模型視圖中進行即時編輯的視圖延伸。

瞭解如何建立 Zero-Touch 專案後，我們可以逐步瀏覽 Dynamo Github 上的 ZeroTouchEssentials 範例，更深入地瞭解建立節點的詳細資訊。

許多 Dynamo 的標準節點本質上是 Zero-Touch 節點，如上面大多數的 Math、Color 和 DateTime 節點。

若要開始，請從 下載 ZeroTouchEssentials 專案

在 Visual Studio 中，開啟 ZeroTouchEssentials.sln 方案檔並建置方案。

ZeroTouchEssentials.cs 檔案包含我們要匯入至 Dynamo 的所有方法。

開啟 Dynamo 並匯入 ZeroTouchEssentials.dll，以取得我們要在以下範例中參考的節點。

預設輸入值

• 將方法參數設定為預設值：inputNumber = 2.0

1. 將游標懸停在節點輸入埠上時，會出現預設值

傳回多個值

傳回多個值比建立多個輸入要複雜一些，因此需要使用字典傳回。字典的項目會成為節點輸出端的埠。透過以下方式可以建立多個傳回埠：

• 加入 using System.Collections.Generic; 以使用 Dictionary<>。

• 加入 using Autodesk.DesignScript.Runtime; 以使用 MultiReturn 屬性。這會參考 DynamoServices NuGet 套件中的「DynamoServices.dll」。

• 在方法中加入 [MultiReturn(new[] { "string1", "string2", ... more strings here })] 屬性。字串會參考字典中的鍵，並成為輸出埠名稱。

• 從函數傳回 Dictionary<>，其中的鍵與屬性中的參數名稱相符：return new Dictionary<string, object>

傳回多個輸出的節點。

1. 請注意，現在有兩個輸出埠，根據我們為字典的鍵輸入的字串進行命名。

文件、工具提示和搜尋

最佳實踐是在 Dynamo 節點中加入文件，描述節點的功能、輸入、輸出、搜尋標籤等。這可以透過 XML 文件標籤完成。透過以下方式可以建立 XML 文件：

• 前面有三條斜線的任何註解文字都會視為文件

  • 例如：/// Documentation text and XML goes here

• 三條斜線後，在 Dynamo 匯入 .dll 時將讀取的方法上方建立 XML 標籤

  • 例如：/// <summary>...</summary>

• 在 Visual Studio 中選取「Project > Project Properties > Build」並勾選「XML documentation file」以啟用 XML 文件

1. Visual Studio 將在指定位置產生 XML 檔案

標籤類型如下：

• /// <summary>...</summary> 是節點的主文件，會以工具提示的形式出現在左側搜尋列中的節點上

• /// <param name="inputName">...</param> 將建立特定輸入參數的文件

• /// <returns>...</returns> 將建立輸出參數的文件

• /// <returns name = "outputName">...</returns> 將建立多個輸出參數的文件

• /// <search>...</search> 將根據逗號分隔清單將您的節點與搜尋結果比對。例如，如果我們建立細分網格的節點，我們可能要加入標籤，例如「網格」、「細分」和「catmull-clark」。

以下是包含輸入和輸出描述的範例節點，以及將顯示在資源庫中的摘要。

請注意，此範例節點的程式碼包含：

1. 節點摘要

2. 輸入描述

3. 輸出描述

物件

Dynamo 沒有 new 關鍵字，因此需要使用靜態建構方法建構物件。透過以下方式可以建構物件：

• 除非另有要求，否則將建構函式設為內部的 internal ZeroTouchEssentials()

• 使用靜態方法建構物件，例如 public static ZeroTouchEssentials ByTwoDoubles(a, b)

注意事項：Dynamo 使用「By」字首指出靜態方法是建構函式，雖然這是選擇性的，但使用「By」可協助您的資源庫更符合既有的 Dynamo 型式。

匯入 ZeroTouchEssentials dll 後，資源庫中將會有 ZeroTouchEssentials 節點。使用 ByTwoDoubles 節點可以建立此物件。

使用 Dynamo 幾何圖形類型

Dynamo 資源庫可以使用原生 Dynamo 幾何圖形類型做為輸入，並建立新幾何圖形做為輸出。透過以下方式可以建立幾何圖形類型：

• 在專案中的 C# 檔案頂端包括 using Autodesk.DesignScript.Geometry; 參考「ProtoGeometry.dll」，並將 ZeroTouchLibrary NuGet 套件加入專案。

• 重要事項： 管理未從函數傳回的幾何圖形資源，請參閱下方的〈Dispose/using 陳述式〉一節。

注意事項：Dynamo 幾何圖形物件的使用方式與任何其他傳入函數的物件相同。

取得曲線長度後加倍的節點。

1. 此節點接受曲線幾何圖形類型做為輸入。

Dispose/using 陳述式

除非您使用 Dynamo 2.5 版或更高版本，否則必須手動管理未從函數傳回的幾何圖形資源。在 Dynamo 2.5 和更高版本中，幾何圖形資源由系統內部處理，但是，如果您的使用案例較複雜，或者您必須在決定性時間減少消耗記憶體，您可能仍需要手動處置幾何圖形。Dynamo 引擎將處理從函數傳回的任何幾何圖形資源。透過以下方式可以手動處理未傳回的幾何圖形資源：

• 使用 using 陳述式：

• 使用手動的 Dispose 呼叫：

移轉

發佈較新版本的資源庫時，節點名稱可能會變更。在移轉檔案中可以指定名稱變更，以便在更新時，以舊版資源庫建置的圖表可以持續正常運作。透過以下方式可以實作移轉：

• 使用以下格式，在與 .dll 相同的資料夾中建立 .xml 檔案：「BaseDLName」.Migrations.xml

• 在 .xml 中，建立單一 <migrations>...</migrations> 元素

• 在 migrations 元素內，為每個名稱變更建立 <priorNameHint>...</priorNameHint> 元素

• 對每個名稱變更，提供 <oldName>...</oldName> 和 <newName>...</newName> 元素

1. 按一下右鍵，然後選取「Add > New Item」

2. 選擇 XML File

3. 對於此專案，我們將移轉檔案命名為 ZeroTouchEssentials.Migrations.xml

此範例程式碼告訴 Dynamo，任何名為 GetClosestPoint 的節點現在都命名為 ClosestPointTo。

泛型

Zero-Touch 目前不支援使用泛型。可以使用泛型，但不能在直接匯入且未設定類型的程式碼中使用。無法顯示屬於泛型且未設定類型的方法、性質或類別。

在以下範例中，不會匯入類型為 T 的 Zero-Touch 節點。如果將剩餘的資源庫匯入至 Dynamo，則會發生缺少類型的例外狀況。

在此範例中設定類型的情況下使用泛型類型，將匯入至 Dynamo。

在開始開發之前，為新專案建立堅實的基礎非常重要。Dynamo 開發人員社群中有幾個專案樣板非常適合開始，但瞭解如何從頭開始一個專案更有價值。從頭開始建立一個專案可以更深入地瞭解開發過程。

建立 Visual Studio 專案

Visual Studio 是一個功能強大的 IDE，我們可在其中建立專案、新增參考、建置 .dlls 和除錯。建立新專案時，Visual Studio 也會建立一個「方案」，這是組織專案的結構。多個專案可以在單一方案中，也可以一起建置。若要建立 ZeroTouch 節點，我們需要啟動新的 Visual Studio 專案，然後在當中撰寫 C# 類別資源庫並建置 .dll。

Visual Studio 中的「新增專案」視窗

1. 首先開啟 Visual Studio 並建立新專案：「File > New > Project」

2. 選擇「Class Library」專案樣板

3. 為專案命名 (我們已將專案命名為 MyCustomNode)

4. 設定專案的檔案路徑。在此範例中，我們讓它保留在預設位置

5. 選取「Ok」

Visual Studio 會自動建立 C# 檔案並開啟。我們應為其指定適當的名稱、設定工作區，然後以此乘法方法更換預設程式碼。

1. 從「View」開啟「方案總管」和「輸出」視窗。

2. 在右側的「方案總管」中，將 Class1.cs 檔案更名為 SampleFunctions.cs。

3. 為乘法函數加入上述程式碼。我們稍後會介紹 Dynamo 如何讀取您的 C# 類別。

4. 「方案總管」：您可以從這裡存取專案中的所有內容。

5. 「輸出」視窗：我們稍後需要此視窗，以查看建置是否成功。

下一步是建置專案，但在那之前，需要檢查一些設定。首先，請確定在「平台目標」選取了「Any CPU」或「x64」，且「專案屬性」中未勾選「Prefer 32-bit」。

1. 選取「Project > "ProjectName" Properties」開啟專案屬性

2. 選取「Build」頁面

3. 從下拉式功能表中選取「Any CPU」或「x64」

4. 確保未勾選「Prefer 32-bit」

現在我們可以建置專案來建立 .dll。若要執行，請從「Build」功能表中選取「Build Solution」，或使用捷徑 CTRL+SHIFT+B。

1. 選取「Build > Build Solution」

2. 您可以查看「輸出」視窗，判斷專案是否成功建置

如果專案已成功建置，則專案的 bin 資料夾中會有一個名為 MyCustomNode 的 .dll。在此範例中，我們將專案的檔案路徑保留為 Visual Studio 的預設路徑：c:\users\username\documents\visual studio 2015\Projects。我們來看看專案的檔案結構。

1. bin 資料夾包含從 Visual Studio 建置的 .dll。

2. Visual Studio 專案檔。

3. 類別檔案。

4. 由於我們的方案組態已設定為「Debug」，因此將在 bin\Debug 中建立 .dll。

現在我們可以開啟 Dynamo 並匯入 .dll。使用「加入」功能，瀏覽至專案的 bin 位置，然後選取要開啟的 .dll。

1. 選取「加入」按鈕以匯入 .dll

2. 瀏覽至專案位置。我們的專案位於 Visual Studio 的預設檔案路徑：C:\Users\username\Documents\Visual Studio 2015\Projects\MyCustomNode

3. 選取要匯入的 MyCustomNode.dll

4. 按一下「Open」以載入 .dll

如果在名為 MyCustomNode 的資源庫中建立了品類，則表示已成功匯入 .dll！但是，Dynamo 建立了兩個節點，而我們只想要一個節點。在下一節中，我們將說明發生這個狀況的原因，以及 Dynamo 如何讀取 .dll。

1. Dynamo 資源庫中的 MyCustomNode。「資源庫」品類由 .dll 名稱決定。

2. 圖元區上的 SampleFunctions.MultiplyByTwo。

Dynamo 如何讀取類別和方法

Dynamo 載入 .dll 時，會將所有公用靜態方法顯示為節點。建構函式、方法和性質將分別轉換為「建立」、「動作」和「查詢」節點。在乘法範例中，MultiplyByTwo() 方法會變成 Dynamo 中的「動作」節點。這是因為節點已根據其方法和類別命名。

1. 輸入根據方法的參數名稱命名為 inputNumber。

2. 輸出預設命名為 double，因為這是要傳回的資料類型。

3. 節點命名為 SampleFunctions.MultiplyByTwo，因為這些是類別名稱和方法名稱。

在以上範例中，多建立一個 SampleFunctions 建立節點是因為我們未明確提供建構函式，因此自動建立了一個建構函式。我們可以在 SampleFunctions 類別中建立一個空的私用建構函式來避免發生這個情況。

1. Dynamo 已將我們的方法匯入為「建立」節點

加入 Dynamo NuGet 套件參考

乘法節點非常簡單，不需要參考 Dynamo。例如，如果我們要存取任何 Dynamo 功能來建立幾何圖形，則需要參考 Dynamo NuGet 套件。

若要在 Visual Studio 專案中參考這些套件，請從上面連結的 NuGet 下載套件並手動參考 .dll，或使用 Visual Studio 中的 NuGet 套件管理員。首先，我們可以逐步瞭解如何在 Visual Studio 中使用 NuGet 安裝這些套件。

1. 選取「Tools > NuGet Package Manager > Manage NuGet Packages for Solution...」開啟 NuGet 套件管理員

這是 NuGet 套件管理員。此視窗顯示已為專案安裝的套件，也可讓使用者瀏覽其他套件。如果發行了新版本的 DynamoServices 套件，則可從此處更新套件或回復至舊版。

1. 選取「瀏覽」並搜尋 DynamoVisualProgramming 以顯示 Dynamo 套件。

2. Dynamo 套件。選取一個套件會顯示套件的目前版本和內容描述。

3. 選取您需要的套件版本，然後按一下「安裝」。這會為您正在處理的特定專案安裝套件。由於我們使用的是 Dynamo 的最新穩定版本 1.3 版，因此請選擇對應的套件版本。

若要手動加入從瀏覽器下載的套件，請從「方案總管」開啟「參考管理員」，然後瀏覽套件。

1. 以右鍵按一下「References」，然後選取「Add Reference」。

2. 選取「Browse」以瀏覽至套件位置。

現在 Visual Studio 已正確設定，我們也已成功將 .dll 加入 Dynamo，因此，我們已經有堅實的基礎可以讓概念繼續發揮。這只是開始，請繼續跟進，進一步瞭解如何建立自訂節點。

在 Visual Studio 專案啟動並執行時，我們將逐步瞭解如何建置一個自訂節點來建立一個矩形的儲存格網格。雖然我們可以使用幾個標準節點建立此節點，但它是一個實用的工具，可以輕鬆包含在 Zero-Touch 節點中。與網格線相反，儲存格可以繞其中心點調整比例、查詢其角落頂點，或建置到面中。

本範例將介紹建立 Zero-Touch 節點時要注意的一些功能和概念。建置自訂節點並加入 Dynamo 後，請務必檢閱「深入瞭解 Zero-Touch」頁面，以更深入地查看預設輸入值、傳回多個值、文件、物件、使用 Dynamo 幾何圖形類型，以及移轉。

自訂矩形網格節點

若要開始建置網格節點，請建立新的 Visual Studio 類別資源庫專案。請參閱「入門」頁面，以取得如何設定專案的深入逐步解說。

1. 選擇「Class Library」做為專案類型

2. 將專案命名為 CustomNodes

由於我們要建立幾何圖形，因此需要參考適當的 NuGet 套件。從 Nuget 套件管理員安裝 ZeroTouchLibrary 套件。using Autodesk.DesignScript.Geometry; 陳述式需要此套件。

1. 瀏覽 ZeroTouchLibrary 套件

2. 我們將在 Dynamo Studio 的目前建置 (1.3) 中使用此節點。選取與此相符的套件版本。

3. 請注意，我們也已將類別檔案更名為 Grids.cs

接下來，我們需要建立 RectangularGrid 方法將位於的命名空間和類別。節點會根據方法名稱和類別名稱在 Dynamo 中命名。我們還不需要將此內容複製到 Visual Studio。

Autodesk.DesignScript.Geometry; 參考 ZeroTouchLibrary 套件中的 ProtoGeometry.dll。建立清單需要 System.Collections.Generic

現在，我們可以加入繪製矩形的方法。類別檔案應如下所示，可複製到 Visual Studio。

如果專案看起來與此類似，請繼續並嘗試建置 .dll。

1. 選擇「建置」>「建置方案」

檢查專案的 bin 資料夾是否有 .dll。如果建置成功，我們可以將 .dll 加入 Dynamo。

1. Dynamo 資源庫中的自訂 RectangularGrids 節點

2. 圖元區上的自訂節點

3. 將 .dll 加入 Dynamo 的「加入」按鈕

修改自訂節點

在以上範例中，我們建立了一個相當簡單的節點，此節點除了 RectangularGrids 方法外沒有定義太多其他內容。但是，我們也許需要建立輸入埠的工具提示，或為節點提供類似標準 Dynamo 節點的摘要。將這些功能加入自訂節點，可以讓使用者更輕鬆地使用這些節點，尤其是當使用者想要在資源庫中搜尋這些節點時。

1. 預設輸入值

2. xCount 輸入的工具提示

RectangularGrid 節點需要某些基本功能。在以下程式碼中，我們加入了輸入埠和輸出埠的描述、摘要和預設輸入值。

• 對方法參數指定值來提供輸入預設值：RectangularGrid(int xCount = 10, int yCount = 10)

• 建立輸入和輸出的工具提示、搜尋關鍵字，以及 XML 文件前面有 /// 的摘要。

若要加入工具提示，專案目錄中需要一個 xml 檔案。透過啟用選項，Visual Studio 可以自動產生 .xml。

1. 在此啟用 XML 文件檔案並指定檔案路徑。這會產生 XML 檔案。

這樣就可以了！我們建立了一個有幾項標準功能的新節點。下一章〈Zero-Touch 基礎知識〉會更詳細介紹 Zero-Touch 節點開發及需要注意的問題。

以 NodeModel 為基礎的節點提供的靈活性和功能比 Zero-Touch 節點要大得多。在此範例中，我們將加入一個可隨機顯示矩形大小的整合滑棒，將 Zero-Touch 網格節點提升到下一個層次。

滑棒會相對於儲存格的大小調整比例，因此使用者不必為滑棒提供正確範圍。

模型-視圖-視圖模型模式

在 Dynamo 較高的層次，有兩個部分可以建立模型-視圖關係：

• NodeModel 類別建立節點的核心邏輯 (「模型」)

• INodeViewCustomization 類別自訂檢視 NodeModel 的方式 (「視圖」)

NodeModel 物件已經有一個關聯的視圖-模型 (NodeViewModel)，因此我們只需將焦點放在模型上，以及自訂使用者介面的視圖。

如何實作 NodeModel

NodeModel 節點與 Zero-Touch 節點有幾項顯著差異，我們將在此範例中進行介紹。在跳至使用者介面自訂之前，我們先建置 NodeModel 邏輯。

1.建立專案結構：

NodeModel 節點只能呼叫函數，因此我們需要將 NodeModel 和函數分到不同的資源庫。對 Dynamo 套件執行此作業的標準方式是為每個套件建立單獨的專案。首先，建立新的方案以包含專案。

1. 選取「File > New > Project」

2. 選取「Other Project Types」以顯示方案選項

3. 選取「Blank Solution」

4. 將方案命名為 CustomNodeModel

5. 選取「Ok」

在方案中建立兩個 C# 類別資源庫專案：一個用於函數，一個用於實作 NodeModel 介面。

1. 在「方案」上按一下右鍵，然後選取「Add > New Project」

2. 選擇「類別庫」

3. 將其命名為 CustomNodeModel

4. 按一下「Ok」

5. 重複此程序，加入另一個名為 CustomNodeModelFunctions 的專案

接下來，我們需要將自動建立的類別資源庫更名，並在 CustomNodeModel 專案中加入一個資源庫。GridNodeModel 類別實作抽象 NodeModel 類別，GridNodeView 用於自訂視圖，GridFunction 包含我們需要呼叫的任何函數。

1. 在 CustomNodeModel 專案上按一下右鍵，選取「Add > New Item...」並選擇「Class」，以加入其他類別。

2. 在 CustomNodeModel 專案中，我們需要 GridNodeModel.cs 和 GridNodeView.cs 類別

3. 在 CustomNodeModelFunction 專案中，我們需要 GridFunctions.cs 類別

在類別中加入任何程式碼之前，請先為此專案加入必要的套件。CustomNodeModel 需要 ZeroTouchLibrary 和 WpfUILibrary，CustomNodeModelFunction 只需要 ZeroTouchLibrary。WpfUILibrary 將用於我們稍後執行的使用者介面自訂，ZeroTouchLibrary 將用於建立幾何圖形。可以個別為專案加入套件。由於這些套件具有相依性，因此將自動安裝 Core 和 DynamoServices。

1. 在專案上按一下右鍵，然後選取「Manage NuGet Packages」

2. 只會為該專案安裝必要的套件

Visual Studio 會複製我們參考建置目錄的 NuGet 套件。這可以設定為 False，讓套件中沒有任何不必要的檔案。

1. 選取 Dynamo NuGet 套件

2. 將 Copy Local 設定為 False

2.繼承 NodeModel 類別

如前所述，NodeModel 節點與 ZeroTouch 節點不同的主要層面是對 NodeModel 類別的實作。NodeModel 節點需要此類別中的幾個函數，我們可以透過在類別名稱後加入 :NodeModel 來取得這些函數。

將以下程式碼複製到 GridNodeModel.cs。

這與 Zero-Touch 節點不同。我們來瞭解每個部分在做什麼。

• 指定節點屬性，如名稱、品類、InPort/OutPort 名稱、InPort/OutPort 類型、描述。

• public class GridNodeModel : NodeModel 是從 Dynamo.Graph.Nodes 繼承 NodeModel 類別的類別。

• public GridNodeModel() { RegisterAllPorts(); } 是註冊節點輸入和輸出的建構函式。

• BuildOutputAst() 傳回 AST (抽象語法樹)，這是從 NodeModel 節點傳回資料必要的結構。

• AstFactory.BuildFunctionCall() 從 GridFunctions.cs 呼叫 RectangularGrid 函數。

• new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid) 指定函數及其參數。

• new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue }); 將節點輸入對映至函數參數

• 如果輸入埠未連接，AstFactory.BuildNullNode() 會建置空節點。這可避免在節點上顯示警告。

• RaisePropertyChanged("SliderValue") 在滑棒值變更時通知使用者介面

• var sliderValue = AstFactory.BuildDoubleNode(SliderValue) 在 AST 中建置表示滑棒值的節點

• 在 functionCall 變數 new List<AssociativeNode> { inputAstNodes[0], sliderValue }); 中將輸入變更為 sliderValue 變數

3.呼叫函數

CustomNodeModelFunction 專案將建置到與 CustomNodeModel 分開的組合中，以便能被呼叫。

將以下程式碼複製到 GridFunction.cs。

此函數類別與 Zero-Touch 網格案例研究非常類似，但有一項差異：

• [IsVisibleInDynamoLibrary(false)] 讓 Dynamo 看不到下列方法和類別，因為已經從 CustomNodeModel 呼叫函數。

正如我們加入 NuGet 套件的參考一樣，CustomNodeModel 需要參考 CustomNodeModelFunction 才能呼叫函數。

CustomNodeModel 的 using 陳述式將處於非作用中狀態，直到我們參考該函數

1. 在 CustomNodeModel 上按一下右鍵，然後選取「Add > Reference」

2. 選擇「Projects > Solution」

3. 勾選 CustomNodeModelFunction

4. 按一下「Ok」

4.自訂視圖

若要建立滑棒，我們需要透過實作 INodeViewCustomization 介面來自訂使用者介面。

將以下程式碼複製到 GridNodeView.cs

• public class CustomNodeModelView : INodeViewCustomization<GridNodeModel> 定義自訂使用者介面必要的函數。

設定專案結構後，請使用 Visual Studio 的設計環境建置使用者控制項，並在 .xaml 檔案中定義其參數。從工具方塊中，將滑棒加入 <Grid>...</Grid>。

1. 在 CustomNodeModel 上按一下右鍵，然後選取「Add > New Item」

2. 選取「WPF」

3. 將使用者控制項命名為 Slider

4. 按一下「Add」

將以下程式碼複製到 Slider.xaml

• 滑棒控制項的參數定義在 .xaml 檔案中。Minimum 和 Maximum 屬性定義此滑棒的數值範圍。

• 在 <Grid>...</Grid> 內，我們可以從 Visual Studio 工具箱放置不同的使用者控制項

建立 Slider.xaml 檔案時，Visual Studio 會自動建立一個名為 Slider.xaml.cs 的 C# 檔案以初始化滑棒。變更此檔案中的名稱空間。

• 名稱空間應為 CustomNodeModel.CustomNodeModel

GridNodeModel.cs 定義滑棒計算邏輯。

5.設定為套件

在建置專案之前，最後一步是加入 pkg.json 檔案，讓 Dynamo 可以讀取套件。

1. 在 CustomNodeModel 上按一下右鍵，然後選取「Add > New Item」

2. 選取「Web」

3. 選取 JSON File

4. 將檔案命名為 pkg.json

5. 按一下「Add」

• 將以下程式碼複製到 pkg.json

• "name": 決定 Dynamo 資源庫中套件及其群組的名稱

• "keywords": 提供搜尋 Dynamo 資源庫的搜尋術語

• "node_libraries": [] 是與套件關聯的資源庫

  最後一步是建置方案，並發佈為 Dynamo 套件。請參閱〈套件部署〉一章，以瞭解如何在線上發佈之前建立本端套件，以及如何直接從 Visual Studio 建置套件。

簡介：

Dynamo 2.0 一個是重大版本，某些 API 已變更或移除。影響節點和套件作者其中一項最大的改變是我們改用 JSON 檔案格式。

一般而言，Zero Touch 節點的作者幾乎不需要完成什麼工作，就能在 2.0 中執行他們的套件。

直接從 NodeModel 衍生的使用者介面節點和節點則要付出較多的工作，才能在 2.x 中執行。

延伸的作者也可能需要進行一些潛在的變更 - 取決於他們在延伸中使用多少 Dynamo 核心 API。

一般封裝規則：

• 請勿將 Dynamo 或 Dynamo Revit .dll 與套件一起封裝。這些 dll 將由 Dynamo 載入。如果您組合的版本與使用者載入的版本不同 (例如您散發 dynamo core 1.3，但使用者在 dynamo 2.0 上執行套件)，將會發生神秘的執行時期錯誤。這包括 dll，例如 DynamoCore.dll、DynamoServices.dll、DSCodeNodes.dll、ProtoGeometry.dll

• 如果可以避免，請勿將 newtonsoft.json.net 與套件一起封裝並散發。此 dll 也將由 Dynamo 2.x 載入。可能會發生與上述相同的問題。

• 如果可以避免，請勿將 CEFSharp 與套件一起封裝並散發。此 dll 也將由 Dynamo 2.x 載入。可能會發生與上述相同的問題。

• 如果您需要控制相依性的版本，一般而言請避免與 dynamo 或 revit 共用相依性。

常見問題：

1) 開啟圖表時，某些節點有多個埠具有相同名稱，但圖表在儲存時看起來正常。此問題可能有幾種原因。

常見的根本原因是，節點是使用重新建立埠的建構函式建立的。應該使用載入埠的建構函式。這些建構函式通常會標記 [JsonConstructor] 請參閱下方範例

這可能是因為：

• 沒有相符的 [JsonConstructor]，或未從 JSON .dyn 傳入 Inports 和 Outports。

• 同時將兩個版本的 JSON.net 載入到同一個程序中，會導致 .net 執行時期失敗，因此無法正確使用 [JsonConstructor] 屬性來標記建構函式。

• 與目前 Dynamo 版本不同的 DynamoServices.dll 與套件一起封裝，導致 .net 執行時期無法識別 [MultiReturn] 屬性，因此以各種屬性標記的 zero touch 節點無法套用這些屬性。您可能會發現節點傳回單一字典輸出，而不是多個埠。

2) 在主控台中載入帶有某些錯誤的圖表時，節點會完全遺失。

• 如果還原序列化因某些原因失敗，則可能會發生此情況。最好只序列化您需要的性質。我們可以對您不需要載入或儲存的複雜性質使用 [JsonIgnore] 加以忽略。例如 function pointer, delegate, action, 或 event 等性質。這些性質不應該序列化，因為它們通常無法還原序列化而導致執行時期錯誤。

深度升級：

自訂節點 1.3 -> 2.0

已知問題：

• 註解將轉換為區塊註解，而不是行註解。

• 簡短類型名稱將取代為完整名稱。例如，如果您在再次載入自訂節點時未指定類型，您會看到 var[]..[] - 因為這是預設類型。

Zero Touch 節點 1.3 -> 2.0

• 在 Dynamo 2.0 中，清單和字典類型已經分開，用於建立清單和字典的語法也已經變更。清單使用 [] 初始化，字典則是使用 {}。 如果您先前使用 DefaultArgument 屬性標記 Zero Touch 節點上的參數，並使用清單語法預設為特定清單 (例如 someFunc([DefaultArgument("{0,1,2}")]))，此作業將不再有效，您需要修改 DesignScript 片段對清單使用新的初始化語法。

• 如上所述，請勿將 Dynamo dll 與您的套件 (DynamoCore、DynamoServices 等) 一起散發。

NodeModel 節點 1.3 -> 2.0

NodeModel 節點需要最多工作才能更新到 Dynamo 2.x。除了用於實體化節點類型新例證的正規 nodeModel 建構函式外，進階一點，您還需要實作只用於從 json 載入節點的建構函式。若要區分這些建構函式，請使用來自 newtonsoft.Json.net 的屬性 [JsonConstructor] 標記載入時間建構函式。

JSON 建構函式

更新衍生自 NodeModel 基準類別 (或其他 Dynamo 核心基準類別，例如 DSDropDownBase) 的節點時，最常見的變更是需要將 JSON 建構函式加入您的類別。

您原始的無參數建構函式仍會處理初始化在 Dynamo 中建立的新節點 (例如，透過資源庫)。必須有 JSON 建構函式，才能初始化從儲存的 .dyn 或 .dyf 檔案還原序列化 (已載入) 的節點。

JSON 建構函式與基本建構函式不同，因為它有 inPorts 和 outPorts 的 PortModel 參數，由 JSON 載入邏輯提供。此處不需要呼叫註冊節點的埠，因為資料存在於 .dyn 檔案中。JSON 建構函式的範例如下所示：

using Newtonsoft.Json; //New dependency for Json

………

[JsonConstructor] //Attribute required to identity the Json constructor

//Minimum constructor implementation. Note that the base method invocation must also be present.

FooNode(IEnumerable<PortModel> inPorts, IEnumerable<PortModel> outPorts) : base(inPorts, outPorts) { }

此語法 :base(Inports,outPorts){} 呼叫基本 nodeModel 建構函式，並將還原序列化的埠傳入。

類別建構函式中牽涉到已序列化至 .dyn 檔案之特定資料初始化而存在的任何特殊邏輯 (例如設定埠註冊、交織策略等)，在此建構函式中都不需要重複，因為這些值可以從 JSON 中讀取。

這是 nodeModels 的 JSON 建構函式與非 JSON 建構函式之間的主要差異。JSON 建構函式是從檔案載入時呼叫，並傳入載入的資料。但是，在 JSON 建構函式中必須複製其他使用者邏輯 (例如，初始化節點的事件處理常式或附加)。

公用性質和序列化

[JsonProperty(PropertyName = "InputValue")]

public DSColor DsColor {...

轉換器：

注意事項 如果您建立自己的 JSON.net 轉換器類別，Dynamo 目前沒有機制可讓您將其插入載入方法和儲存方法，因此即使您使用 [JsonConverter] 屬性標記類別，也可能不會使用它 - 您可以改為直接在 setter 或 getter 中呼叫轉換器。//TODO 需要確認此限制。歡迎提出任何證據。

[JsonProperty("MeasurementType"), JsonConverter(typeof(StringEnumConverter))]

public ConversionMetricUnit SelectedMetricConversion{...

忽略性質

退回/重做

如上所述，過去曾使用 SerializeCore 和 DeserializeCore 方法將節點儲存並載入至 xml .dyn 檔案。此外，這些方法也用來儲存和載入節點狀態以用於退回/重做，**現在也還是！**如果您要為 nodeModel 使用者介面節點實作複雜的退回/重做功能，則需要實作這些方法，並序列化為以這些方法的參數提供的 XML 文件物件。除了複雜的使用者介面節點，這應該是很少見的使用案例。

輸入和輸出埠 API

受 2.0 API 變更影響的 nodeModel 節點中，一個常見情況是節點建構函式中的埠註冊。查看 Dynamo 或 DynamoSamples 儲存庫中的範例，您先前會發現使用 InPortData.Add() 或 OutPortData.Add() 方法。先前在 Dynamo API 中，InPortData 和 OutPortData 公用性質已標記為棄用。在 2.0 中，這些性質已移除。開發人員現在應使用 InPorts.Add() 和 OutPorts.Add() 方法。此外，這兩種 Add() 方法的簽章略有不同：

InPortData.Add(new PortData("Port Name", "Port Description")); //Old version valid in 1.3 but now deprecated

與

InPorts.Add(new PortModel(PortType.Input, this, new PortData("Port Name", "Port Description"))); //Recommended 2.0

範例：

接下來逐步解說將 1.3 使用者介面節點升級到 Dynamo 2.x。

我們只需對此 nodeModel 類別加入一個 jsonConstructor 處理埠的載入，就能在 2.0 中正確載入和儲存。我們只是在基本建構函式上傳入埠，此實作為空的。

注意事項：請勿在 JsonConstructor 中呼叫 RegisterPorts() 或其某些變體 - 這會在您的節點類別上使用輸入和輸出參數屬性來建構新的埠！我們不想要這個結果，因為我們要使用傳入建構函式的已載入埠。

以下是使用者介面節點更複雜的建構函式：

當我們加入 JSON 建構函式以從檔案載入此節點時，必須重新建立其中的某些邏輯，但請注意，我們不包括建立埠、設定交織或設定性質預設值的程式碼，這些程式碼可從檔案載入。

請注意，已序列化為 JSON 的其他公用性質 (例如 ButtonText 和 WindowText) 將不會以明確參數加到建構函式中 - JSON.net 會使用這些性質的 setter 自動設定這些性質。

簡介

本部分包含將圖表、套件和資源庫移轉至 Dynamo 3.x 時，可能會遇到之問題相關資訊。

Dynamo 3.0 為主要版本，某些 API 已變更或移除。其中可能會影響 Dynamo 3.x 開發人員或使用者的最大變更是改為使用 .NET8。

Dotnet/.NET 是執行階段，支援編寫 Dynamo 時使用的 C# 語言。此項目及 Autodesk 生態系統中的其他項目已更新為使用此執行階段的新版本。

您可以在中閱讀更多相關資訊。

套件相容性

在 Dynamo 3.x 中使用 Dynamo 2.x 套件

由於 Dynamo 3.x 現在於 .NET8 執行階段上執行，因此針對 Dynamo 2.x 建置的套件 (使用 .NET48) 不保證可在 Dynamo 3.x 中運作。嘗試在 Dynamo 3.x 中下載從低於 3.0 的 Dynamo 版本發佈的套件時，您會收到警告，指出套件來自舊版 Dynamo。

這不表示套件無法運作。這只是警告您可能有相容性問題。一般而言，建議您檢查是否有專為 Dynamo 3.x 建置的較新版本。

載入套件時，您也可能會在 Dynamo 記錄檔中看到此類警告。如果所有一切都正常運作，即可忽略警告。

在 Dynamo 2.x 中使用 Dynamo 3.x 套件

針對 Dynamo 3.x 建置的套件 (使用.Net8) 在 Dynamo 2.x上很可能無法運作。若使用舊版，下載為更新版 Dynamo 建置的套件時，您也會看到警告。

Dynamo 取決於社群的創意和承諾，Dynamo 團隊鼓勵貢獻者探索各種可能性、測試想法，並參與社群做出回饋。雖然我們非常鼓勵創新，但只有在變更能讓 Dynamo 更容易使用，並且符合本文件中定義的準則時，我們才會合併變更。我們不會合併只有少量改進的變更。

提取請求的期望

Dynamo 團隊希望提取請求遵循一些準則：

• 遵循我們的程式碼撰寫標準和節點命名標準

• 加入新功能時需納入單元測試

• 修正錯誤時，請加入一個能突顯目前行為是如何造成問題的單元測試

• 將討論集中在一個問題。如果出現新主題或相關主題，請建立新問題。

不要這樣做的準則：

• 做出大量超出我們預期的提取請求。請改為提出問題並開始討論，以便我們可以在您投入大量時間之前就方向達成共識。

• 認可不是您撰寫的程式碼。如果您發現一些程式碼很適合加入 Dynamo，請在繼續之前，先提出問題並開始討論。

• 提交會改變授權相關檔案或標頭的 PR。如果您認為這些 PR 有問題，請提出問題，我們很樂於討論。

• 在沒有提出問題並且先跟我們討論的情況下增加 API 內容。

填寫提取請求樣板

提交提取請求時，請使用預設的 PR 樣板。在提交您的 PR 之前，請確定清楚描述目的，並且確認所有聲明都真實：

• 提出此 PR 之後，程式碼庫會處於更佳狀態

• 根據標準製作文件

• 此 PR 所包含的測試階層是適當的

• 向使用者顯示的字串 (如果有) 已擷取到 *.resx 檔案中

• 使用自助服務 CI 通過所有測試

• 使用者介面變更的快照 (如果有)

• 對 API 的變更遵循語意版本管理，並記錄在 API 變更文件中。

Dynamo 團隊將為您的提取請求指定適當的審閱者。

提取請求審閱流程

提交提取請求後，您可能需要在審閱過程中持續參與。請注意以下審閱準則：

• Dynamo 團隊每個月開會一次，檢閱最舊到最新的提取請求。

• 如果審閱過的提取請求需要擁有者進行變更，PR 的擁有者有 30 天時間可以回覆。如果該 PR 在下一次會議之前沒有任何活動，則會被團隊關閉，或視其實用性由團隊中的某人接管。

• 提取請求應使用 Dynamo 的預設 PR 樣板

• 不會審閱未完整填寫 Dynamo PR 樣板且確信所有聲明為真的提取請求。

精選 Dynamo Revit 認可內容

由於市場上有多個版本的 Revit，因此您可能需要精選您的變更來放入特定的 DynamoRevit Release 分支，以便不同版本的 Revit 可以挑選新功能。在審閱過程中，貢獻者要依照 Dynamo 團隊指定，負責精選其審閱過的內容認可到其他 DynamoRevit 分支。

如果您要尋找如何開發 Dynamo 的範例，請查看以下資源：

範例儲存庫

這些範例是 Visual Studio 樣板，您可以用來開始您自己的專案：

• ZeroTouchEssentials： 基本 ZeroTouch 節點的樣板。

  • 傳回多個輸出：程式碼

  • 使用 Dynamo 的原生幾何圖形物件：程式碼

  • 範例性質 (查詢節點)：程式碼

• HelloDynamo： 基本 NodeModel 節點和視圖自訂的樣板。

  • 基本 NodeModel 樣板：HelloNodeModel.cs

    • 定義節點屬性 (輸入/輸出名稱、描述、類型)：程式碼

    • 如果沒有輸入，則傳回空節點：程式碼

    • 建立函數呼叫：程式碼

  • 基本 NodeModel 視圖自訂樣板：HelloGui.cs、HelloGuiNodeView.cs、Slider.xaml、Slider.xaml.cs

    • 警示使用者介面：某個元素需要更新：程式碼

    • 自訂 NodeModel：程式碼

    • 定義滑棒屬性：程式碼

    • 決定滑棒的互動邏輯：程式碼

• DynamoSamples： ZeroTouch、自訂使用者介面、測試和視圖延伸的樣板。

  • 使用者介面範例

    • 建立基本的自訂使用者介面節點：CustomNodeModel.cs

    • 建立下拉式功能表：DropDown.cs

  • 測試

    • 系統測試：HelloDynamoSystemTests.cs

    • ZeroTouch 測試：HelloDynamoZeroTouchTests.cs

  • ZeroTouch 範例：

    • 範例 ZeroTouch 節點，包括實作 IGraphicItem 影響幾何圖形彩現的節點：BasicExample.cs

    • 使用 IRenderPackage 為幾何圖形著色的範例 ZeroTouch 節點：ColorExample.cs

  • 視圖延伸範例：實作 IViewExtension，在按一下無模式視窗的 MenuItem 時，會顯示視窗。

• NodeModelsEssentials： 使用 NodeModel 進行進階 Dynamo 套件開發的樣板。

  • 基本範例：

    • Error

    • MultiOperation

    • Multiply

    • Timeout

  • 幾何圖形範例：

    • CustomPreview

    • SurfaceFrom4Points

    • UVPlanesOnSurface

    • WobblySurface

  • 使用者介面範例：

    • Button

    • ButtonFunction

    • CopyableWatch

    • 滑棒

    • SliderBound

    • State

DynaText： 用於在 Dynamo 中建立文字的 ZeroTouch 資源庫。

案例研究

第三方開發人員為平台做出了巨大且振奮人心的貢獻，其中許多也是開放原始碼。下列專案是使用 Dynamo 可以執行的特殊範例。

Ladybug 是一個載入、分析和修改 EneregyPlus Weather 檔案 (epw) 的 Python 資源庫。

https://github.com/ladybug-tools/ladybug

Honeybee 是一個建立、執行和視覺化日照 (RADIANCE) 和能源分析 (EnergyPlus/OpenStudio) 結果的 Python 資源庫。

https://github.com/ladybug-tools/honeybee

Bumblebee 是一個讓 Excel 和 Dynamo 具有互通性 (GPL) 的外掛程式。

https://github.com/ksobon/Bumblebee

Clockwork是一個 Revit 相關動作以及諸如以下各種其他用途的自訂節點集合，例如清單管理、數學運算、字串運算、幾何運算 (主要是邊界框、網格、平面、點、曲面、UV 和向量) 和面板化。

https://github.com/andydandy74/ClockworkForDynamo

將延伸當作套件

概述

Dynamo 延伸可以部署到 Package Manager，就像一般 Dynamo 節點資源庫一樣。如果安裝的套件包含視圖延伸，在 Dynamo 載入的執行時期會載入該延伸。您可以查看 Dynamo 主控台，以確認延伸已正確載入。

套件結構

延伸套件的結構與一般套件的結構相同，其中包含...

C:\Users\User\AppData\Roaming\Dynamo\Dynamo Core\2.1\packages\Sample View Extension
│   pkg.json
├───bin
│       SampleViewExtension.dll
├───dyf
└───extra
        SampleViewExtension_ViewExtensionDefinition.xml

假設您已建置延伸，您 (至少) 會有一個 .NET 組合和一個資訊清單檔案。組合應包含實作 IViewExtension 或 IExtension 的類別。資訊清單 .XML 檔案會告訴 Dynamo 要實體化哪個類別，以啟動您的延伸。為了讓 Package Manager 能正確找到延伸，資訊清單檔案應準確對應組合位置和命名。

將任何組合檔放在 bin 資料夾中，將資訊清單檔案放在 extra 資料夾中。此資料夾中也可以放置任何其他資產。

範例資訊清單 .XML 檔案：

<ViewExtensionDefinition>
  <AssemblyPath>..\bin\MyViewExtension.dll</AssemblyPath>
  <TypeName>MyViewExtension.MyViewExtension</TypeName>
</ViewExtensionDefinition>

上傳

一旦您有包含上述子目錄的資料夾，即可推送 (上傳) 到 Package Manager。需要注意的一點是，您目前無法從 Dynamo Sandbox 發佈套件。這表示您需要使用 Dynamo Revit。在 Dynamo Revit 內瀏覽到「套件」=>「發佈新套件」。這會提示使用者登入要與套件關聯的 Autodesk 帳戶。

此時，您應該會在一般的發佈套件視窗中，您將在其中輸入有關套件/延伸的所有必要欄位。還有一個非常重要的額外步驟，您必須確保沒有任何組合檔被標記為節點資源庫。您可以在已匯入的檔案 (上面建立的套件資料夾) 上按一下右鍵確認。此時會顯示一個關聯式功能表，讓您勾選 (或取消勾選) 此選項。應取消勾選所有延伸組合。

在公開發佈之前，請您務必先在本端發佈，以確保所有內容都如預期般運作。確認之後，您就可以選取「發佈」讓套件上線。

提取

若要確認套件已成功上傳，您應該能夠透過在發佈步驟指定的名稱和關鍵字搜尋到套件。最後，請務必注意，您需要重新啟動 Dynamo，相同的延伸才能正常運作。這些延伸通常需要指定 Dynamo 啟動時的參數。

發佈套件

套件是儲存節點並與 Dynamo 社群分享節點一個很便利的方式。套件可以包含從在 Dynamo 工作區中建立的自訂節點到 NodeModel 衍生的節點等所有內容。套件的發佈和安裝是透過 Package Manager 進行。除了此頁面，Primer 也提供套件的一般指南。

什麼是 Package Manager？

Dynamo Package Manager 是一種可從 Dynamo 或網頁瀏覽器存取的軟體登錄 (類似於 npm)。Package Manager 包括安裝、發佈、更新和檢視套件。與 npm 一樣，它維護不同版本的套件。它也能協助管理專案的相依性。

在瀏覽器中，搜尋套件並檢視統計資訊：https://dynamopackages.com/

• 在 Dynamo 中，Package Manager 包括安裝、發佈和更新套件。

1. 線上搜尋套件：Packages > Search for a Package...

2. 檢視/編輯安裝的套件：Packages > Manage Packages...

3. 發佈新套件：Packages > Publish New Package...

發佈套件

套件的發佈是透過 Dynamo 內的 Package Manager 進行。建議的程序是在本端發佈、測試套件，然後線上發佈與社群分享。使用 NodeModel 案例研究，我們將逐步完成必要步驟，將 RectangularGrid 節點以套件方式本端發佈，然後線上發佈。

啟動 Dynamo，然後選取「Packages > Publish New Package...」以開啟「Publish a Package」視窗。

1. 選取「Add file...」瀏覽要加入套件的檔案

2. 從 NodeModel 案例研究中選取兩個 .dll 檔案

3. 選取「Ok」

將檔案加入套件內容後，為套件指定名稱、描述和版本。使用 Dynamo 發佈套件會自動建立一個 pkg.json 檔案。

一個準備好要發佈的套件。

1. 提供名稱、描述和版本等必要資訊。

2. 按一下「本端發佈」，然後選取 Dynamo 的套件資料夾：AppData\Roaming\Dynamo\Dynamo Core\1.3\packages 讓節點能在 Core 當中使用。在套件準備好分享之前，請永遠在本端發佈。

發佈套件後，在 Dynamo 資源庫的 CustomNodeModel 品類下就能使用節點。

1. 我們剛剛在 Dynamo 資源庫中建立的套件

套件一旦準備好線上發佈，請開啟 Package Manager，選擇「Publish」，然後選擇「Publish Online」。

1. 若要查看 Dynamo 如何格式化套件，請按一下「CustomNodeModel」右側的三個垂直點，然後選擇「展示根目錄」

2. 在「發佈 Dynamo 套件」視窗中，選取「Publish」，然後選取「Publish Online」。

3. 若要刪除套件，請選取「Delete」。

如何更新套件？

更新套件的程序與發佈類似。開啟 Package Manager，然後對需要更新的套件選取「Publish Version...」，並輸入一個更高的版本。

1. 選取「Publish Version」以使用根目錄中的新檔案更新既有套件，然後選擇在本端還是線上發佈。

Package Manager 網路用戶端

Package Manager 網路用戶端專門用於搜尋和檢視套件資料，例如版本管理和下載統計資訊。

透過此連結 https://dynamopackages.com/ 可以存取 Package Manager 網路用戶端

如果您正在開發要發佈為 Dynamo 套件的組合，可以將專案規劃為群組所有必要資產，並將這些資產放在與套件相容的目錄結構中。這可讓專案以套件方式進行快速測試，並模擬使用者的體驗。

如何直接建置到套件資料夾

有兩種方法可以在 Visual Studio 中建置套件：

• 透過「專案設定」對話方塊，使用 xcopy 或 Python 指令碼複製必要檔案，加入建置後事件

• 在 .csproj 檔案中使用「AfterBuild」建置目標，來建立檔案和目錄複製工作

「AfterBuild」是這些類型作業 (以及本指南中介紹的作業) 的偏好方法，因為它不依賴在建置電腦上可能無法使用的檔案複製。

使用 AfterBuild 方法複製套件檔案

在儲存庫中設定目錄結構，讓原始碼檔案與套件檔案分開。使用 CustomNodeModel 案例研究，將 Visual Studio 專案及所有關聯的檔案放到新的 src 資料夾中。您將會在此資料夾中儲存專案產生的所有套件。資料夾結構現在應如下所示：

CustomNodeModel
> src
  > CustomNodeModel
  > CustomNodeModelFunction
  > packages
  > CustomNodeModel.sln

1. 將專案檔移到新的 src 資料夾

由於原始碼檔案位於不同的資料夾，因此請在 Visual Studio 的 CustomNodeModel.csproj 檔案加入 AfterBuild 目標。這會將必要的檔案複製到新的套件資料夾中。在文字編輯器 (我們使用 Atom) 中開啟 CustomNodeModel.csproj 檔案，在 </Project> 結束標籤之前放置建置目標。此 AfterBuild 目標會將所有 .dll、.pbd、.xml 和 .config 檔案複製到新的 bin 資料夾中，並建立 dyf 和 extra 資料夾。

  <Target Name="AfterBuild">
    <ItemGroup>
      <Dlls Include="$(OutDir)*.dll" />
      <Pdbs Include="$(OutDir)*.pdb" />
      <Xmls Include="$(OutDir)*.xml" />
      <Configs Include="$(OutDir)*.config" />
    </ItemGroup>
    <Copy SourceFiles="@(Dlls)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <Copy SourceFiles="@(Pdbs)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <Copy SourceFiles="@(Xmls)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <Copy SourceFiles="@(Configs)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <MakeDir Directories="$(SolutionDir)..\packages\CustomNodeModel\dyf" />
    <MakeDir Directories="$(SolutionDir)..\packages\CustomNodeModel\extra" />
  </Target>

我們需要確保目標已加到 CustomNodeModel.csproj 檔案 (而不是另一個專案檔) 中，而且專案沒有任何既有的「建置後」設定。

1. 在 </Project> 結束標籤前放置 AfterBuild 目標。

<ItemGroup> 區段中定義了許多變數來表示特定檔案類型。例如，Dll 變數表示輸出目錄中其副檔名為 .dll 的所有檔案。

<ItemGroup>
  <Dlls Include="$(OutDir)*.dll" />
</ItemGroup>

Copy 工作是將所有 .dll 檔案複製到目錄，具體來說是要建置到的套件資料夾。

<Copy SourceFiles="@(Dlls)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />

Dynamo 套件通常會有 dyf 和 extra 資料夾，分別給 Dynamo 自訂節點和其他資產 (例如影像) 使用。若要建立這些資料夾，我們需要使用 MakeDir 工作。如果資料夾不存在，此工作會建立一個。您可以手動將檔案加到此資料夾中。

<MakeDir Directories="$(SolutionDir)..\packages\CustomNodeModel\extra" />

如果您建置專案，現在專案資料夾在先前建立的 src 資料夾旁邊應該會有一個 packages 資料夾。packages 目錄內有一個資料夾，其中包含套件所需的所有內容。我們也需要將 pkg.json 檔案複製到套件資料夾，讓 Dynamo 知道要載入套件。

1. AfterBuild 目標建立的新套件資料夾

2. 專案既有的 src 資料夾

3. 從 AfterBuild 目標建立的 dyf 和 extra 資料夾

4. 手動複製 pkg.json 檔案。

現在，您可以使用 Dynamo 的 Package Manager 發佈套件，或直接將套件複製到 Dynamo 的套件目錄：<user>\AppData\Roaming\Dynamo\1.3\packages。