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# 中的工廠模式

另請參閱：

• 關於外掛開發的一般說明。