無論經驗程度為何，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 廣泛涵蓋這些內容，並在指令碼撰寫策略一章中提供撰寫指令碼的秘訣和最佳實踐。

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

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

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

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

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

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

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

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

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

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

Dynamo 中的 Code Block、Python 節點和自訂節點

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

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

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

• 將 Python 資源庫匯入 Dynamo。

• 將 Code Block、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 的權限。

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

Dynamo UI 在效能方面的考慮事項

在撰寫本文時，Dynamo 主要使用 WPF (Windows Presentation Foundation) 來呈現其 UI。WPF 是一個複雜而強大的 XAML/繫結型系統。由於 Dynamo 具有複雜的 UI，因此很容易發生 UI 當機、記憶體洩漏，或者以降低效能的方式將圖表執行與 UI 更新包裹在一起。

請參閱 Dynamo 效能考慮事項 Wiki 頁面，該頁面將協助您避免發生一些變更 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 節點開發及需要注意的問題。

在開始開發之前，為新專案建立堅實的基礎非常重要。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# 檔案並開啟。我們應為其指定適當的名稱、設定工作區，然後以此乘法方法更換預設程式碼。

 namespace MyCustomNode
 {
     public class SampleFunctions
     {
         public static double MultiplyByTwo(double inputNumber)
         {
             return inputNumber * 2.0;
         }
     }
 }

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 類別中建立一個空的私用建構函式來避免發生這個情況。

namespace MyCustomNode
{
    public class SampleFunctions
    {
        //The empty private constructor.
        //This will be not imported into Dynamo.
        private SampleFunctions() { }

        //The public multiplication method. 
        //This will be imported into Dynamo.
        public static double MultiplyByTwo(double inputNumber)
        {
            return inputNumber * 2.0;
        }
    }
}

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

加入 Dynamo NuGet 套件參考

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

• ZeroTouchLibrary - 用於為 Dynamo 建置 zero touch 節點資源庫的套件，包含以下資源庫：DynamoUnits.dll、ProtoGeometry.dll

• WpfUILibrary - 用於為 Dynamo 建置具有 WPF 自訂使用者介面之節點資源庫的套件，包含以下資源庫：DynamoCoreWpf.dll、CoreNodeModels.dll、CoreNodeModelWpf.dll

• DynamoServices - 適用於 Dynamo 的 DynamoServices 資源庫

• Core - Dynamo 的單位與系統測試基礎架構，包含以下資源庫：DSIronPython.dll、DynamoApplications.dll、DynamoCore.dll、DynamoInstallDetective.dll、DynamoUtilities.dll、ProtoCore.dll、VMDataBridge.dll

• Tests - Dynamo 的單位與系統測試基礎架構，包含以下資源庫：DynamoCoreTests.dll、SystemTestServices.dll、TestServices.dll

• DynamoCoreNodes - 用於為 Dynamo 建置核心節點的套件，包含以下資源庫：Analysis.dll、GeometryColor.dll、DSCoreNodes.dll

若要在 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，因此，我們已經有堅實的基礎可以讓概念繼續發揮。這只是開始，請繼續跟進，進一步瞭解如何建立自訂節點。

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

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

若要開始，請從 https://github.com/DynamoDS/ZeroTouchEssentials 下載 ZeroTouchEssentials 專案

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

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

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

程式碼範例是從 ZeroTouchEssentials.cs 提取，通常與其相符。為了簡潔已移除 XML 文件，每個程式碼範例都會建立其上方影像中的節點。

預設輸入值

Dynamo 支援定義節點上輸入埠的預設值。如果埠沒有連接，則會對節點提供這些預設值。預設值使用在《C# 程式設計手冊》中指定可選引數的 C# 機制表示。預設值以下列方式指定：

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

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        // Set the method parameter to a default value
        public static double MultiplyByTwo(double inputNumber = 2.0) 
        {
            return 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>

using System.Collections.Generic;
using Autodesk.DesignScript.Runtime;

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        [MultiReturn(new[] { "add", "mult" })]
        public static Dictionary<string, object> ReturnMultiExample(double a, double b)
        {
            return new Dictionary<string, object>

                { "add", (a + b) },
                { "mult", (a * b) }
            };
        }
    }
}

請參閱 ZeroTouchEssentials.cs 中的此程式碼範例

傳回多個輸出的節點。

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

文件、工具提示和搜尋

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

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

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

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

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

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

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

標籤類型如下：

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

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

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

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

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

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

using Autodesk.DesignScript.Geometry;

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        /// <summary>
        /// This method demonstrates how to use a native geometry object from Dynamo
        /// in a custom method
        /// </summary>
        /// <param name="curve">Input Curve. This can be of any type deriving from Curve, such as NurbsCurve, Arc, Circle, etc</param>
        /// <returns>The twice the length of the Curve </returns>
        /// <search>example,curve</search>
        public static double DoubleLength(Curve curve)
        {
            return curve.Length * 2.0;
        }
    }
}

請參閱 ZeroTouchEssentials.cs 中的此程式碼範例

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

1. 節點摘要

2. 輸入描述

3. 輸出描述

Dynamo 節點描述最佳實踐

節點描述簡短描述節點的功能和輸出。在 Dynamo 中，節點描述會出現在兩個位置：

• 在節點工具提示中

• 在文件瀏覽器中

請按照這些準則，在撰寫或更新節點描述時，可確保一致性並幫助節省時間。

概述

描述應該是一到兩句話。如果需要更多資訊，請將其放在文件瀏覽器的「深入資訊」下。

句子大小寫 (將句子的第一個單字和任何專有名詞大寫)。句尾不用句點。

語言應盡可清楚、簡單。在第一次提到首字母縮寫字時加以定義，除非連非專業使用者也知道這些縮寫字。

一律以清楚明瞭為優先考量，即使可能偏離這些準則亦同。

指南

Dynamo 節點的警告和錯誤

節點的警告和錯誤會提醒使用者圖表有問題。通知使用者問題的方式，是在節點上方顯示圖示和展開的文字標示圈，來干擾正常的圖表運作。節點錯誤和警告的嚴重性可能有所不同：某些圖表還是能在有警告的情況下充分執行，但某些圖表卻可能無法獲得預期的結果。無論如何，節點的錯誤和警告都是重要的工具，可讓使用者隨時掌握圖表的問題。

如需在寫入或更新節點警告和錯誤訊息時確保一致性並協助節省時間的準則，請參閱內容模式：節點的警告與錯誤 Wiki 頁面。

物件

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

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

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

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

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        private double _a;
        private double _b;

        // Make the constructor internal
        internal ZeroTouchEssentials(double a, double b)
        {
            _a = a;
            _b = b;
        }

        // The static method that Dynamo will convert into a Create node
        public static ZeroTouchEssentials ByTwoDoubles(double a, double b)
        {
            return new ZeroTouchEssentials(a, b);
        }
    }
}

請參閱 ZeroTouchEssentials.cs 中的此程式碼範例

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

使用 Dynamo 幾何圖形類型

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

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

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

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

using Autodesk.DesignScript.Geometry;

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        // "Autodesk.DesignScript.Geometry.Curve" is specifying the type of geometry input, 
        // just as you would specify a double, string, or integer 
        public static double DoubleLength(Autodesk.DesignScript.Geometry.Curve curve)
        {
            return curve.Length * 2.0;
        }
    }
}

請參閱 ZeroTouchEssentials.cs 中的此程式碼範例

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

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

Dispose/using 陳述式

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

• 使用 using 陳述式：

  Copy

  using (Point p1 = Point.ByCoordinates(0, 0, 0))
  {
    using (Point p2 = Point.ByCoordinates(10, 10, 0))
    {
        return Line.ByStartPointEndPoint(p1, p2);
    }
  }

  此處說明 using 陳述式

  請參閱 Dynamo 幾何圖形穩定性的改進，以進一步瞭解 Dynamo 2.5 中引入的新穩定性功能

• 使用手動的 Dispose 呼叫：

  Copy

  Point p1 = Point.ByCoordinates(0, 0, 0);
  Point p2 = Point.ByCoordinates(10, 10, 0);
  Line l = Line.ByStartPointEndPoint(p1, p2);
  p1.Dispose();
  p2.Dispose();
  return l;

移轉

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

• 使用以下格式，在與 .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。

<?xml version="1.0"?>
<migrations>
  <priorNameHint>
    <oldName>Autodesk.DesignScript.Geometry.Geometry.GetClosestPoint</oldName>
    <newName>Autodesk.DesignScript.Geometry.Geometry.ClosestPointTo</newName>
  </priorNameHint>
</migrations>

請參閱 ProtoGeometry.Migrations.xml 中的此程式碼範例

泛型

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

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

public class SomeGenericClass<T>
{
    public SomeGenericClass()
    {
        Console.WriteLine(typeof(T).ToString());
    }  
}

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

public class SomeWrapper
{
    public object wrapped;
    public SomeWrapper(SomeGenericClass<double> someConstrainedType)
    {
        Console.WriteLine(this.wrapped.GetType().ToString());
    }
}

簡介

本部分包含將圖表、套件和資源庫移轉至 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 建置的套件時，您也會看到警告。

我們已經具備 ZeroTouch 的基礎知識，本節將深入探討自訂 Dynamo 節點來增強功能和使用者體驗的優點。透過增加警告訊息、資訊訊息和自訂圖示等功能，您可以建立更直覺、資訊量更大、視覺上更吸引人的節點。這些自訂功能不僅能協助使用者瞭解潛在的問題或最佳化其工作流程，還能讓您的節點脫穎而出，成為專業且容易使用的工具。

自訂節點是一種絕佳方式，能確保您的解決方案清晰、可靠，專門為滿足特定專案需求而量身打造。

使用 OnLogWarningMessage 產生自訂警告訊息

在 Dynamo 中，OnLogWarningMessage 方法提供一種將警告訊息直接記錄到 Dynamo 主控台的方法。這是一項強大的功能，尤其是對於 Zero Touch 節點，因為它允許開發人員在輸入或參數出現可能導致非預期行為的問題時提醒使用者。本指南將教您如何在任何 Zero Touch 節點中實施 OnLogWarningMessage。

OnLogWarningMessage 的實施步驟

步驟 1：匯入所需的名稱空間

OnLogWarningMessage 屬於 DynamoServices 名稱空間，因此請先將其加入專案檔。

步驟 2：找出何時記錄警告

在加入警告訊息之前，請考慮方法中的邏輯：

• 哪些條件可能會導致不正確或意外的結果？

• 方法是否需要特定的輸入值或參數才能正確運作？

要檢查的條件範例：

• 超出範圍值 (例如 if (inputValue < 0))。

• 空值或空集合 (例如 if (list == null || list.Count == 0))。

• 資料類型不相符 (例如，檔案類型不受支援時)。

步驟 3：使用 OnLogWarningMessage 記錄警告

在偵測到可能導致問題的位置進行 OnLogWarningMessage 呼叫。當滿足條件時，記錄一則警告訊息，向使用者提供明確的指導意見。

OnLogWarningMessage 的語法

OnLogWarningMessage 的範例實施

為了實際示範 OnLogWarningMessage，下面是您在建置 Zero Touch 節點時可能會遇到的不同情境。

範例 1：驗證數字輸入

在此範例中，我們將以上一個「Zero-Touch 案例研究 - 網格節點」中建立的自訂節點為基礎；一個名為 RectangularGrid 的方法會根據 xCount 和 yCount 輸入產生矩形格線。我們將逐步測試某個輸入是否無效，然後使用 OnLogWarningMessage 記錄警告並停止處理。

使用 OnLogWarningMessage 進行輸入驗證

根據 xCount 和 yCount 產生格線時。在繼續操作之前，您希望確保兩個值都是正整數。

在本範例中：

• 條件：如果 xCount 或 yCount 小於或等於零。

• 訊息："Grid count values must be positive integers."

如果使用者輸入零或負值，將在 Dynamo 中顯示警告，以協助他們瞭解預期的輸入。

現在我們知道運作方式，可以將其實施到 Grids 範例節點中：

範例 2：檢查空值或空集合

如果您的方法需要一個點清單，但使用者傳入空白或空值清單，您可以使用 OnLogWarningMessage 通知他們有這個問題。

在本範例中：

• 條件：如果 points 清單為空值或包含少於三個點。

• 訊息："Point list cannot be null or have fewer than three points."

這會警告使用者，他們需要傳入至少包含三個點的有效清單才能形成一個多邊形。

範例 3：驗證檔案類型相容性

如果是處理檔案路徑的節點，您可能希望確保只允許某些檔案類型。如果偵測到不支援的檔案類型，則記錄警告。

在本範例中：

• 條件：如果檔案路徑不是以「.csv」結尾。

• 訊息："Only CSV files are supported."

這會警告使用者，確保他們傳入的是 CSV 檔，有助於防止出現與檔案格式不相容相關的問題。

使用 OnLogInfoMessage 新增資訊訊息

在 Dynamo 中，DynamoServices 名稱空間中的 OnLogInfoMessage 可讓開發人員將資訊訊息直接記錄到 Dynamo 的主控台。這有助於確認運算成功、傳達進度或提供有關節點動作的其他見解。本指南將教您如何在任何 Zero Touch 節點中加入 OnLogInfoMessage，以增強回饋並改善使用者體驗。

OnLogInfoMessage 的實施步驟

步驟 1：匯入所需的名稱空間

OnLogInfoMessage 屬於 DynamoServices 名稱空間，因此請先將其加入專案檔。

步驟 2：找出何時記錄資訊

在加入資訊訊息之前，請考慮方法的用途：

• 動作完成後，要確認哪些資訊有用？

• 方法中是否有使用者可能想要瞭解的關鍵步驟或里程碑？

有用的確認範例：

• 完成訊息 (例如，當網格或模型完全建立好時)。

• 已處理資料的詳細資料 (例如，「已成功處理 10 個項目」)。

• 執行摘要 (例如，過程中使用的參數)。

步驟 3：使用 OnLogInfoMessage 記錄資訊訊息

在方法中有意義的點進行 OnLogInfoMessage 呼叫。發生關鍵步驟或完成動作時，記錄一則資訊訊息，向使用者更新發生的情況。

OnLogInfoMessage 的語法

OnLogInfoMessage 的範例實施

以下是幾個不同情境，示範如何在 Zero Touch 節點中使用 OnLogInfoMessage。

範例 1：驗證數字輸入

在此範例中，我們將以上一個「Zero-Touch 案例研究 - 網格節點」中建立的自訂節點為基礎；一個名為 RectangularGrid 的方法會根據 xCount 和 yCount 輸入產生矩形格線。我們將逐步測試某個輸入是否無效，然後在節點完成其執行時使用 OnLogInfoMessage 提供資訊。

使用 OnLogInfoMessage 進行輸入驗證

根據 xCount 和 yCount 產生格線時。產生網格後，您希望透過記錄網格尺寸的資訊訊息來確認其建立完成。

在本範例中：

• 條件：網格建立程序已經完成。

• 訊息："Successfully created a grid with dimensions {xCount}x{yCount}."

此訊息將通知使用者，網格已依指定方式建立，協助他們確認節點如預期般運作。

現在我們知道運作方式，可以將其實施到 Grids 範例節點中：

範例 2：提供資料計數資訊

如果要建立處理點清單的節點，可能需要記錄成功處理的點數。這對於大型資料集非常有用。

在本範例中：

• 條件：迴圈完成後，顯示已處理項目的計數。

• 訊息："6 points were processed successfully."

此訊息將協助使用者瞭解處理結果，並確認所有點都已處理。

範例 3：彙總使用的參數

在某些情況下，確認節點用於完成動作的輸入參數會很有用。例如，如果您的節點將資料匯出到某個檔案，則記錄檔名和路徑可以讓使用者放心使用了正確的檔案。

在本範例中：

• 條件：匯出程序成功完成。

• 訊息："Data exported successfully to {filePath}."

此訊息向使用者確認匯出已完成，並顯示確切的檔案路徑，可協助避免檔案位置混淆。

建立自訂文件並新增到節點

自訂節點文件

從歷史上看，套件作者如何在 Dynamo 中為其節點提供文件一直存在限制。自訂節點的作者受到限制，只允許在節點的工具提示中顯示簡短描述，或只允許在套件中加入大量註解的範例圖表。

一種新方式

Dynamo 現在為套件作者提供一套改進的系統，讓您可以為自訂節點提供更好、更清楚的文件。這種新方法利用友善的 Markdown 語言進行文字撰寫，並使用「文件瀏覽器」視圖延伸功能在 Dynamo 中顯示 Markdown。使用 Markdown 為套件作者在記錄自訂節點時提供多種新的可能性。

什麼是 Markdown？

Markdown 是一種輕量標記語言，可用於格式化純文字文件。Markdown 自 2004 年創造出來後，其受歡迎程度日益增加，現在已經是世界上其中一種最受歡迎的標記語言。

開始使用 Markdown

Markdown 能做什麼？

在節點中新增延伸文件

在節點中新增文件非常容易。您可以將文件加到所有類型的自訂節點，包括：

• 現成的 Dynamo 節點

• 自訂節點 (.dyf) - 現成和/或其他套件節點的集合。

• 自訂 C# 套件節點 (也稱為 Zerotouch。這些自訂節點看起來像現成節點)

• NodeModel 節點 (包含特殊使用者介面功能 (如下拉式清單或選取按鈕) 的節點)

• 具有自訂使用者介面的 NodeModel 節點 (包含獨特的使用者介面功能 (如節點上有圖形) 的節點)

請按照以下幾個步驟，讓 Markdown 檔案顯示在 Dynamo 內。

在 Dynamo 中開啟文件檔案

Dynamo 使用「文件瀏覽器」視圖延伸來顯示節點文件。若要開啟節點文件，請在節點上按一下右鍵，然後選取「說明」。這會開啟「文件瀏覽器」，並顯示與該節點關聯的 Markdown (如果有)。

「文件瀏覽器」中顯示的文件由兩個部分組成。第一個是「Node Info」部分，這是由節點中提取的資訊自動產生而成，例如輸入/輸出、節點品類、節點名稱/名稱空間和節點簡短描述。第二部分展示自訂節點文件，這是用來記錄節點的 Markdown 檔案。

套件文件資料夾

若要將文件檔案加到 Dynamo 中的節點，請在套件目錄中建立一個名為 /doc 的新資料夾。載入套件後，Dynamo 會掃描此目錄，並取得當中所有的 文件 Markdown 檔案。

命名 Markdown 檔案

為了確保 Dynamo 知道當要求時要為特定節點開啟哪個檔案，Markdown 檔案的命名必須依照特定格式。您的 Markdown 檔案應該根據其記錄的節點名稱空間來命名。如果您不確定節點的名稱空間為何，請查看「Node Info」部分，當您在節點上按「Help」時，在節點名稱下會看到所選節點的完整名稱空間。

此名稱空間應該是該特定節點的 Markdown 檔案名稱。例如，上圖中 CustomNodeExample 的名稱空間是 TestPackage.TestCategory.CustomNodeExample，因此此節點的 Markdown 檔案應命名為 TestPackage.TestCategory.CustomNodeExample.md

在節點多載 (節點的名稱相同但輸入不同) 的特殊情況下，您必須在節點名稱空間之後的 () 加上輸入名稱。例如，內建節點 Geometry.Translate 有多個多載。在此案例中，我們會將以下節點的 Markdown 檔案命名為：Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction).md Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction,distance).md

在 Dynamo 中開啟時修改 Markdown 檔案

為了方便修改文件檔案，「文件瀏覽器」對開啟的文件檔案實作一個「檔案監看器」。您可以對 Markdown 檔案進行變更，在 Dynamo 中會立即看到修改的內容。

在 Dynamo 開啟時，也可以新增文件檔案。只要在 /doc 資料夾中新增一個 Markdown 檔案，其名稱對應到其記錄的節點即可。

將自訂圖示加入 Zero Touch 節點

概述

Dynamo 中 Zero Touch 節點的自訂圖示，可讓您的節點在視覺上與眾不同，也更容易在資源庫中辨識。透過增加自訂圖示，您可以讓節點脫穎而出，讓使用者在清單中快速識別。

本指南將向您展示如何將圖示加入 Zero Touch 節點。

新增自訂節點圖示的步驟

步驟 1：設定專案

首先，為您的 Zero Touch 節點建立一個 Visual Studio 類別程式庫 (.NET Framework) 專案。如果您還沒有專案，請參閱入門一節，以取得建立專案的逐步指示。

請確保您至少有一個功能性的 Zero Touch 節點，因為只能將圖示加到既有節點中。如需指導意見，請參閱 Zero Touch 案例研究 - 網格節點。

步驟 2：建立圖示影像

建立自訂圖示：

1. 設計圖示：使用影像編輯器為節點建立簡單清晰的圖示。

2. 影像規格：

   • 小圖示：32x32 像素 (用於資源庫的側邊欄和節點本身)。

   • 大圖示：128x128 像素 (將游標懸停在資源庫中的節點上時用於節點性質)。

3. 檔案命名慣例：

   • 檔名必須符合以下格式，才能將其與正確的節點關聯：

     • <ProjectName>.<ClassName>.<MethodName>.Small.png (用於小圖示)。

     • <ProjectName>.<ClassName>.<MethodName>.Large.png (用於大圖示)。

範例：如果您的專案是 ZeroTouchNodeIcons，您的類別是 Grids，且您的方法是 RectangularGrid，則檔案將命名為：

• ZeroTouchNodeIcons.Grids.RectangularGrid.Small.png

• ZeroTouchNodeIcons.Grids.RectangularGrid.Large.png

秘訣：對所有圖示使用一致的設計主題，可賦予專業的觀感。

步驟 3：將資源檔加到專案中

若要將圖示嵌入 .dll 中，請建立一個資源檔：

1. 新增資源檔：

• 在**「方案總管」**中以右鍵按一下您的專案。

• 移至**「新增」>「新項目」，然後選取「資源檔」**。

• 將檔案命名為 <ProjectName>Images.resx。例如 ZeroTouchNodeIconsImages.resx。

1. 清除自訂工具屬性：

   • 在**「方案總管」**中選取資源檔。

   • 在**「屬性」**面板中，透過移除 ResXFileCodeGenerator 值來清除「Custom Tool」欄位。

注意：如果沒有清除「自訂工具」欄位，會導致 Visual Studio 將資源名稱中的句點轉換為底線。請在建置之前，確認您的資源名稱是以句點 (而不是底線) 分隔類別名稱。

步驟 4：將影像新增為資源

1. 使用**「受控資源編輯器 (舊版)」**開啟資源檔：

   • 如果使用 Visual Studio 17.11 或更高版本，請以右鍵按一下資源檔，選擇**「開啟方式」，然後選取「受控資源編輯器 (舊版)」**。

   • 如果使用 17.11 之前的 Visual Studio 版本，請按兩下資源檔以使用「資源編輯器」開啟 (在您的 Visual Studio 版本中，此編輯器尚未成為舊版)。

1. 新增您的影像：

   • 將影像檔拖放到編輯器中，或使用**「新增現有檔案」**選項。

1. 更新持續性：

   • 在「資源編輯器」中選取影像 (如果在「方案總管」中選取影像，此動作將沒有作用)，將**「屬性」面板中的「持續性」**屬性變更為「Embedded in .resx」。這可確保影像包含在 .dll 中。

步驟 5：將專案轉換為 SDK 型

如果您的專案還不是 SDK 型 (嵌入資源需要)，請加以轉換：

1. 從 Visual Studio 的**「延伸模組」>「管理延伸模組」**功能表安裝 .NET Upgrade Assistant 延伸模組。

1. 在**「方案總管」中的專案上按一下右鍵，然後選取「升級」>「將專案轉換為 SDK 型」**。

1. 等待轉換完成。

步驟 6：新增要嵌入資源的建置後指令碼

1. 卸載專案：

   • 在**「方案總管」中的專案上按一下右鍵，然後選取「卸載專案」**。

1. 編輯 .csproj 檔案：

   • 在 </ItemGroup> 和 </Project> 之間加入以下 <Target> 元素：

1. 將 ZeroTouchNodeIcons 的所有例證取代為您的專案名稱。

2. 重新載入專案：

   • 在已卸載的專案上按一下右鍵，然後選取**「重新載入專案」**。

步驟 7：建置 .dll 並將其載入到 Dynamo

1. 建置專案：

   • 新增建置後指令碼後，在 Visual Studio 中建置專案。

1. 檢查輸出檔案：

   • 確保您的 .dll 和 .customization.dll 位於 bin 資料夾中。

2. 將 .dll 加入 Dynamo：

   • 在 Dynamo 中，使用「匯入資源庫」按鈕將 .dll 匯入到 Dynamo。

1. 您的自訂節點現在應該會與其各自的圖示一起顯示。

在 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...」

多個輸出

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

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

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

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

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

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

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

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

一些有關互通性類型的一般資訊

在 C# 中使用 COM 類型的標準方法，是使用套件來參考和遞送主要的互通性組合 (基本上是 API 的一個大型集合)。

另一種方法是將 PIA (主要互通性組合) 嵌入受管的組合中。這基本上只是納入受管組合實際使用的類型和成員。但是，此方法還存在一些其他問題，例如類型對等項。

這篇文章仔細描述了這個問題：

Dynamo 如何管理類型對等項

如何避免嵌入式互通性類型之間發生衝突

您可以按照以下範例：

簡介：

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 節點無法套用這些屬性。您可能會發現節點傳回單一字典輸出，而不是多個埠。

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

• 如果還原序列化因某些原因失敗，則可能會發生此情況。最好只序列化您需要的性質。我們可以對您不需要載入或儲存的複雜性質使用 [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 自動設定這些性質。

以 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 建置套件。

  -o, -O, --OpenFilePath        Instruct Dynamo to open a command file and run the commands it contains at 
                                this path, this option is only supported when run from DynamoSandbox

  -c, -C, --CommandFilePath     Instruct Dynamo to open a command file and run the commands it contains at 
                                this path, this option is only supported when run from DynamoSandbox                      

  -v, -V, --Verbose             Instruct Dynamo to output all evaluations it performs to an XML file at this path

  -g, -G, --Geometry            Instruct Dynamo to output geometry from all evaluations to a JSON file at this path

  -h, -H, --help                Get some help

  -i, -I, --Import              Instruct Dynamo to import an assembly as a node library. This argument should be a 
                                file path to a single.dll - if you wish to import multiple dlls - list the dlls 
                                separated by a space: -i 'assembly1.dll' 'assembly2.dll'

  --GeometryPath                Relative or absolute path to a directory containing ASM. When supplied, instead of 
                                searching the hard disk for ASM, it will be loaded directly from this path

  -k, -K, --KeepAlive           Keepalive mode, leave the Dynamo process running until a loaded extension shuts it 
                                down

  --HostName                    Identify Dynamo variation associated with the host

  -s, -S, --SessionId           Identify Dynamo host analytics session id

  -p, -P, --ParentId            Identify Dynamo host analytics parent id

  -x, -X, --ConvertFile         When used in combination with the 'O' flag, opens a .dyn file from the specified 
                                path and converts it to .json. The file will have the .json extension and be 
                                located in the same directory as the original file

  -n, -N, --NoConsole           Don't rely on the console window to interact with CLI in Keepalive mode

  -u, -U  --UserData            Specify user data folder to be used by PathResolver with CLI

  --CommonData                  Specify common data folder to be used by PathResolver with CLI

  --DisableAnalytics            Disables analytics in Dynamo for the process lifetime

  --CERLocation                 Specify the crash error report tool located on the disk

  --ServiceMode                 Specify the service mode startup

原因

出於各種原因，您會透過指令行控制 Dynamo，這些原因可能包括：

• 自動執行多個 Dynamo

• 測試 Dynamo 圖表 (使用 DynamoSandbox 時也要查看 -c)

• 以特定順序執行一系列 Dynamo 圖表

• 撰寫執行多個指令行執行的批次檔

• 撰寫另一個程式來控制和自動執行 Dynamo 圖表，並且運用這些計算結果做一些特別的事情

內容

指令行介面 (DynamoCLI) 是對 DynamoSandbox 的補充內容。它是一個 DOS/終端機指令行公用程式，設計來提供指令行引數方便執行 Dynamo。在一開始的實作中，它無法獨立執行，必須從 Dynamo 二進位檔所在的資料夾執行，因為它依賴與沙箱相同的核心 DLL。無法與其他 Dynamo 建置版本互通。

有四種方式可以執行 CLI：從 DOS 命令提示執行、從 DOS 批次檔執行，以及以 Windows 桌面捷徑執行 (其路徑修改為包括指定的指令行旗標)。DOS 檔規格可以是完整的或相對的，也支援對映的磁碟機和 URL 語法。它也可以使用 Mono 建置，並在 Linux 或 Mac 上從終端機執行。

公用程式支援 Dynamo 套件，但是您無法載入自訂節點 (dyf)，只能載入獨立圖表 (dyn)。

在初步測試中，CLI 公用程式支援本土化的 Windows 版本，而且可以使用大寫的 Ascii 字元指定 filespec 引數。

可透過 DynamoCLI.exe 應用程式存取 CLI。此應用程式允許使用者或其他應用程式使用指令字串叫用 DynamoCLI.exe 與 Dynamo 演算模型互動。看起來可能會像下面這樣：

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn"

此指令會告訴 Dynamo 開啟 C:\someReallyCoolDynamoFile.Dyn 的指定檔案，而不繪製任何使用者介面，然後執行它。圖表執行完成後，Dynamo 就結束。

2.1 版中的新功能：DynamoWPFCLI.exe應用程式。此應用程式透過加入「幾何圖形 (-g)」選項支援 DynamoCLI.exe 應用程式支援的所有功能。DynamoWPFCLI.exe 應用程式僅限 Windows。

重要注意事項

• 與 DynamoCLI 互動的首選方式是透過指令提示介面。

• 目前，您需要從安裝位置的 [Dynamo 版本] 資料夾內執行 DynamoCLI。CLI 需要存取與 Dynamo 相同的 .dll，因此不應移動。

• 您應該能夠執行目前在 Dynamo 中開啟的圖表，但這可能會導致意外的副作用。

• 所有檔案路徑都完全遵守 DOS 規範，因此相對路徑和完整路徑應該都能運作，但請務必將路徑放在引號 "C:path\to\file.dyn" 中

• DynamoCLI 是新功能，目前不斷在變化：目前 CLI 只會載入一小組標準 Dynamo 資源庫，如果圖表未正確執行，請注意這一點。此處指定這些資源庫

• 目前不提供 std 輸出，如果未遇到錯誤，CLI 將在執行完成後直接結束。

方法

-o：您可以用無頭模式開啟 Dynamo 指向將執行圖表的 .dyn。

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn"

-v：可在 Dynamo 以無頭模式執行 (當我們使用 -o 打開檔案) 時使用，此旗標會反覆運算圖表中的所有節點，並將輸出值傾印到簡單的 XML 檔中。由於 --ServiceMode 旗標可能會強制 Dynamo 執行多個圖表演算，因此輸出檔案會保留發生的每個演算值。

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -p "C:\aFileWithPresetsInIt.dyn" --ServiceMode "all" -v "C:\output.xml"

XML 輸出檔的格式如下：

    <evaluations>
        <evaluation0>
            <Node guid="e2a6a828-19cb-40ab-b36c-cde2ebab1ed3">
                <output0 value="str" />
            </Node>
            <Node guid="67139026-e3a5-445c-8ba5-8a28be5d1be0">
                <output0 value="C:\Users\Dale\state1.txt" />
            </Node>
            <Node guid="579ebcb8-dc60-4faa-8fd0-cb361443ed94">
                <output0 value="null" />
            </Node>
        </evaluation0>
        <evaluation1>
            <Node guid="e2a6a828-19cb-40ab-b36c-cde2ebab1ed3">
                <output0 value="str" />
            </Node>
            <Node guid="67139026-e3a5-445c-8ba5-8a28be5d1be0">
                <output0 value="C:\Users\Dale\state2.txt" />
            </Node>
            <Node guid="579ebcb8-dc60-4faa-8fd0-cb361443ed94">
                <output0 value="null" />
            </Node>
        </evaluation1>
    </evaluations>

-g：可在 Dynamo 以無頭模式執行 (當我們使用 -o 開啟檔案) 時使用，此旗標會產生圖表，然後將產生的幾何圖形傾印到 JSON 檔中。

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoWPFCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -g "C:\geometry.json"

JSON 幾何圖形檔案的格式如下：

 TBD - Work in progress

-h：使用此旗標可取得可能選項的清單

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -h

-i 旗標可使用多次來匯入多個您嘗試開啟的圖表需要執行的組合。

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -i"a.dll" -i"aSecond.dll"

-l 旗標可用來在不同地區設定下執行 Dynamo。但通常而言，地區設定不會影響圖表結果

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -l "de-DE"

--GeometryPath 旗標可用來將 DynamoSandbox 或 CLI 指向一組特定的 ASM 二進位檔案 - 使用方式如下

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoSandbox.exe --GeometryPath "\pathToGeometryBinaries\"

或者

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoSandbox.exe --GeometryPath "\pathToGeometryBinaries\"

-k 旗標可用來維持 Dynamo 程序執行，直到載入的延伸將其關閉。

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -k

--HostName 旗標可用來識別與主體關聯的 Dynamo 變體。

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe --HostName "DynamoFormIt"

或者

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoSandbox.exe --HostName "DynamoFormIt"

-s 旗標可用來識別 Dynamo 主體分析階段作業 ID

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -s [HostSessionId]

-p 旗標可用來識別 Dynamo 主體分析父系 ID

    C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -p "RVT&2022&MUI64&22.0.2.392"

要讓套件達到想要的配置，取決於您要納入套件中的節點類型。NodeModel 衍生的節點、ZeroTouch 節點和自訂節點，定義分類方式的程序都略有不同。您可以在同一個套件中混合使用這些節點類型，但需要結合使用下面概述的策略。

NodeModel

NodeModel 資源庫預設會根據類別結構進行整理。

namespace SampleLibraryUI.Examples

// Class Attribute
[NodeName("MyNodeModel")]
public class MyNewNodeModel : NodeModel

// or

// Constructor
public ButtonCustomNodeModel()
{
    this.Name = "MyNodeModel";
}

節點將位於附加元件的以下位置：

SampleLibraryUI/Examples/MyNodeModel

您也可以在類別上或在建構函式中使用 NodeCategory 屬性來取代該品類，如下所示。

// Class Attribute
[NodeCategory("NewSampleLibraryUI.Examples")]

// or

// Constructor
public ButtonCustomNodeModel()
{
    this.Category = "NewSampleLibraryUI.Examples";
}

節點現在將位於附加元件中的以下位置：

NewSampleLibraryUI/Examples/MyNodeModel

ZeroTouch

ZeroTouch 資源庫預設也會根據類別結構進行整理。

namespace MyZTLibrary

public class Utilities
{
    public double doubleValue(double num)
    {
        return num * 2;
    }
}

節點將位於附加元件的以下位置：

MyZTLibrary/Utilities/doubleValue

您也可以使用 Dynamo 自訂 XML 檔案取代類別結構位置。

• XML 檔案必須相應地命名，並放入套件的 extra 資料夾中

  • PackageName_DynamoCustomization.xml

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MeshToolkit</name>
    </assembly>
    <namespaces>
        <!--Remap Namespaces-->
        <namespace name="Autodesk.Dynamo.MeshToolkit">
            <category>MeshToolkit</category>
        </namespace>
        <namespace name="Autodesk.Dynamo.MeshToolkit.Display">
                <category>Display</category>
        </namespace>
    </namespaces>
    <classes>
        <!--Remap Class Names-->
        <class name="Autodesk.Dynamo.MeshToolkit.Display.MeshDisplay" shortname="MeshDisplay"/>
        <class name="Autodesk.Dynamo.MeshToolkit.Mesh" shortname="Mesh"/>
    </classes>
</doc>

自訂節點

自訂節點是根據建立節點期間 (使用新的「自訂節點」對話方塊) 中指定的 Category Name 來進行整理。

警告！ 在節點名稱或品類中使用點符號，將會產生額外的巢狀子品類。. 將用作分隔符號來決定其他階層。這是 Dynamo 2.0 資源庫中的新行為。

之後可在 .dyf 檔案 (XML 或 JSON) 中更新品類名稱

{
  "Uuid": "85066088-1616-40b1-96e1-c33e685c6948",
  "IsCustomNode": true,
  "Category": "MyCustomNodes.Utilities.Actions",
  "Description": "This is an example custom nodes.",
  "Name": "doubleValue",
  "ElementResolver": {
    "ResolutionMap": {}
  },...

<Workspace Version="1.3.0.0000" X="100" Y="100" zoom="1.0000000" Description="This is an example custom nodes." Category="MyCustomNodes.Utilities.Actions" Name="doubleValue" ID="85066088-1616-40b1-96e1-c33e685c6948">

套件節點移轉策略

當套件作者決定在新版本中更名先前存在的節點時，他們應該提供方法來移轉包含舊名稱節點的圖表。可以透過以下方式完成...

ZeroTouch 節點使用套件 bin 資料夾中的 Namespace.Migrations.XML 檔案，例如：

MyZeroTouchLib.MyNodes.SayHello 變為 MyZeroTouchLib.MyNodes.SayHelloRENAMED

<?xml version="1.0"?>
<migrations>
  <priorNameHint>
    <oldName>MyZeroTouchLib.MyNodes.SayHello</oldName>
    <newName>MyZeroTouchLib.MyNodes.SayHelloRENAMED</newName>
  </priorNameHint>
</migrations>

NodeModel 衍生的節點在類別上使用 AlsoKnownAs 屬性，例如：

SampleLibraryUI.Examples.DropDownExample 變為 SampleLibraryUI.Examples.DropDownExampleRENAMED

namespace SampleLibraryUI.Examples
{
    [NodeName("Drop Down Example")]
    [NodeDescription("An example drop down node.")]
    [IsDesignScriptCompatible]
    [AlsoKnownAs("SampleLibraryUI.Examples.DropDownExample")]
    public class DropDownExampleRENAMED : DSDropDownBase
    {
        ...
    }
{

發佈套件

套件是儲存節點並與 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://dynamobim.org/discover-the-new-dynamo-package-management-experience/。

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

更新套件詳細資料

作者可以按照以下步驟編輯其套件描述、網站連結和儲存庫連結：

1. 在**「我的套件」下選取套件，然後按一下「編輯套件詳細資料」**。

2. 使用各自的欄位增加或修改**「網站」和「儲存庫」**連結。

3. 依需要更新**「套件描述」**。

4. 按一下**「儲存變更」**套用更新。

注意: 由於伺服器更新需要一些時間，因此更新內容最多可能需要 15 分鐘，才能在 Dynamo 內的 Package Manager 中重新整理。我們正努力減少這種延誤。

編輯已發佈套件版本的相容性資訊

對於先前發佈的套件版本，可以透過回溯方式更新相容性資訊。請依以下步驟執行：

步驟 1：

1. 按一下要更新的套件版本。

2. **「相依於」**清單將自動填入套件所相依的套件。

3. 按一下**「相容性」旁邊的鉛筆圖示，開啟「編輯相容性資訊」**工作流程。

步驟 2：

請按照以下流程圖並參考下表，協助您瞭解哪種選項最適合您的套件。

我們來使用一些範例來逐步解說一些情境：

範例套件 #1 - Civil Connection：此套件與 Revit 和 Civil 3D 兩者都有 API 相依性，且不包括核心節點的集合 (例如：幾何函數、數學函數和/或清單管理)。因此，在此案例中，理想的選擇是選項 1。套件在與版本範圍和/或個別版本清單相符的 Revit 和 Civil 3D 中會顯示為「相容」。

範例套件 #2 - Rhythm：此套件是 Revit 特定節點的集合，以及核心節點的集合。在此案例中，套件有主體相依性。但也包括可在 Dynamo Core 中運作的核心節點。因此，在此案例中，理想的選擇是選項 2。套件在與版本範圍和/或個別版本清單相符的 Revit 和 Dynamo Core (也稱為 Dynamo Sandbox) 環境中會顯示為「相容」。

範例套件 #3 - Mesh Toolkit：此套件是一個 Dynamo Core 套件，是沒有主體相依性的幾何節點集合。因此，在此案例中，理想的選擇是選項 3。套件在與版本範圍和/或個別版本清單相符的 Dynamo 和所有主體環境中會顯示為「相容」。

根據選取的選項，將會彈出 Dynamo 和/或主體特定的欄位，如下圖所示。

使用 GeometryPrimitiveConverter.cs 中的方法

DynamoRevit 程式碼資源庫中的 GeometryPrimitiveConverter 類別提供各種方法，在 Revit 和 Dynamo 幾何類型之間進行轉換。在與 Revit 模型互動的 Dynamo 腳本中處理幾何圖形時，這些方法非常有用。

方法品類

GeometryPrimitiveConverter.cs 中的方法可分為四個主要品類：

1. Proto 轉換為 Revit 類型：將 Dynamo (Proto) 類型轉換為 Revit 類型的方法。

2. Revit 轉換為 Proto 類型：將 Revit 類型轉換為 Dynamo (Proto) 類型的方法。

3. 度與弳度：在度與弳度之間轉換的方法。

4. X 與 UZ：處理取得互垂向量的方法。

Proto 轉換為 Revit 類型

ToRevitBoundingBox

從 Dynamo 座標系統和兩個定義點 (最小值和最大值) 建立 Revit BoundingBoxXYZ。

public static Autodesk.Revit.DB.BoundingBoxXYZ ToRevitBoundingBox( Autodesk.DesignScript.Geometry.CoordinateSystem cs, Autodesk.DesignScript.Geometry.Point minPoint, Autodesk.DesignScript.Geometry.Point maxPoint, bool convertUnits = true)

ToRevitType (BoundingBox)

將 Dynamo BoundingBox 轉換為 Revit BoundingBoxXYZ。

convertUnits 旗標 (預設為 True) 決定座標是否應從 Dynamo 的單位系統轉換為 Revit 的內部單位。

public static Autodesk.Revit.DB.BoundingBoxXYZ ToRevitType(this Autodesk.DesignScript.Geometry.BoundingBox bb, bool convertUnits = true)

ToRevitType (Point)

將 Dynamo Point 轉換為 Revit XYZ。

convertUnits 旗標 (預設為 True) 會視需要轉換座標。

public static Autodesk.Revit.DB.XYZ ToRevitType(this Autodesk.DesignScript.Geometry.Point pt, bool convertUnits = true)

ToRevitType (Vector)

將 Dynamo Vector 轉換為 Revit XYZ。

請注意，convertUnits 旗標預設為 False，因為向量表示方向和大小，這通常不需要單位轉換。轉換可能會影響向量的方向和長度。

public static Autodesk.Revit.DB.XYZ ToRevitType(this Vector vec, bool convertUnits = false)

ToXyz (Point)

將 Dynamo Point 轉換為 Revit XYZ。

public static Autodesk.Revit.DB.XYZ ToXyz(this Autodesk.DesignScript.Geometry.Point pt, bool convertUnits = true)

ToXyz (Vector)

將 Dynamo Vector 轉換為 Revit XYZ。

請注意，convertUnits 旗標預設為 False，因為向量表示方向和大小，這通常不需要單位轉換。轉換可能會影響向量的方向和長度。

public static Autodesk.Revit.DB.XYZ ToXyz(this Vector vec, bool convertUnits = false)

ToTransform

將 Dynamo CoordinateSystem 轉換為 Revit Transform。

public static Autodesk.Revit.DB.Transform ToTransform(this CoordinateSystem cs, bool convertUnits = true)

ToPlane

將 Dynamo Plane 轉換為 Revit Plane。

public static Autodesk.Revit.DB.Plane ToPlane(this Autodesk.DesignScript.Geometry.Plane plane, bool convertUnits = true)

ToXyzs (Points)

將 Dynamo Point 物件的集合轉換為 Revit XYZ 集合。

傳回 XYZ 清單。public static List<XYZ> ToXyzs(this List<Autodesk.DesignScript.Geometry.Point> list, bool convertUnits = true)

傳回 XYZ 的陣列。public static XYZ[] ToXyzs(this Autodesk.DesignScript.Geometry.Point[] list, bool convertUnits = true)

ToXyzs (Vectors)

將 Dynamo Vector 物件的陣列轉換為 Revit XYZ 向量的陣列。

public static XYZ[] ToXyzs(this Autodesk.DesignScript.Geometry.Vector[] list, bool convertUnits = false)

ToDoubleArray

將倍精度值的陣列轉換為 Revit 的 DoubleArray。

public static DoubleArray ToDoubleArray(this double[] list)

ToUvs

將每個內部陣列都表示一對值 (U 和 V) 的二維陣列 (double[][]) 轉換為 Revit UV 物件的陣列。

internal static Autodesk.Revit.DB.UV[] ToUvs(this double[][] uvArr)

ToDSUvs

將每個內部陣列都表示一對值 (U 和 V) 的二維陣列 (double[][]) 轉換為 Dynamo UV 物件的陣列。

internal static Autodesk.DesignScript.Geometry.UV[] ToDSUvs(this double[][] uvArr)

使用 Proto 轉換為 Revit 類型的範例

此範例示範使用 .ToXyz (Point) 方法將 Dynamo Point.ByCoordinates 快速簡單轉換為 Revit XYZ 的方法。

# Load the Python Standard and DesignScript Libraries
import sys
import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

# Revit API
from Autodesk.Revit.DB import *

# Revit Geometry Conversion Library
import Revit
clr.ImportExtensions(Revit.GeometryConversion)

# Input: Dynamo Point
dyn_point = IN[0]

# Convert to Revit XYZ
revit_point = dyn_point.ToXyz()

# Output
OUT = revit_point

Revit 轉換為 Proto 類型

ToProtoType (BoundingBox)

將 Revit BoundingBoxXYZ 轉換為 Dynamo BoundingBox。

public static Autodesk.DesignScript.Geometry.BoundingBox ToProtoType(this Autodesk.Revit.DB.BoundingBoxXYZ xyz, bool convertUnits = true)

ToPoint (XYZ)

將 Revit XYZ 轉換為 Dynamo Point。

public static Autodesk.DesignScript.Geometry.Point ToPoint(this XYZ xyz, bool convertUnits = true)

ToProtoType (Point)

將 Revit Point 轉換為 Dynamo Point。

public static Autodesk.DesignScript.Geometry.Point ToProtoType(this Autodesk.Revit.DB.Point point, bool convertUnits = true)

ToVector (XYZ)

將 Revit XYZ 轉換為 Dynamo Vector。

public static Vector ToVector(this XYZ xyz, bool convertUnits = false)

ToProtoType (UV)

將 Revit UV 轉換為 Dynamo UV。

public static Autodesk.DesignScript.Geometry.UV ToProtoType(this Autodesk.Revit.DB.UV uv)

ToPlane (Revit Plane)

將 Revit Plane 轉換為 Dynamo Plane。

public static Autodesk.DesignScript.Geometry.Plane ToPlane(this Autodesk.Revit.DB.Plane plane, bool convertUnits = true)

ToCoordinateSystem

將 Revit Transform 轉換為 Dynamo CoordinateSystem。

public static CoordinateSystem ToCoordinateSystem(this Transform t, bool convertUnits = true)

ToPoints

將 Revit XYZ 點清單轉換為 Dynamo Point 清單。

public static List<Autodesk.DesignScript.Geometry.Point> ToPoints(this List<XYZ> list, bool convertUnits = true)

使用 Revit 轉換為 Proto 類型範例

此範例示範使用 .ToPoint (XYZ) 方法將 Revit XYZ 快速簡單轉換為 Dynamo Point 的方法。

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

# Revit API
from Autodesk.Revit.DB import *

# Revit Geometry Conversion Library
import Revit
clr.ImportExtensions(Revit.GeometryConversion)

# Input: Dynamo Point
dyn_point = IN[0]

# Convert to Revit XYZ
revit_point = dyn_point.ToPoint()

# Output
OUT = revit_point

度與弳度

ToRadians

將度轉換為弳度。

public static double ToRadians(this double degrees) { return degrees * Math.PI / 180.0; }

ToDegrees

將弳度轉換為度。

public static double ToDegrees(this double degrees) { return degrees * 180.0 / Math.PI; }

度與弳度的範例用法

此範例示範使用 .ToRadians 方法將度快速簡單轉換為弳度的方法。

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

# Revit API
from Autodesk.Revit.DB import *

# Revit Geometry Conversion Library
import Revit
clr.ImportExtensions(Revit.GeometryConversion)

# Input: Measure Angle
degree_angle = IN[0]

# Convert to Radians
radian_angle = Revit.GeometryConversion.GeometryPrimitiveConverter.ToRadians(degree_angle)

# Output
OUT = radian_angle

X 與 UZ

GetPerpendicular (XYZ)

此方法會傳回與給定 XYZ 向量互垂的 XYZ 向量。

public static XYZ GetPerpendicular(this XYZ xyz)

GetPerpendicular (Vector)

此方法會傳回與給定 Dynamo Vector 互垂的 Dynamo Vector。

public static Vector GetPerpendicular(this Vector vector)

X 與 UZ 的範例用法

此範例示範使用 .GetPerpendicular 方法快速簡單取得與輸入向量互垂之向量的方法。

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

# Revit API
from Autodesk.Revit.DB import *

# Revit Geometry Conversion Library
import Revit
clr.ImportExtensions(Revit.GeometryConversion)

# Input Dynamo Vector
input_vector = IN[0]

# Get perpendicular vector using GetPerpendicular
perpendicular_vector = Revit.GeometryConversion.GeometryPrimitiveConverter.GetPerpendicular(input_vector)

# Output the perpendicular vector
OUT = perpendicular_vector

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

延伸案例研究

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

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

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

DynamoSamples 儲存庫：https://github.com/DynamoDS/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 類別檔案中，加入以下程式碼：

using System;
using System.Windows;
using System.Windows.Controls;
using Dynamo.Wpf.Extensions;

namespace SampleViewExtension
{

    public class SampleViewExtension : IViewExtension
    {
        private MenuItem sampleMenuItem;

        public void Dispose()
        {
        }

        public void Startup(ViewStartupParams p)
        {
        }

        public void Loaded(ViewLoadedParams p)
        {
            // Save a reference to your loaded parameters.
            // You'll need these later when you want to use
            // the supplied workspaces

            sampleMenuItem = new MenuItem {Header = "Show View Extension Sample Window"};
            sampleMenuItem.Click += (sender, args) =>
            {
                var viewModel = new SampleWindowViewModel(p);
                var window = new SampleWindow
                {
                    // Set the data context for the main grid in the window.
                    MainGrid = { DataContext = viewModel },

                    // Set the owner of the window to the Dynamo window.
                    Owner = p.DynamoWindow
                };

                window.Left = window.Owner.Left + 400;
                window.Top = window.Owner.Top + 200;

                // Show a modeless window.
                window.Show();
            };
            p.AddMenuItem(MenuBarType.View, sampleMenuItem);
        }

        public void Shutdown()
        {
        }

        public string UniqueId
        {
            get
            {
                return Guid.NewGuid().ToString();
            }  
        } 

        public string Name
        {
            get
            {
                return "Sample View Extension";
            }
        } 

    }
}

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 類別檔案：

using System;
using Dynamo.Core;
using Dynamo.Extensions;
using Dynamo.Graph.Nodes;

namespace SampleViewExtension
{
    public class SampleWindowViewModel : NotificationObject, IDisposable
    {
        private string activeNodeTypes;
        private ReadyParams readyParams;

        // Displays active nodes in the workspace
        public string ActiveNodeTypes
        {
            get
            {
                activeNodeTypes = getNodeTypes();
                return activeNodeTypes;
            }
        }

        // Helper function that builds string of active nodes
        public string getNodeTypes()
        {
            string output = "Active nodes:\n";

            foreach (NodeModel node in readyParams.CurrentWorkspaceModel.Nodes)
            {
                string nickName = node.Name;
                output += nickName + "\n";
            }

            return output;
        }

        public SampleWindowViewModel(ReadyParams p)
        {
            readyParams = p;
            p.CurrentWorkspaceModel.NodeAdded += CurrentWorkspaceModel_NodesChanged;
            p.CurrentWorkspaceModel.NodeRemoved += CurrentWorkspaceModel_NodesChanged;
        }

        private void CurrentWorkspaceModel_NodesChanged(NodeModel obj)
        {
            RaisePropertyChanged("ActiveNodeTypes");
        }

        public void Dispose()
        {
            readyParams.CurrentWorkspaceModel.NodeAdded -= CurrentWorkspaceModel_NodesChanged;
            readyParams.CurrentWorkspaceModel.NodeRemoved -= CurrentWorkspaceModel_NodesChanged;
        }
    }
}

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

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

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

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

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

4. 選取「Add」

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

<Window x:Class="SampleViewExtension.SampleWindow"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
             xmlns:local="clr-namespace:SampleViewExtension"
             mc:Ignorable="d" 
             d:DesignHeight="300" d:DesignWidth="300"
            Width="500" Height="100">
    <Grid Name="MainGrid" 
          HorizontalAlignment="Stretch"
          VerticalAlignment="Stretch">
        <TextBlock HorizontalAlignment="Stretch" Text="{Binding ActiveNodeTypes}" FontFamily="Arial" Padding="10" FontWeight="Medium" FontSize="18" Background="#2d2d2d" Foreground="White"/>
    </Grid>
</Window>

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

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

using System.Windows;

namespace SampleViewExtension
{
    /// <summary>
    /// Interaction logic for SampleWindow.xaml
    /// </summary>
    public partial class SampleWindow : Window
    {
        public SampleWindow()
        {
            InitializeComponent();
        }
    }
}

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

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

2. 選取 XML 檔案

3. 將檔案命名為 SampleViewExtension_ViewExtensionDefinition.xml

4. 選取「Add」

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

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

<ViewExtensionDefinition>
  <AssemblyPath>C:\Users\username\Documents\Visual Studio 2015\Projects\SampleViewExtension\SampleViewExtension\bin\Debug\SampleViewExtension.dll</AssemblyPath>
  <TypeName>SampleViewExtension.SampleViewExtension</TypeName>
</ViewExtensionDefinition>

• 在此範例中，我們將組合建置到預設的 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 模型視圖中進行即時編輯的視圖延伸。

從 Dynamo 論壇 https://forum.dynamobim.com/t/dynashape-published/11666 可下載 DynamoShape 的套件安裝程式

從 Github https://github.com/LongNguyenP/DynaShape 可以複製原始程式碼

您已經找到 Dynamo 視覺程式設計語言的整合文件。

本指南將探討如何在應用程式中主控 Dynamo 的各種面向，讓使用者能夠使用視覺程式設計與應用程式互動。

內容：

• 本簡介 重點概述本指南涵蓋的內容，以及關於 Dynamo 的所有內容。

• Dynamo 自訂進入點 如何建立 DynamoModel 以及如何開始。

• 元素繫結和追蹤 使用 Dynamo 的追蹤機制，將圖表中的節點繫結至主體中的結果。

• Dynamo Revit Selection 節點 如何實作節點，讓使用者選取主體中的物件或資料，並將其作為輸入傳入 Dynamo 圖表。

• Dynamo 內建套件概述 什麼是 Dynamo 標準資源庫，以及如何使用底層機制透過整合方式遞送套件。

一些用語：

我們將在這些文件中交替使用 Dynamo 腳本、圖表和程式這幾個詞彙，來指稱使用者在 Dynamo 中建立的程式碼。

Dynamo 自訂進入點

以 Dynamo Revit 作為範例

https://github.com/DynamoDS/DynamoRevit/blob/master/src/DynamoRevit/DynamoRevit.cs#L534

DynamoModel 是主控 Dynamo 之某個應用程式的進入點 - 它代表的是一個 Dynamo 應用程式。模型是頂層根物件，此物件會參考組成 Dynamo 應用程式和 DesignScript 虛擬機器的其他重要資料結構和物件。

建構 DynamoModel 時，會使用規劃物件來設定上面的一般參數。

本文件中的範例取材自 DynamoRevit 實作，Revit 在此整合中主控 DynamoModel 作為增益集。(適用於 Revit 的外掛程式架構)。載入此增益集時，它會啟動一個 DynamoModel，然後使用 DynamoView 和 DynamoViewModel 向使用者顯示。

Dynamo 是一種 C# .NET 專案，若要在應用程式的程序中使用它，您必須能夠主控和執行 .NET 程式碼。

DynamoCore 是一個跨平台的計算引擎和核心模型集合，可使用 .NET 或 Mono (在未來的 .NET Core 中) 建置。但 DynamoCoreWPF 包含 Dynamo 僅限 Windows 的 UI 元件，無法在其他平台編譯。

自訂 Dynamo 進入點的步驟

若要初始化 DynamoModel，整合者必須在主體程式碼中的某個位置執行這些步驟。

從主體預先載入共用的 Dynamo Dll。

D4R 中的清單目前只包含 Revit\SDA\bin\ICSharpCode.AvalonEdit.dll. 這樣做是為了避免 Dynamo 與 Revit 之間的資源庫版本發生衝突。例如，當 AvalonEdit 發生衝突時，Code Block 的功能可能會被完全破壞。此問題已在 Dynamo 1.1.x https://github.com/DynamoDS/Dynamo/issues/7130 中進行回報，也可手動重現。如果整合者發現主體函數和 Dynamo 之間發生資源庫衝突，建議首先執行此作業。有時必須執行此作業，來阻止其他外掛程式或主體應用程式本身載入與共用相依性不相容的版本。更好的解決方式是讓版本一致來解決版本衝突 - 或者如果可能，在主體的 app.config 中使用 .net 繫結重新導向。

載入 ASM

什麼是 ASM 和 LibG

ASM 是建置 Dynamo 的基礎 ADSK 幾何圖形資源庫。

LibG 是包裝 ASM 幾何圖形核心的 .Net 人性化包裝函式。libG 與 ASM 共用其版本控制配置 - 它使用與 ASM 相同的主要和次要版本號碼，來指出它是特定 ASM 版本的對應包裝函式。如果給定 ASM 版本，對應的 libG 版本應該相同。在大多數情況下，LibG 應該可以搭配特定主要版本的所有 ASM 版本運作。例如 LibG 223，應該能夠載入任何 ASM 223 版本。

Dynamo Sandbox 載入 ASM

Dynamo Sandbox 設計的目的是為了能夠使用多個 ASM 版本，為了達到這個目的，會將多個 libG 版本捆綁在一起並隨核心一起遞送。Dynamo Shape Manager 中提供內建功能，可搜尋 ASM 隨附的 Autodesk 產品，因此 Dynamo 可以從這些產品載入 ASM，讓幾何圖形節點無需明確載入至主體應用程式即可運作。目前存在的產品清單為：

private static readonly List<string> ProductsWithASM = new List<string>() 

 { "Revit", "Civil", "Robot Structural Analysis", "FormIt" }; 

Dynamo 會搜尋 Windows 登錄，尋找此清單中的 Autodesk 產品是否已安裝在使用者的電腦上 (如果已安裝其中任何一個)，接著會搜尋 ASM 二進位檔，取得版本並尋找 Dynamo 中對應的 libG 版本。

找到 ASM 版本後，以下 ShapeManager API 將挑選要載入的對應 libG 預載程式位置。如果有確切符合的版本，則會使用該版本，否則會載入最接近的較低版次，但主要版本相同的 libG。

例如，如果 Dynamo 與有較新版 ASM 建置版本 225.3.0 的 Revit 開發建置版本整合，Dynamo 會嘗試使用 libG 225.3.0 (如果有)，否則會嘗試使用小於其首選的最接近主要版本，即 225.0.0。

public static string GetLibGPreloaderLocation(Version asmVersion, string dynRootFolder)

Dynamo 程序內整合從主體載入 ASM

Revit 是 ASM 產品搜尋清單中的第一個項目，這表示預設情況下，DynamoSandbox.exe 會先嘗試從 Revit 載入 ASM，我們仍需要確保整合的 D4R 工作階段作業會從目前 Revit 主體載入 ASM：例如，如果使用者電腦同時有 R2018 和 R2020，則從 R2020 啟動 D4R 時，D4R 應使用 R2020 的 ASM 225，而不是 R2018 的 ASM 223。整合者需要實作類似下列內容的呼叫，以強制載入其指定的版本。

internal static Version PreloadAsmFromRevit() 

{ 

     var asmLocation = AppDomain.CurrentDomain.BaseDirectory; 
     Version libGVersion = findRevitASMVersion(asmLocation); 
     var dynCorePath = DynamoRevitApp.DynamoCorePath; 
     var preloaderLocation = DynamoShapeManager.Utilities.GetLibGPreloaderLocation(libGVersion, dynCorePath); 
     Version preLoadLibGVersion = PreloadLibGVersion(preloaderLocation); 
     DynamoShapeManager.Utilities.PreloadAsmFromPath(preloaderLocation, asmLocation); 
     return preLoadLibGVersion; 

} 

Dynamo 從自訂路徑載入 ASM

我們最近增加 DynamoSandbox.exe 和 DynamoCLI.exe 載入特定 ASM 版本的功能。若要略過正常的登錄搜尋行為，您可以使用 �gp 旗標強制 Dynamo 從特定路徑載入 ASM。

DynamoSandbox.exe -gp �somePath/To/ASMDirectory/�

建立 StartConfiguration

使用 StartupConfiguration 的方式是作為參數傳入來初始化 DynamoModel，這表示它包含您想要如何自訂 Dynamo 階段作業設定的幾乎所有定義。根據以下性質的設定方式，Dynamo 整合可能會因不同的整合者而異。例如，不同的整合者可能會設定不同的 python 樣板路徑，或顯示的數值格式。

包括以下內容：

• DynamoCorePath // 載入 DynamoCore 二進位檔所在的位置

• DynamoHostPath // Dynamo 整合二進位檔所在的位置

• GeometryFactoryPath // 載入的 libG 二進位檔所在的位置

• PathResolver //協助解析各種檔案的物件

• PreloadLibraryPaths // 預載節點二進位檔 (例如 DSOffice.dll) 所在的位置

• AdditionalNodeDirectories // 其他節點二進位檔所在的位置

• AdditionalResolutionPaths // 載入資源庫時可能需要的其他相依性的額外組合解決方案路徑

• UserDataRootFolder // 使用者資料資料夾，例如 "AppData\Roaming\Dynamo\Dynamo Revit"

• CommonDataRootFolder // 用於儲存自訂定義、範例等的預設資料夾。

• Context // 整合者主體名稱 + 版本 (Revit<BuildNum>)

• SchedulerThread // 實作 ISchedulerThread 的整合者排程器執行緒 - 對於大多數整合者而言，這是主要 UI 執行緒或可存取其 API 的任何執行緒。

• StartInTestMode // 目前階段作業是否為測試自動化階段作業 - 修改一堆 Dynamo 行為 - 除非您正在撰寫測試，否則請不要使用。

• AuthProvider // 整合者的 IAuthProvider 實作，例如 RevitOxygenProvider 實作是在 Greg.dll - 用於 packageManager 上傳整合。

偏好

預設偏好設定路徑由 PathManager.PreferenceFilePath (例如 "AppData\\Roaming\\Dynamo\\Dynamo Revit\\2.5\\DynamoSettings.xml") 管理。整合者可以決定是否也要將自訂的偏好設定檔案遞送到需要與路徑管理員一致的位置。以下是序列化的偏好設定性質：

• IsFirstRun // 表示是否是第一次執行此版本的 Dynamo，例如用於判斷是否需要顯示 GA 選擇加入/退出訊息。也會用於判斷在啟動新的 Dynamo 版本時，是否需要移轉舊式 Dynamo 偏好設定，讓使用者獲得一致的體驗

• IsUsageReportingApproved // 指出使用情況報告是否已核准

• IsAnalyticsReportingApproved // 指出分析報告是否已核准

• LibraryWidth // Dynamo 左側資源庫面板的寬度。

• ConsoleHeight // 主控台顯示的高度

• ShowPreviewBubbles // 指出是否應顯示預覽標示圈

• ShowConnector // 指出是否顯示連接器

• ConnectorType // 指出連接器類型：Bezier 或 Polyline (聚合線)

• BackgroundPreviews // 指出指定背景預覽的作用中狀態

• RenderPrecision // 彩現精確度等級 - 越低表示會產生三角形數越少的網格。越高表示會在背景預覽中產生越平滑的幾何圖形。128 對於預覽幾何圖形是一個很適合可靠的數字。

• ShowEdges // 指出是否將彩現曲面和實體邊

• ShowDetailedLayout // 未使用

• WindowX、WindowY // Dynamo 視窗的最後 X、Y 座標

• WindowW、WindowH // Dynamo 視窗的最後寬度、高度

• UseHardwareAcceleration // Dynamo 是否應使用硬體加速 (如果支援)

• NumberFormat // 用於在預覽標示圈 toString() 中顯示數字的小數精確度。

• MaxNumRecentFiles // 要儲存的最近檔案路徑最大數目

• RecentFiles // 最近開啟的檔案路徑清單，修改此設定會直接影響 Dynamo 開始頁面中的最近使用檔案清單

• BackupFiles // 備份檔案路徑清單

• CustomPackageFolders // 包含 zero-touch 二進位檔和目錄路徑的資料夾清單，系統會掃描這些資料夾中是否有套件和自訂節點。

• PackageDirectoriesToUninstall // Package Manager 用來判斷哪些套件被標記為刪除的套件清單。在 Dynamo 啟動期間會刪除這些路徑 (如果可以)。

• PythonTemplateFilePath // 建立新的 PythonScript 節點時用作起始樣板的 Python (.py) 檔案路徑 - 可用來設定自訂 Python 樣板以進行整合。

• BackupInterval // 指出自動儲存圖表的時間長度 (以毫秒為單位)

• BackupFilesCount // 指出要進行的備份數量

• PackageDownloadTouAccepted // 指出使用者是否已接受使用條款從 Package Manager 下載套件

• OpenFileInManualExecutionMode // 指出「開啟檔案」對話方塊中「以手動模式開啟」勾選方塊的預設狀態

• NamespacesToExcludeFromLibrary // 指出哪些名稱空間 (如果有) 不應顯示在 Dynamo 節點資源庫中。字串格式："[資源庫名稱]:[完整名稱空間]"

序列化偏好設定的範例：

<PreferenceSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 

<IsFirstRun>false</IsFirstRun> 

<IsUsageReportingApproved>false</IsUsageReportingApproved> 

<IsAnalyticsReportingApproved>false</IsAnalyticsReportingApproved> 

<LibraryWidth>204</LibraryWidth> 

<ConsoleHeight>0</ConsoleHeight> 

<ShowPreviewBubbles>true</ShowPreviewBubbles> 

<ShowConnector>true</ShowConnector> 

<ConnectorType>BEZIER</ConnectorType> 

<BackgroundPreviews> 

<BackgroundPreviewActiveState> 

<Name>IsBackgroundPreviewActive</Name> 

<IsActive>true</IsActive> 

</BackgroundPreviewActiveState> 

<BackgroundPreviewActiveState> 

<Name>IsRevitBackgroundPreviewActive</Name> 

<IsActive>true</IsActive> 

</BackgroundPreviewActiveState> 

</BackgroundPreviews> 

<IsBackgroundGridVisible>true</IsBackgroundGridVisible> 

<RenderPrecision>128</RenderPrecision> 

<ShowEdges>false</ShowEdges> 

<ShowDetailedLayout>true</ShowDetailedLayout> 

<WindowX>553</WindowX> 

<WindowY>199</WindowY> 

<WindowW>800</WindowW> 

<WindowH>676</WindowH> 

<UseHardwareAcceleration>true</UseHardwareAcceleration> 

<NumberFormat>f3</NumberFormat> 

<MaxNumRecentFiles>10</MaxNumRecentFiles> 

<RecentFiles> 

<string></string> 

</RecentFiles> 

<BackupFiles> 

<string>..AppData\Roaming\Dynamo\Dynamo Revit\backup\backup.DYN</string> 

</BackupFiles> 

<CustomPackageFolders> 

<string>..AppData\Roaming\Dynamo\Dynamo Revit\2.5</string> 

</CustomPackageFolders> 

<PackageDirectoriesToUninstall /> 

<PythonTemplateFilePath /> 

<BackupInterval>60000</BackupInterval> 

<BackupFilesCount>1</BackupFilesCount> 

<PackageDownloadTouAccepted>true</PackageDownloadTouAccepted> 

<OpenFileInManualExecutionMode>false</OpenFileInManualExecutionMode> 

<NamespacesToExcludeFromLibrary> 

<string>ProtoGeometry.dll:Autodesk.DesignScript.Geometry.TSpline</string> 

</NamespacesToExcludeFromLibrary> 

</PreferenceSettings>