跳到主要内容
版本：1.0.0

二次开发 SDK（C#）

ToolBank 对外提供一套 C# 二次开发 API，封装在单 DLL MainUI.ToolBank.ClientSdk（命名空间 ToolBank.Sdk）中：你可以让自己的程序驱动 ToolBank 运行 Job、读写变量、查询程序结构，把 ToolBank 当作一个“视觉处理引擎”嵌入到自己的系统里。

三条 API 线​

入口是单例 ToolBankSdk.Instance，按能力分三条线，各管各的职责：

线定位典型能力
A 线 · 程序执行驱动运行运行全部 / 单 Job / 算子区间 / 单步；重复运行 N 次并在每轮前换参；读各算子执行状态
B 线 · 变量读写数据进出按变量名读写整数 / 浮点 / 字符串 / 点 / 线 / 矩形 / 圆 / 椭圆 / 多边形 / 图像 / 区域掩码
Q 线 · 只读查询摸清结构当前程序路径、Job 结构、变量清单

运行约束（重要）​

SDK 必须与 ToolBank 运行期同进程、同 AppDomain：它通过在 WPF 可视树中定位宿主控件获取上下文，因此典型形态是：

  • 插件内使用：在控件插件 / 宿主扩展里调用（推荐方式，见 控件插件）；
  • 独立交付：不能用外部分发的方式直接 new 一个宿主——需要自包含运行期的场景请使用 二次开发 → 导出CS程序 生成的工程（见 导出 CS 程序），导出工程内部已把 SDK 与运行期打包好。

A 线：程序执行​

方法说明
JobRunResult RunAll()运行当前程序全部 Job；任一 Job 失败抛 ToolBankSdkException
JobRunResult RunJob(string jobName)按名称运行单个 Job
JobRunResult RunJob(string jobName, int startIdx, int endIdx)运行算子区间（endIdx=-1 到末尾）
ToolRunResult RunOperator(string jobName, int toolIdx)运行单个算子
ToolStepResult StepOperator(string jobName, int toolIdx, out int nextToolIndex)单步执行，返回下一步索引
int[] GetLastJobStates(string jobName)各算子上次执行状态（0 未执行 / 1 成功 / 2 跳过 / 3 失败 / 4 禁用）
string GetLastError()底层最近一次报错
void SetIterationCounter(int value)设置迭代计数器（“循环跑 N 次”的循环变量）
RepeatRunIteration[] RepeatRun(string jobName, int times, Action<int> onBefore)同一 Job 反复执行；onBefore 每轮前换参
LoadFileResult LoadFile(string filePath, ...)复用加载类算子把本地文件读入变量池

B 线：变量读写​

统一签名 Set*(jobName, variableName, data) / Get*(jobName, variableName)；变量是全局共享时 jobName 可传任意值（按名定位，找不到回退首个 Job）。

类型Set / GetSDK 包装类型
整数数组SetIntList / GetIntListint[]
浮点数组SetDoubleList / GetDoubleListdouble[]
字符串数组SetStringList / GetStringListstring[]
二维点SetPoint2DList / GetPoint2DListPoint2D[]
三维点SetPoint3DList / GetPoint3DListPoint3D[]
线段SetLine2DList / GetLine2DListLine2D[]
矩形SetRectangle / GetRectangleRectShape?
圆SetCircle / GetCircleCircleShape?
椭圆SetEllipse / GetEllipseEllipseShape?
多边形SetPolygon / GetPolygonPolygonShape
图像GetImageInfo / GetImageAt / GetImageFrameCountImageVariableInfo / DImage
区域掩码SetRegionMask / GetRegionCount / GetRegionMaskbyte[][]（0/255 像素）
任意类型转字符串GetAsStringstring

变量管理：DeleteVariable(name)、RenameVariable(old, new)、VariableExists(name)。

几何类型用结构体承载，底层以扁平 double[] 传输（与内核格式一致，跨语言无需中间转换）。Region 收敛为 0/255 像素掩码后，SetRegion/GetRegion 已废弃，改用矩形 / 圆 / 多边形或 SetRegionMask。

Q 线：只读查询​

成员说明
bool HasCurrentProgram当前是否有可运行的程序
string CurrentProgramFilePath当前程序文件绝对路径
IReadOnlyList<JobInfo> Jobs全部 Job 摘要（名称 / 描述 / 算子名 / 上次状态）
JobInfo GetJobInfo(string jobName)单个 Job 摘要
IReadOnlyList<VariableInfo> Variables全部变量元信息（名称 / 类型）

数据类型与异常​

  • 几何：Point2D / Point3D / Line2D / RectShape / CircleShape / EllipseShape / PolygonShape；
  • 结果：JobRunResult（Success / FailedToolIndex / ToolConsumedTimes / ExecutionStates / ErrorMessage / TotalMilliseconds）、ToolRunResult、ToolStepResult、RepeatRunIteration（Tag 可回写自定义上下文）；
  • 查询：JobInfo / VariableInfo（含 VariableType 枚举）/ ImageVariableInfo；
  • 异常：ToolBankSdkException（Message 为底层 LastMsg，JobName / ToolIndex / RawLastMessage 供定位）。

调用示例​

using ToolBank.Sdk;

var sdk = ToolBankSdk.Instance;

// 1. 跑整个程序
var r = sdk.RunAll();
Console.WriteLine($"运行完成，耗时 {r.TotalMilliseconds:0}ms");

// 2. 指定 Job 循环跑 3 次，每轮前换输入
var iterations = sdk.RepeatRun("Main", 3, i =>
    sdk.SetIntList("Main", "SrcImagePath", new[] { i + 1 }));

// 3. 读结果
double[] scores = sdk.GetDoubleList("Main", "Score");
string text     = sdk.GetAsString("Main", "Result");
var info        = sdk.GetImageInfo("Main", "OutImage");
Console.WriteLine($"图像 {info.Width}x{info.Height}x{info.Channels}");

// 4. 查状态
var states = sdk.GetLastJobStates("Main");   // 0 未执行 / 1 成功 / 2 跳过 / 3 失败 / 4 禁用

常见问题​

为什么在外部程序里调用 SDK 报“找不到宿主”类错误？

SDK 依赖与 ToolBank 同进程运行。外部独立进程应改用「导出 CS 程序」生成的自包含工程（自带运行期），而不是直接引用 SDK 驱动主程序。

读写变量的 jobName 怎么传？

变量池全局按名寻址。变量名唯一时 jobName 传任意值即可；若不同 Job 存在同名变量，SDK 会先按给定 jobName 找，找不到回退首个 Job。推荐始终传真实 Job 名。

RunAll 中途一个算子失败了会怎样？

抛出 ToolBankSdkException，其 JobName / ToolIndex 指明失败位置，Message / RawLastMessage 为底层错误详情。用 try/catch 接住即可做失败处理。