C# 技巧

为 Divooka 插件编写 C# 代码时，遵循一些惯用模式并使用 XML 注释，可以确保你的方法和类型在图编辑器中清晰地呈现。在 Divooka 中，任何打算作为独立节点公开的方法都应声明为 public static 函数。由于静态方法不持有实例状态，Divooka 会自动生成一个节点，其输入引脚对应方法的参数，主输出引脚则反映方法的返回类型。例如，考虑一个计算平方的简单静态方法：

/// <summary>
/// Returns the square of an integer.
/// </summary>
public static int Square(int x) => x * x;

加载这段代码后，Divooka 会呈现一个名为“Square”的节点，它有一个输入（类型为 int 的 x）和一个以其类型命名的输出 Integer，无需任何额外的连线或样板代码。

除了返回值之外，C# 的 out 参数也作为额外的输出引脚受到支持。如果你像这样声明一个方法：

/// <summary>
/// Divides an integer and returns quotient and remainder.
/// </summary>
public static int Divide(int dividend, int divisor, out int remainder)
{
    remainder = dividend % divisor;
    return dividend / divisor;
}

Divooka 会创建两个输出——一个对应返回值（商），一个对应 out 参数（remainder）。关键在于，out 参数不会作为节点的输入出现，而是自动成为额外的输出引脚。这样就能直接公开返回多个值的方法，而不会让节点的输入侧变得杂乱。

相比之下，实例方法默认是隐藏的，除非你明确选择公开。要在纯数据流图中公开一个实例方法（使其表现得像静态函数一样），请在其 XML 文档中添加 <const>true</const>。例如：

public class MathHelpers
{
    /// <summary>
    /// Adds two numbers together.
    /// </summary>
    /// <const>true</const>
    public int Add(int a, int b) => a + b;
}

有了 <const>true</const>，Divooka 会把 Add 当作静态方法处理——显示一个接受两个整数并返回其和的节点。省略 <const> 则告诉 Divooka 该方法可能依赖内部状态或副作用，因此它只在维护着显式对象实例的过程式上下文中可用。

XML 文档是节点元数据（工具提示、显示名称、输入格式等）的权威来源。Divooka 能识别以下几种标签和特性：

<summary> 和 <remarks> 用于填充节点的工具提示或帮助面板，为用户提供上下文指导。
<param name="…" textFormat="…"> 控制 Divooka 如何呈现或约束该参数——例如，textFormat="text" 表示纯文本，textFormat="Password" 用于遮盖敏感输入。
<snap>URL</snap> 链接到一张截图，它会显示在节点的文档窗格中，帮助最终用户一目了然地理解用法。
<hidden>true</hidden> 阻止该方法或类型出现在工具箱中，即使它原本是可被发现的。
<const>true</const>（用于实例方法）强制 Divooka 在数据流图中将该方法视为纯函数。

例如，如果你这样写：

/// <summary>
/// Executes a query and returns a DataGrid.
/// </summary>
/// <snap>https://cdn.example.com/snaps/QueryNode.png</snap>
public static DivookaDataGrid Query(string sql, ODBCConfiguration? config = null)
{
    // Implementation omitted…
}

Divooka 会将“Executes a query and returns a DataGrid”显示为工具提示，并在用户查看节点文档时显示所引用的图片。如果你添加 <hidden>true</hidden>，即使满足其他公开条件，Divooka 也会将该方法从面向用户的工具箱中完全隐藏。

Divooka 还支持基于委托的节点：如果一个静态方法或实例方法包含 Func<…> 或 Action<…> 参数，该参数在图中就会成为一个 lambda 占位符。例如：

/// <summary>
/// Applies a lambda to each element in an integer array.
/// </summary>
public static int[] Map(int[] items, Func<int, int> transformer)
{
    return items.Select(transformer).ToArray();
}

拖入图中后，“Map”会显示一个 items 输入、一个 transformer 子图占位符和一个 int[] 输出。在底层，Divooka 会把用户的子图编译为委托，并在运行时将其应用于每个元素。

泛型方法和泛型类型同样会变成节点。例如这样一个方法

public static T Identity<T>(T value) => value;

是一个带有 T 选择块的节点：在其上选择一个类型，或者将一个值连入 value，T 就会根据连入的值推断出来。

最后，Divooka 在填充工具箱时不识别继承层次结构或多态分派。如果你定义了一个基类和一个派生类，它们都实现了 Compute(double)，Divooka 会把两者分别列出；它不会将它们合并到一个共享的“Compute”节点下，也不会执行基于运行时类型的分派。如果你需要多态行为，请实现显式的包装方法，或利用过程式上下文在运行时检查类型。

XML 标签和特性

下面汇总了为 Divooka 注释 C# 代码时最有用的 XML 标签和特性。编写文档注释时，可将其用作快速参考：

标签 / 特性	用途	说明
`<summary>…</summary>`	提供节点的主要描述。	在图编辑器中显示为工具提示文本。
`<remarks>…</remarks>`	提供额外的说明文字。	显示在详细文档窗格中，位于摘要下方。
`<param name="…" …>…</param>`	描述一个参数及其输入格式（可选）。	特性：`textFormat="text"`（纯文本）、`textFormat="Password"`（遮盖输入）、`default="White"`（用于默认值，例如颜色）等。
`<snap>URL</snap>`	嵌入截图或插图的 URL。	Divooka 会在节点的文档窗格中显示这张图片，作为直观的指导。
`<hidden>true</hidden>`	在工具箱中隐藏该方法或类型。	即使其他条件会公开它，此标签也会强制 Divooka 将其从界面中省略。
`<const>true</const>`	将实例方法标记为数据流上下文中的纯函数。	没有此标签时，实例方法只能在过程式上下文中使用。
`<name>…</name>`	覆盖节点的标题。	如果省略，标题就是成员名拆分成单词后的形式：`DiameterOf` 显示为 Diameter Of。
`<returns name="…">…</returns>`	为返回类型命名或加以描述。	很少需要——Divooka 会自动推断返回类型；仅在需要声明自定义的返回引脚名称时使用。

请始终如一地使用这些标签，这样当用户把你的自定义节点拖入图中时，就能获得精致且自带文档的体验。

待办事项：

补充关于可序列化为字符串的复合类型的默认值的说明。
补充关于绕过 C# 位置参数限制的参数默认值的说明。

文本格式

格式	名称	描述
文本框	textFormat="text"	显示多行文本框，而不是单行文本框。
密码输入	textFormat="password"	显示一个单行文本框，字符以掩码符号显示。
图名称选择器	textFormat="graphPicker"	弹出图选择器。
资源路径选择器	textFormat="assetPath"	弹出资源路径选择器。

参考资料

C# 中的工厂模式

另请参阅：

关于插件开发的一般说明。