简体中文
Primer for v2.0

进一步了解 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());
    }
}
Previous在 Zero-Touch 节点中执行 Python 脚本 (C#)NextNodeModel 案例研究 - 自定义 UI

Last updated