进一步了解 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

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 并选中 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”之类的标记。

以下是一个示例节点,其中包含输入和输出描述,以及将在库中显示的摘要。

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 没有 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; 并将 ZeroTouchLibrary NuGet 软件包添加到项目中,可参照项目中的“ProtoGeometry.dll”。

  • 重要信息: 管理未从函数中返回的几何图形资源,请参见下面的 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 语句:

    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 调用:

    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 文件,其格式如下所示:"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

<?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());
    }
}

Last updated