在 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 软件包 System.Collections.Generic 中的 ProtoGeometry.dll

现在，我们可以添加用于绘制矩形的方法。类文件应如下所示，并可以复制到 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 文件。通过启用该选项，.xml 可以由 Visual Studio 自动生成。

1. 在此处启用 XML 文档文件，然后指定文件路径。这将生成一个 XML 文件。

大功告成！我们已创建了一个包含多个标准功能的新节点。以下“Zero-Touch 基础知识”章节将更详细地介绍 Zero-Touch 节点开发以及需要注意的问题。

简介

本部分包含有关将图形、软件包和库移植到 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 中下载从 Dynamo 版本低于 3.0 发布的软件包时，您会收到一条警告，指出该软件包来自较旧版本的 Dynamo。

这并不意味着软件包将不工作。这只是一个警告，指出可能存在兼容性问题；通常，最好检查是否有专为 Dynamo 3.x 构建的较新版本。

在加载软件包时，您还可能会在 Dynamo 日志文件中注意到此类警告。如果一切正常，可以忽略它。

在 Dynamo 2.x 中使用 Dynamo 3.x 软件包

为 Dynamo 3.x（使用 .Net8）构建的软件包不太可能基于 Dynamo 2.x 运行。如果您正在使用较旧版本的 Dynamo，则下载为更高版本的 Dynamo 构建的软件包时，还会看到警告。

在开始开发之前，请务必为新项目打下坚实基础。Dynamo 开发人员社区中的多个项目模板是绝佳的起点，但了解如何从头开始构建项目更有价值。通过从头开始构建项目，将能够更深入地了解开发过程。

创建 Visual Studio 项目

Visual Studio 是一个功能强大的 IDE，我们可以在其中创建项目、添加参照、构建 .dlls 和调试。在创建新项目时，Visual Studio 还会创建一个解决方案，即用于组织项目的结构。多个项目可以存在于一个解决方案中，并可以一起构建。要创建 ZeroTouch 节点，我们需要开始一个新的 Visual Studio 项目，我们将在该项目中编写一个 C# 类库并构建一个 .dll。

Visual Studio 中的“新建项目”窗口

1. 首先打开 Visual Studio 并创建一个新项目：File > New > Project

2. 选择 Class Library 项目模板

3. 为项目命名（我们已将项目命名为“MyCustomNode”）

4. 设置项目的文件路径。在本例中，我们将其保留在默认位置

5. 选择 Ok

Visual Studio 将自动创建并打开一个 C# 文件。我们应为其指定一个合适名称、设置工作空间，并将默认代码替换为以下乘法方法。

1. 从 View 打开“解决方案资源管理器”和“输出”窗口。

2. 在右侧的“解决方案资源管理器”中，将 Class1.cs 文件重命名为 SampleFunctions.cs。

3. 为乘法函数添加上述代码。我们稍后会介绍 Dynamo 将如何读取您的 C# 类的详情。

4. 解决方案资源管理器：该资源管理器使您能够访问项目中的所有内容。

5. “输出”窗口：我们稍后会需要使用该窗口来查看构建是否已成功。

下一步是构建项目，但在构建之前，我们需要检查一些设置。首先，确保已选择 Any CPU 或 x64 作为平台目标，并确保在“项目特性”中未选中 Prefer 32-bit。

1. 通过选择 Project > "ProjectName" Properties 打开项目特性

2. 选择 Build 页面

3. 从下拉菜单中选择 Any CPU 或 x64

4. 确保未选中 Prefer 32-bit

现在，我们可以构建项目以创建 .dll。要执行此操作，请从 Build 菜单中选择 Build Solution，或使用快捷键 CTRL+SHIFT+B。

1. 选择 Build > Build Solution

2. 可以通过检查“输出”窗口来确定您的项目是否已成功构建

如果项目已成功构建，则项目的 bin 文件夹中会有一个名为 MyCustomNode 的 .dll。在本例中，我们已将项目的文件路径保留为 Visual Studio 的默认路径：c:\users\username\documents\visual studio 2015\Projects。让我们来看一下项目的文件结构。

1. bin 文件夹包含从 Visual Studio 构建的 .dll。

2. Visual Studio 项目文件。

3. 类文件。

4. 由于我们的解决方案配置已设置为 Debug，因此将在 bin\Debug 中创建 .dll。

现在，我们可以打开 Dynamo 并输入 .dll。使用“添加”功能时，导航到项目的 bin 位置，然后选择要打开的 .dll。

1. 选择“添加”按钮以输入 .dll

2. 浏览到项目位置。我们的项目位于 Visual Studio 的默认文件路径：C:\Users\username\Documents\Visual Studio 2015\Projects\MyCustomNode

3. 选择要输入的 MyCustomNode.dll

4. 单击 Open 以载入 .dll

如果在名为 MyCustomNode 的库中创建了一个类别，则表示 .dll 已成功输入！但是，Dynamo 创建了两个节点，而我们希望这两个节点成为单个节点。在下一节中，我们将解释发生这种情况的原因，以及 Dynamo 读取 .dll 的方式。

1. Dynamo 库中的 MyCustomNode。“库”类别由 .dll 名称确定。

2. 画布上的 SampleFunctions.MultiplyByTwo。

Dynamo 读取类和方法的方式

在 Dynamo 载入 .dll 后，它会将所有公有静态方法显示为节点。构造函数、方法和特性将分别转换为 Create、Action 和 Query 节点。在我们的乘法示例中，MultiplyByTwo() 方法会在 Dynamo 中成为 Action 节点。这是因为节点已根据其方法和类进行命名。

1. 根据方法的参数名称，输入命名为 inputNumber。

2. 输出默认命名为 double，因为这是要返回的数据类型。

3. 节点命名为 SampleFunctions.MultiplyByTwo，因为这些是类和方法名称。

在上面的示例中，创建了额外的 SampleFunctions Create 节点，因为我们没有显式地提供构造函数，因此自动创建了一个构造函数。我们可以通过在 SampleFunctions 类中创建一个空的私有构造函数，来避免出现这种情况。

1. Dynamo 已将我们的方法输入为 Create 节点

添加 Dynamo NuGet 软件包参照

乘法节点非常简单，不需要参照 Dynamo。例如，如果我们要访问 Dynamo 的任何功能来创建几何图形，则我们需要参照 Dynamo NuGet 软件包。

要在 Visual Studio 项目中参照这些软件包，请通过上述链接从 NuGet 中下载软件包并手动参照 .dll，或者在 Visual Studio 中使用 NuGet 软件包管理器。首先，我们可以漫游如何在 Visual Studio 中使用 NuGet 安装它们。

1. 通过选择 Tools > NuGet Package Manager > Manage NuGet Packages for Solution... 来打开 NuGet 软件包管理器

这是 NuGet 软件包管理器。此窗口会显示已为项目安装的软件包，并允许用户浏览其他软件包。如果发布了新版本的 DynamoServices 软件包，则可以从此处更新软件包或将其恢复为早期版本。

1. 选择“浏览并搜索 DynamoVisualProgramming”以显示 Dynamo 软件包。

2. Dynamo 软件包。选择一个软件包即会显示其当前版本，以及内部内容的描述。

3. 选择所需的软件包版本，然后单击“安装”。这将为您要处理的特定项目安装一个软件包。由于我们使用的是 Dynamo 的最新稳定版本 1.3，因此请选择相应的软件包版本。

要手动添加从浏览器下载的软件包，请从“解决方案资源管理器”打开“参照管理器”，然后浏览到该软件包。

1. 在 References 上单击鼠标右键，然后选择 Add Reference。

2. 选择 Browse 以导航到软件包位置。

现在，Visual Studio 已正确配置，并且我们已成功将 .dll 添加到 Dynamo，这样我们就为后续概念奠定了坚实基础。这仅仅是一个开始，因此请继续学习，以详细了解如何创建自定义节点。

相较于 Zero-Touch 节点，基于 NodeModel 的节点提供了更大的灵活性和更强大的功能。在本例中，我们将通过添加一个随机化矩形大小的集成滑块，来将 Zero-Touch 网格节点提升到下一个级别。

滑块会相对于单元大小缩放单元，因此用户不必为滑块提供正确的范围。

Model-View-Viewmodel 模式

Dynamo 基于 model-view-viewmodel (MVVM) 软件体系结构模式，以使 UI 与后端保持分离。当创建 ZeroTouch 节点时，Dynamo 会在节点的数据与其 UI 之间绑定数据。要创建自定义 UI，我们必须添加数据绑定逻辑。

在较高级别上，在 Dynamo 中建立模型-视图关系有两个部分：

• NodeModel 类用于建立节点的核心逻辑（“模型”）

• INodeViewCustomization 类用于自定义如何查看 NodeModel（“视图”）

NodeModel 对象已有关联的视图-模型 (NodeViewModel)，因此我们可以仅关注自定义 UI 的模型和视图。

如何实现 NodeModel

NodeModel 节点与 Zero-Touch 节点有几个明显差异，我们将在本例中介绍这些差异。在我们进入 UI 自定义之前，让我们先构建 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 将用于我们稍后进行操作的 UI 自定义，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") 会在滑块值发生更改时通知 UI

• 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 网格案例研究非常相似，但有一点不同：

• 由于已从 CustomNodeModel 调用函数，因此 [IsVisibleInDynamoLibrary(false)] 会阻止 Dynamo“看到”以下方法和类。

正如我们为 NuGet 软件包添加参照一样，CustomNodeModel 需要参照 CustomNodeModelFunction 才能调用函数。

在我们参照函数之前，CustomNodeModel 的 using 语句将处于不活动状态

1. 在 CustomNodeModel 上单击鼠标右键，然后选择 Add > Reference

2. 选择 Projects > Solution

3. 选中 CustomNodeModelFunction

4. 单击 Ok

4.自定义视图

要创建滑块，我们需要通过实现 INodeViewCustomization 接口来自定义 UI。

将以下代码复制到 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> 定义自定义 UI 所需的功能。

在完成设置项目结构后，使用 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 构建软件包。

在 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 可以作为软件包的一部分或通过导航到 File < Import Library... 以输入到 Dynamo 中

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 节点，则以下内容应该很熟悉。有关详细信息，请查看入门手册的 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 命名约定；为了清晰起见，在本例中已严格使用输出。

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> 将根据逗号分隔的列表将您的节点与搜索结果匹配。例如，如果我们创建一个细分网格的节点，则我们可能需要添加诸如“mesh”、“subdivision”和“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; 并将 ZeroTouchLibrary NuGet 软件包添加到项目中，可参照项目中的“ProtoGeometry.dll”。

• 重要信息： 管理未从函数中返回的几何图形资源，请参见下面的 Dispose/using 语句部分。

注意：Dynamo 几何图形对象与传递给函数的任何其他对象一样使用。

获取曲线长度并使其加倍的节点。

1. 此节点接受曲线几何图形类型作为输入。

Dispose/using 语句

除非您使用的是 Dynamo 2.5 版或更高版本，否则不会从函数中返回的几何图形资源需要进行手动管理。在 Dynamo 2.5 及更高版本中，几何图形资源由系统进行内部处理；但是，如果您有复杂的用例，或者您必须在确定时间减少内存，则可能仍需要手动处理几何图形。Dynamo 引擎将处理从函数中返回的任何几何图形资源。可以通过以下方式手动处理未返回的几何图形资源：

• 使用 using 语句：

• 使用手动 Dispose 调用：

移植

发布库的较新版本时，节点名称可能会更改。可以在移植文件中指定名称更改，以便在完成更新后，基于库的以前版本构建的图形可以继续正常使用。通过以下方式实现移植：

• 在与 .dll 所在的同一个文件夹中创建 .xml 文件，其格式如下所示："BaseDLLName".Migrations.xml

• 在 .xml 中，创建单个 <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 2.0 是一个主要版本，一些 API 已更改或已删除。将影响节点和软件包作者的最大更改之一是我们转为使用 JSON 文件格式。

通常，Zero Touch 节点作者几乎无需进行任何操作，即可在 2.0 中运行其软件包。

UI 节点和直接从 NodeModel 派生的节点需要进行更多操作才能在 2.x 中运行。

扩展作者可能还要进行一些潜在更改，具体取决于他们在其扩展中使用的 Dynamo 核心 API 数量。

常规打包规则：

• 请勿将 Dynamo 或 Dynamo Revit .dll 与软件包捆绑在一起。这些 dll 会由 Dynamo 进行载入。如果捆绑的版本不同于用户已载入的版本 （即，您分发 Dynamo Core 1.3，但用户运行的是基于 Dynamo 2.0 的软件包），则会发生意外运行时错误。这包括诸如 DynamoCore.dll、DynamoServices.dll、DSCodeNodes.dll、ProtoGeometry.dll 之类的 dll

• 如果可以避免，请勿将 newtonsoft.json.net 与软件包捆绑在一起并分发。此 dll 也将由 Dynamo 2.x 载入。可能会出现与上述相同的问题。

• 如果可以避免，请勿将 CEFSharp 与软件包捆绑在一起并分发。此 dll 也将由 Dynamo 2.x 载入。可能会出现与上述相同的问题。

• 通常，如果需要控制依存关系的版本，请避免将该依存关系与 Dynamo 或 Revit 共享。

常见问题：

1) 打开图形时，一些节点有多个同名端口，但图形在保存时看起来正常。此问题可能有几个原因。

常见的根本原因是，节点是使用重新创建端口的构造函数创建的。反之，应使用已载入端口的构造函数。这些构造函数通常标记为 [JsonConstructor] 参见下文以了解示例

这可能是因为：

• 根本没有匹配的 [JsonConstructor]，或者未通过 JSON .dyn 给它传递 Inports 和 Outports。

• 有两个版本的 JSON.net 同时载入到同一进程中导致 .net 运行时失败，因此无法正确使用 [JsonConstructor] 属性来标记构造函数。

• 版本不同于当前 Dynamo 版本的 DynamoServices.dll 已与软件包捆绑在一起，并会导致 .net 运行时无法识别 [MultiReturn] 属性，因此标记有各种属性的 Zero Touch 节点将无法应用它们。您可能会发现，一个节点返回一个字典输出，而不是多个端口。

2) 在将存在一些错误的图形载入控制台后，节点会完全丢失。

• 如果反序列化因某种原因而失败，则可能会发生这种情况。最好仅序列化所需的特性。我们可以对不需要载入或保存的复杂特性使用 [JsonIgnore] 来忽略它们。诸如 function pointer, delegate, action, 或 event 之类的特性。由于这些特性通常无法反序列化并导致出现运行时错误，因此不应该对它们序列化。

全面升级：

自定义节点 1.3 - > 2.0

已知问题：

• 注释将转换为块注释，而不是行注释。

• 短类型名称将替换为完整名称。例如，如果再次载入自定义节点时未指定类型，则您会看到 var[]..[] - 因为这是默认类型。

Zero Touch 节点 1.3 -> 2.0

• 在 Dynamo 2.0 中，“列表”和“字典”类型已拆分，并且用于创建列表和字典的语法已更改。列表将使用 [] 初始化，而字典使用 {}。 如果以前使用 DefaultArgument 属性标记 Zero Touch 节点上的参数，并将列表语法默认用于特定列表（如 someFunc([DefaultArgument("{0,1,2}")])），则此语法将不再有效，需要修改 DesignScript 代码段以对列表使用新的初始化语法。

• 如上所述，请勿将 Dynamo DLL 与软件包一起分发。（DynamoCore、DynamoServices 等）。

节点模型节点 1.3 -> 2.0

节点模型节点需要做大量操作才能更新到 Dynamo 2.x。在较高级别上，除了用于实例化节点类型的新实例的常规 nodeModel 构造函数外，还需要实现将仅用于从 json 载入节点的构造函数。为了区分这些构造函数，请使用 [JsonConstructor]（来自 newtonsoft.Json.net 的属性）来标记载入时间构造函数。

JSON 构造函数

更新派生自 NodeModel 基类（或其他 Dynamo 核心基类，即 DSDropDownBase）的节点所需的最常见更改是需要将 JSON 构造函数添加到您的类中。

原始无参数构造函数仍将对在 Dynamo 中创建的新节点处理初始化（例如，通过库）。要初始化从保存的 .dyn 或 .dyf 文件反序列化 （载入） 的节点，需要使用 JSON 构造函数。

JSON 构造函数与基础构造函数的不同之处在于，它将 PortModel 参数用于 inPorts 和 outPorts，这些参数由 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 中读取。

这是 nodeModel 的 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 UI 节点实现复杂的撤消/重做功能，则需要实现这些方法并将其序列化到作为这些方法的参数提供的 XML 文档对象中。除了复杂的 UI 节点之外，这应该是一个罕见用例。

输入和输出端口 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 UI 节点升级到 Dynamo 2.x。

为了在 2.0 中正确载入和保存该 nodeModel 类，我们所需要做的就是添加一个 jsonConstructor 来处理端口的载入。我们只需在基础构造函数中传递端口，而这个实现是空的。

注意：请勿在 JsonConstructor 中调用 RegisterPorts() 或其某些变体 - 这将使用节点类中的输入和输出参数属性来构造新端口！由于我们希望使用传递给您的构造函数的已载入端口，因此我们不希望这样。

以下是 UI 节点的更复杂构造函数：

当我们添加用于从文件载入此节点的 JSON 构造函数时，我们必须重新创建该逻辑的一部分；但请注意，我们不会包括创建端口、设置连缀或设置特性的默认值（可以从文件载入）的代码。

请注意，已序列化到 JSON 中的其他公有特性（如 ButtonText 和 WindowText）将不会作为显式参数添加到构造函数中 - JSON.net 会使用这些特性的 setter 自动设置它们。

无论用户的经验水平如何，Dynamo 平台是专为所有用户设计的，旨在使他们都能够成为参与者。有多个针对不同能力和技能水平的开发选项，每个选项都有其优势和劣势，具体取决于目标。下面，我们将概述不同的选项以及如何选择其中一个。

三种开发环境：Visual Studio、Python 编辑器和代码块 DesignScript

我有哪些选项？

Dynamo 的开发选项主要分为两类：for（面向）Dynamo 与 in（使用）Dynamo。可以将这两个类别视为如下所述：“in”Dynamo 表示使用 Dynamo IDE 创建要在 Dynamo 中使用的内容，而“for”Dynamo 表示使用外部工具创建要输入到 Dynamo 中以供使用的内容。尽管本手册重点介绍 for Dynamo 开发，但下面介绍了适用于所有过程的资源。

For（面向）Dynamo

这些节点允许最高程度的自定义。许多软件包都是使用此方法构建的，它对于参与 Dynamo 的源代码而言必不可少。本手册将介绍构建这些软件包的过程。

• Zero-Touch 节点

• NodeModel 派生节点

• 扩展

本 Primer 提供了有关输入 Zero-Touch 库的指南。

在下面的讨论中，Visual Studio 将用作 Zero-Touch 和 NodeModel 节点的开发环境。

我们将要开发的项目的 Visual Studio 界面

In（使用）Dynamo

尽管这些过程存在于可视化编程工作空间中并且相对简单，但它们都是用于自定义 Dynamo 的可行选项。本 Primer 涵盖了这些内容，并在脚本编写策略一章中提供了脚本编写技巧和最佳实践。

• 代码块会在可视化编程环境中显示 DesignScript，从而支持灵活的文本脚本和节点工作流。代码块中的函数可由工作空间中的任何对象调用。

  下载代码块示例（单击鼠标右键，然后单击“另存为”），或在 Primer 中查看详细漫游。

• 自定义节点是节点集合甚至整个图形的容器。它们是收集常用例程并与社区共享这些例程的有效方式。

  下载自定义节点示例（单击鼠标右键，然后单击“另存为”），或在 Primer 中查看详细漫游。

• Python 节点是可视化编程工作空间中的脚本接口，类似于代码块。Autodesk.DesignScript 库使用与 DesignScript 类似的点表示法。

  下载 Python 节点示例（单击鼠标右键，然后单击“另存为”），或在 Primer 中查看详细漫游。

在 Dynamo 工作空间中开发是获得即时反馈的强大工具。

在 Dynamo 工作空间中使用 Python 节点开发

每种方法有哪些优点/缺点？

Dynamo 的开发选项旨在解决自定义需求的复杂性。无论目标是在 Python 中编写递归脚本还是构建完全自定义的节点 UI，都有一些选项可用于实现仅涉及启动和运行所需内容的代码。

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# 编写。尽管此方法提供了最大的灵活性和强大功能，但节点的大多数方面都必须明确定义，并且函数需要位于单独的程序集中。

使用此方法，我们可以：

• 使用滑块、图像、颜色等创建完全可自定义的节点 UI（例如 ColorRange 节点）

• 访问并影响 Dynamo 画布中发生的情况

• 自定义连缀

• 作为软件包载入到 Dynamo 中

了解 Dynamo 版本控制和 API 更改 (1.x → 2.x)

由于 Dynamo 会定期更新，因此可能会对软件包使用的 API 的一部分进行更改。跟踪这些更改对于确保现有软件包继续正常工作而言非常重要。

API 更改是在 Dynamo Github Wiki 上进行跟踪的。这包括对 DynamoCore、库和工作空间的更改。

举例来说，2.0 版中即将发生的重大更改是从 XML 文件格式转换为 JSON 文件格式。NodeModel 派生节点现在需要 JSON 构造函数，否则它们将无法在 Dynamo 2.0 中打开。

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

在软件包中分发二进制文件的权限

请注意，.dll 包含在要上传到软件包管理器的软件包中。如果软件包作者未创建 .dll，则他们必须有权共享它。

如果软件包包含二进制文件，则在下载时必须提示用户该软件包包含二进制文件。

扩展是 Dynamo 生态系统中一款功能强大的开发工具。它们允许开发人员基于 Dynamo 交互和逻辑来派生自定义功能。扩展可以分为两大类：扩展和视图扩展。顾名思义，视图扩展框架允许您通过注册自定义菜单项来扩展 Dynamo UI。除了 UI 之外，常规扩展的运行方式非常相似。例如。我们可以构建一个将特定信息记录到 Dynamo 控制台的扩展。此场景不需要自定义 UI，因此也可以使用扩展完成。

扩展案例研究

按照 DynamoSamples Github 存储库中的 SampleViewExtension 示例，我们将逐步介绍创建一个实时显示图形中活动节点的简单无模式窗口所需的步骤。视图扩展要求我们为窗口创建 UI，并将值绑定到视图模型。

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 相关事件的逻辑，并指示 UI 根据这些事件进行更新。将以下代码复制到 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，并会在工作空间添加或删除节点时触发事件。这将引发特性更改，通知 UI 或绑定图元：数据已更改并需要更新。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 文件

这是对视图扩展的基本介绍。有关更复杂的案例研究，请参见 DynaShape 软件包，它是 Github 上的开源项目。该软件包使用支持在 Dynamo 模型视图中实时编辑的视图扩展。

DynaShape 的软件包安装程序可以从 Dynamo 论坛下载：https://forum.dynamobim.com/t/dynashape-published/11666

源代码可以从 Github 克隆：https://github.com/LongNguyenP/DynaShape