無論經驗程度為何，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)

瞭解如何建立 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 生態系統中功能強大的開發工具。這些工具可讓開發人員根據 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 模型視圖中進行即時編輯的視圖延伸。

簡介

本部分包含將圖表、套件和資源庫移轉至 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 開發人員社群中有幾個專案樣板非常適合開始，但瞭解如何從頭開始一個專案更有價值。從頭開始建立一個專案可以更深入地瞭解開發過程。

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

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

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

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

Dynamo 以模型-視圖-視圖模型 (MVVM) 軟體架構模式為基礎，讓使用者介面與後端保持獨立。建立 ZeroTouch 節點時，Dynamo 會在節點的資料與其使用者介面之間繫結資料。若要建立自訂使用者介面，我們必須加入資料繫結邏輯。

在 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。

using System;
using System.Collections.Generic;
using Dynamo.Graph.Nodes;
using CustomNodeModel.CustomNodeModelFunction;
using ProtoCore.AST.AssociativeAST;
using Autodesk.DesignScript.Geometry;

namespace CustomNodeModel.CustomNodeModel
{
    [NodeName("RectangularGrid")]
    [NodeDescription("An example NodeModel node that creates a rectangular grid. The slider randomly scales the cells.")]
    [NodeCategory("CustomNodeModel")]
    [InPortNames("xCount", "yCount")]
    [InPortTypes("double", "double")]
    [InPortDescriptions("Number of cells in the X direction", "Number of cells in the Y direction")]
    [OutPortNames("Rectangles")]
    [OutPortTypes("Autodesk.DesignScript.Geometry.Rectangle[]")]
    [OutPortDescriptions("A list of rectangles")]
    [IsDesignScriptCompatible]
    public class GridNodeModel : NodeModel
    {
        private double _sliderValue;
        public double SliderValue
        {
            get { return _sliderValue; }
            set
            {
                _sliderValue = value;
                RaisePropertyChanged("SliderValue");
                OnNodeModified(false);
            }
        }
        public GridNodeModel()
        {
            RegisterAllPorts();
        }
        public override IEnumerable<AssociativeNode> BuildOutputAst(List<AssociativeNode> inputAstNodes)
        {
            if (!HasConnectedInput(0) || !HasConnectedInput(1))
            {
                return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), AstFactory.BuildNullNode()) };
            }
            var sliderValue = AstFactory.BuildDoubleNode(SliderValue);
            var functionCall =
              AstFactory.BuildFunctionCall(
                new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid),
                new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue });

            return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), functionCall) };
        }
    }
}

這與 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。

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

namespace CustomNodeModel.CustomNodeModelFunction
{
    [IsVisibleInDynamoLibrary(false)]
    public class GridFunction
    {
        [IsVisibleInDynamoLibrary(false)]
        public static List<Rectangle> RectangularGrid(int xCount = 10, int yCount = 10, double rand = 1)
        {
            double x = 0;
            double y = 0;

            Point pt = null;
            Vector vec = null;
            Plane bP = null;

            Random rnd = new Random(2);

            var pList = new List<Rectangle>();
            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    double rNum = rnd.NextDouble();
                    double scale = rNum * (1 - rand) + rand;
                    x++;
                    pt = Point.ByCoordinates(x, y);
                    vec = Vector.ZAxis();
                    bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, scale, scale);
                    pList.Add(rect);
                }
            }
            pt.Dispose();
            vec.Dispose();
            bP.Dispose();
            return pList;
        }
    }
}

此函數類別與 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

using Dynamo.Controls;
using Dynamo.Wpf;

namespace CustomNodeModel.CustomNodeModel
{
    public class CustomNodeModelView : INodeViewCustomization<GridNodeModel>
    {
        public void CustomizeView(GridNodeModel model, NodeView nodeView)
        {
            var slider = new Slider();
            nodeView.inputGrid.Children.Add(slider);
            slider.DataContext = model;
        }

        public void Dispose()
        {
        }
    }
}

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

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

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

2. 選取「WPF」

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

4. 按一下「Add」

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

<UserControl x:Class="CustomNodeModel.CustomNodeModel.Slider"
             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:CustomNodeModel.CustomNodeModel"
             mc:Ignorable="d" 
             d:DesignHeight="75" d:DesignWidth="100">
    <Grid Margin="10">
        <Slider Grid.Row="0" Width="80" Minimum="0" Maximum="1" IsSnapToTickEnabled="True" TickFrequency="0.01" Value="{Binding SliderValue}"/>
    </Grid>
</UserControl>

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

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

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

using System.Windows.Controls;

namespace CustomNodeModel.CustomNodeModel
{
    /// <summary>
    /// Interaction logic for Slider.xaml
    /// </summary>
    public partial class Slider : UserControl
    {
        public Slider()
        {
            InitializeComponent();
        }
    }
}

• 名稱空間應為 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

{
  "license": "MIT",
  "file_hash": null,
  "name": "CustomNodeModel",
  "version": "1.0.0",
  "description": "Sample node",
  "group": "CustomNodes",
  "keywords": [ "grid", "random" ],
  "dependencies": [],
  "contents": "Sample node",
  "engine_version": "1.3.0",
  "engine": "dynamo",
  "engine_metadata": "",
  "site_url": "",
  "repository_url": "",
  "contains_binaries": true,
  "node_libraries": [
    "CustomNodeModel, Version=1.0.0, Culture=neutral, PublicKeyToken=null",
    "CustomNodeModelFunction, Version=1.0.0, Culture=neutral, PublicKeyToken=null"
  ]
}

• "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

在 librarie.js 中組織自訂節點

已知問題：

• 自訂節點名稱和品類名稱在 library.js 中的同一層級如果相同，會導致非預期的行為。QNTM-3653 - 請避免對品類和節點使用相同的名稱。

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

• 簡短類型名稱將取代為完整名稱。例如，如果您在再次載入自訂節點時未指定類型，您會看到 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 性質的名稱相符，但是如果您使用 [JsonProperty] 屬性取代序列化的名稱，則此對映會更複雜。 請參閱 Json.net 文件，以取得更多資訊。

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 建構函式中必須複製其他使用者邏輯 (例如，初始化節點的事件處理常式或附加)。

在 DynamoSamples 儲存庫 -> ButtonCustomNodeModel、DropDown 或 SliderCustomNodeModel 中可以找到範例

公用性質和序列化

先前，開發人員可以透過 SerializeCore 和 DeserializeCore 方法將特定模型資料序列化和還原序列化為 xml 文件。這些方法仍存在於 API 中，但在未來版本的 Dynamo 中將棄用 (在此處可找到範例)。現在實作 JSON.NET，NodeModel 衍生類別的 public 性質可以直接序列化為 .dyn 檔案。JSON.Net 提供多個屬性，可控制如何序列化性質。

在 Dynamo 儲存庫中的此處可以找到指定 PropertyName 的此範例。

[JsonProperty(PropertyName = "InputValue")]

public DSColor DsColor {...

轉換器：

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

在 Dynamo 儲存庫中的此處可以找到一個範例，指定將性質轉換為字串的序列化方法。

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

public ConversionMetricUnit SelectedMetricConversion{...

忽略性質

不用於序列化的 public 性質需要加入 [JsonIgnore] 屬性。節點儲存為 .dyn 檔案後，可確保序列化機制忽略此資料，再次開啟圖表時，不會導致非預期的結果。在 Dynamo 儲存庫中的此處可以找到此內容的範例。

退回/重做

如上所述，過去曾使用 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

在 Dynamo 儲存庫 -> DynamoConvert.cs 或 FileSystem.cs 中可以找到轉換的程式碼範例

受 2.0 API 變更影響的其他常見使用案例與 BuildAst() 方法中常用的方法有關，該方法可根據埠連接器是否存在決定節點行為。先前 HasConnectedInput(index) 是用於驗證連接的埠狀態。開發人員現在應使用 InPorts[0].IsConnected 性質檢查埠連接狀態。在 Dynamo 儲存庫中的 ColorRange.cs 可以找到此內容的範例。

範例：

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

using System;
using System.Collections.Generic;
using Dynamo.Graph.Nodes;
using CustomNodeModel.CustomNodeModelFunction;
using ProtoCore.AST.AssociativeAST;
using Autodesk.DesignScript.Geometry;

namespace CustomNodeModel.CustomNodeModel
{
    [NodeName("RectangularGrid")]
    [NodeDescription("An example NodeModel node that creates a rectangular grid. The slider randomly scales the cells.")]
    [NodeCategory("CustomNodeModel")]
    [InPortNames("xCount", "yCount")]
    [InPortTypes("double", "double")]
    [InPortDescriptions("Number of cells in the X direction", "Number of cells in the Y direction")]
    [OutPortNames("Rectangles")]
    [OutPortTypes("Autodesk.DesignScript.Geometry.Rectangle[]")]
    [OutPortDescriptions("A list of rectangles")]
    [IsDesignScriptCompatible]
    public class GridNodeModel : NodeModel
    {
        private double _sliderValue;
        public double SliderValue
        {
            get { return _sliderValue; }
            set
            {
                _sliderValue = value;
                RaisePropertyChanged("SliderValue");
                OnNodeModified(false);
            }
        }
        public GridNodeModel()
        {
            RegisterAllPorts();
        }
        public override IEnumerable<AssociativeNode> BuildOutputAst(List<AssociativeNode> inputAstNodes)
        {
            if (!HasConnectedInput(0) || !HasConnectedInput(1))
            {
                return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), AstFactory.BuildNullNode()) };
            }
            var sliderValue = AstFactory.BuildDoubleNode(SliderValue);
            var functionCall =
              AstFactory.BuildFunctionCall(
                new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid),
                new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue });

            return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), functionCall) };
        }
    }
}

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

[JsonConstructor]
protected GridNodeModel(IEnumerable<PortModel> Inports, IEnumerable<PortModel> Outports ) :
base(Inports,Outports)
{

}

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

[InPortNames("xCount", "yCount")]
[InPortTypes("double", "double")]

此範例加入負載很低的 JSON 建構函式。但如果我們需要執行一些更複雜的建構邏輯，例如設定一些接聽程式以在建構函式內處理事件，該怎麼辦。下一個範例是從 DynamoSamples 儲存庫取得，在本文件上方的 。JsonConstructors Section 有連結。

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

 public ButtonCustomNodeModel()
        {
            // When you create a UI node, you need to do the
            // work of setting up the ports yourself. To do this,
            // you can populate the InPorts and the OutPorts
            // collections with PortData objects describing your ports.
            InPorts.Add(new PortModel(PortType.Input, this, new PortData("inputString", "a string value displayed on our button")));

            // Nodes can have an arbitrary number of inputs and outputs.
            // If you want more ports, just create more PortData objects.
            OutPorts.Add(new PortModel(PortType.Output, this, new PortData("button value", "returns the string value displayed on our button")));
            OutPorts.Add(new PortModel(PortType.Output, this, new PortData("window value", "returns the string value displayed in our window when button is pressed")));

            // This call is required to ensure that your ports are
            // properly created.
            RegisterAllPorts();

            // Listen for input port disconnection to trigger button UI update
            this.PortDisconnected += ButtonCustomNodeModel_PortDisconnected;

            // The arugment lacing is the way in which Dynamo handles
            // inputs of lists. If you don't want your node to
            // support argument lacing, you can set this to LacingStrategy.Disabled.
            ArgumentLacing = LacingStrategy.Disabled;

            // We create a DelegateCommand object which will be 
            // bound to our button in our custom UI. Clicking the button 
            // will call the ShowMessage method.
            ButtonCommand = new DelegateCommand(ShowMessage, CanShowMessage);

            // Setting our property here will trigger a 
            // property change notification and the UI 
            // will be updated to reflect the new value.
            ButtonText = defaultButtonText;
            WindowText = defaultWindowText;
        }

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

        // This constructor is called when opening a Json graph.

        [JsonConstructor]
        ButtonCustomNodeModel(IEnumerable<PortModel> inPorts, IEnumerable<PortModel> outPorts) : base(inPorts, outPorts)
        {
            this.PortDisconnected += ButtonCustomNodeModel_PortDisconnected;
            ButtonCommand = new DelegateCommand(ShowMessage, CanShowMessage);
        }

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

在 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。

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

namespace CustomNodes
{
    public class Grids
    {
        public static List<Rectangle> RectangularGrid(int xCount, int yCount)
        {
        //The method for creating a rectangular grid will live in here
        }
    }
}

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

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

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

namespace CustomNodes
{
    public class Grids
    {
        public static List<Rectangle> RectangularGrid(int xCount, int yCount)
        {
            double x = 0;
            double y = 0;

            var pList = new List<Rectangle>();

            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    x++;
                    Point pt = Point.ByCoordinates(x, y);
                    Vector vec = Vector.ZAxis();
                    Plane bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, 1, 1);
                    pList.Add(rect);
                }
            }
            return pList;
        }
    }
}

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

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

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

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

2. 圖元區上的自訂節點

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

修改自訂節點

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

1. 預設輸入值

2. xCount 輸入的工具提示

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

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

namespace CustomNodes
{
    public class Grids
    {
        /// <summary>
        /// This method creates a rectangular grid from an X and Y count.
        /// </summary>
        /// <param name="xCount">Number of grid cells in the X direction</param>
        /// <param name="yCount">Number of grid cells in the Y direction</param>
        /// <returns>A list of rectangles</returns>
        /// <search>grid, rectangle</search>
        public static List<Rectangle> RectangularGrid(int xCount = 10, int yCount = 10)
        {
            double x = 0;
            double y = 0;

            var pList = new List<Rectangle>();

            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    x++;
                    Point pt = Point.ByCoordinates(x, y);
                    Vector vec = Vector.ZAxis();
                    Plane bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, 1, 1);
                    pList.Add(rect);
                    Point cPt = rect.Center();
                }
            }
            return pList;
        }
    }
}

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

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

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

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

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