进一步了解 Zero-Touch
在了解如何创建 Zero-Touch 项目后,我们可以通过浏览 Dynamo Github 中的 ZeroTouchEssentials 示例,来更深入地了解创建节点的具体细节。
Dynamo 的许多标准节点本质上都是 Zero-Touch 节点,就像上面的大多数 Math、Color 和 DateTime 节点一样。
首先,从以下位置下载 ZeroTouchEssentials 项目:https://github.com/DynamoDS/ZeroTouchEssentials
在 Visual Studio 中,打开 ZeroTouchEssentials.sln
解决方案文件并构建解决方案。
ZeroTouchEssentials.cs
文件包含我们将要输入到 Dynamo 中的所有方法。
打开 Dynamo 并输入 ZeroTouchEssentials.dll
,以获取我们将要在以下示例中参照的节点。
代码示例拉取自 ZeroTouchEssentials.cs,通常与之匹配。为了保持简洁,已删除 XML 文档;每个代码示例都会在其上方的图像中创建节点。
默认输入值
Dynamo 支持为节点上的输入端口定义默认值。如果端口没有连接,则这些默认值会提供给节点。默认值是使用《C# 编程手册》中指定可选参数的 C# 机制来表示的。通过以下方式指定默认值:
将方法参数设置为默认值:
inputNumber = 2.0
将光标悬停在节点输入端口上方时,即会显示默认值
返回多个值
返回多个值比创建多个输入要复杂得多,并且需要使用字典返回。字典的条目会成为节点输出端的端口。通过以下方式创建多个返回端口:
添加
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>
请参见 ZeroTouchEssentials.cs 中的此代码示例
返回多个输出的节点。
请注意,现在有两个输出端口,它们是根据我们为字典的键输入的字符串命名的。
文档、工具提示和搜索
最佳做法是向 Dynamo 节点添加描述节点的功能、输入、输出、搜索标记等的文档。这是通过 XML 文档标记实现的。通过以下方式创建 XML 文档:
任何前面带有三个正斜杠的注释文字都会被视为文档
例如:
/// Documentation text and XML goes here
在三个斜杠之后,在 Dynamo 输入 .dll 时将读取的方法上方创建 XML 标记
例如:
/// <summary>...</summary>
在 Visual Studio 中,通过选择
Project > Project Properties > Build
并选中XML documentation file
来启用 XML 文档
Visual Studio 将在指定位置处生成 XML 文件
标记的类型如下所示:
/// <summary>...</summary>
是节点的主文档,将在左侧搜索栏中作为工具提示显示在节点上方/// <param name="inputName">...</param>
将为特定输入参数创建文档/// <returns>...</returns>
将为输出参数创建文档/// <returns name = "outputName">...</returns>
将为多个输出参数创建文档/// <search>...</search>
将根据逗号分隔的列表将您的节点与搜索结果匹配。例如,如果我们创建一个细分网格的节点,则我们可能需要添加诸如“mesh”、“subdivision”和“catmull-clark”之类的标记。
以下是一个示例节点,其中包含输入和输出描述,以及将在库中显示的摘要。
请参见 ZeroTouchEssentials.cs 中的此代码示例
请注意,此示例节点的代码包含:
节点摘要
输入描述
输出描述
对象
Dynamo 没有 new
关键字,因此需要使用静态构造方法来构造对象。通过以下方式构造对象:
除非另有要求,否则使构造函数成为内部构造函数
internal ZeroTouchEssentials()
使用静态方法构造对象,例如
public static ZeroTouchEssentials ByTwoDoubles(a, b)
注意:Dynamo 使用“By”前缀来指示静态方法是构造函数;尽管这是可选方法,但使用“By”将帮助您的库更好地适应现有 Dynamo 样式。
请参见 ZeroTouchEssentials.cs 中的此代码示例
在已输入 ZeroTouchEssentials dll 后,库中会有一个 ZeroTouchEssentials 节点。可以使用 ByTwoDoubles
节点创建此对象。
使用 Dynamo 几何图形类型
Dynamo 库可以使用原生 Dynamo 几何图形类型作为输入,并创建新的几何图形作为输出。通过以下方式创建几何图形类型:
通过在 C# 文件顶部包含
using Autodesk.DesignScript.Geometry;
并将 ZeroTouchLibrary NuGet 软件包添加到项目中,可参照项目中的“ProtoGeometry.dll”。重要信息: 管理未从函数中返回的几何图形资源,请参见下面的 Dispose/using 语句部分。
注意:Dynamo 几何图形对象与传递给函数的任何其他对象一样使用。
请参见 ZeroTouchEssentials.cs 中的此代码示例
获取曲线长度并使其加倍的节点。
此节点接受曲线几何图形类型作为输入。
Dispose/using 语句
除非您使用的是 Dynamo 2.5 版或更高版本,否则不会从函数中返回的几何图形资源需要进行手动管理。在 Dynamo 2.5 及更高版本中,几何图形资源由系统进行内部处理;但是,如果您有复杂的用例,或者您必须在确定时间减少内存,则可能仍需要手动处理几何图形。Dynamo 引擎将处理从函数中返回的任何几何图形资源。可以通过以下方式手动处理未返回的几何图形资源:
使用手动 Dispose 调用:
移植
发布库的较新版本时,节点名称可能会更改。可以在移植文件中指定名称更改,以便在完成更新后,基于库的以前版本构建的图形可以继续正常使用。通过以下方式实现移植:
在与
.dll
所在的同一个文件夹中创建.xml
文件,其格式如下所示:"BaseDLLName".Migrations.xml在
.xml
中,创建单个<migrations>...</migrations>
元素在移植元素内,为每个名称更改创建
<priorNameHint>...</priorNameHint>
元素对于每个名称更改,请提供
<oldName>...</oldName>
和<newName>...</newName>
元素
单击鼠标右键,然后选择
Add > New Item
选择
XML File
对于此项目,我们会将移植文件命名为
ZeroTouchEssentials.Migrations.xml
此示例代码会告知 Dynamo,任何名为 GetClosestPoint
的节点现在都已命名为 ClosestPointTo
。
请参见 ProtoGeometry.Migrations.xml 中的此代码示例
泛型
Zero-Touch 当前不支持使用泛型。可以使用这些泛型,但无法在直接输入且未设置类型的代码中使用它们。不能公开属于泛型且未设置类型的方法、特性或类。
在下面的示例中,将不会输入类型为 T
的 Zero-Touch 节点。如果库的其余部分输入到 Dynamo 中,则会出现丢失的类型异常。
使用在本例中所设置类型的泛型类型将输入到 Dynamo 中。
Last updated