自定义节点类型

自定义节点类型用于扩展规则引擎可编排节点。用户创建节点、维护处理逻辑和参数定义，编译成功后即可在规则流程中拖入使用。

创建前准备

先看术语

术语	现场理解
自定义节点类型	现场或项目自定义的规则功能块，编译成功后可拖入规则流程。
节点实例	某个规则流程画布中实际拖入使用的节点。它引用一个节点类型。
输入参数	上游节点传给当前节点的数据。
输出参数	当前节点处理后传给下游节点的数据。
输入输出参数	既能接收上游数据，也能在节点内部修改后继续传递的数据。
编译	检查节点代码和参数定义能否被网关加载。编译成功后，规则流程才能使用最新节点。
分类	在规则节点面板中分组显示节点，便于现场快速查找。

页面入口

登录 TGateway Web 后，点击左侧菜单“开发配置 → 自定义节点”。

使用前准备

• 明确节点的输入、输出、异常处理和允许的副作用，先用最小参数集合设计。
• 确认节点名称和分类不会与已加载节点混淆，并记录哪些规则流程将引用它。
• 修改已在生产流程中使用的节点前，先导出相关规则流程并安排验证窗口。

配置与编译节点

页面结构

区域	说明
本地节点	管理已保存的自定义节点类型，支持新增、编辑、编译、删除和批量操作。
已加载节点	查看已经可在规则流程中使用的节点类型，适合确认编译结果是否生效。
名称搜索	按节点名称过滤。
分类筛选	按节点分类过滤。
工具按钮	依次为新增、批量编译、批量删除、刷新；批量操作需要先勾选节点。

列表字段

字段	说明
节点名称	节点类型名称，规则流程中按此名称查找和使用。
分类	节点分类，便于在规则编排时组织节点。
输入参数	当前节点定义的输入参数数量。
输出参数	当前节点定义的输出参数数量。
输入输出参数	既可输入又可输出的参数数量。
更新时间	最近一次保存或编译时间。
操作	编辑、编译、删除当前节点。

新建节点

点击列表右上角新增按钮，打开“新建自定义节点”弹窗。

配置项	说明
节点名称	必填。建议使用英文、数字和下划线，保持规则流程引用稳定。
分类	可选。用于按业务或处理类型组织节点。
描述	可选。记录节点用途、输入输出约定和维护注意事项。

点击“确定”后，系统会创建节点并自动进入节点编辑器。

节点编辑器

节点编辑器包含顶部操作栏、代码编辑区和底部信息面板。

区域	说明
返回按钮	返回自定义节点列表。
节点名称标签	显示当前节点名称和分类。
顶部工具栏	Roslyn 服务、撤销、重做及编译按钮集中在同一行。连接配置默认隐藏，点击“Roslyn 服务”可展开或收起。
编译并保存	顶部右侧主按钮。先保存节点信息和处理逻辑，再执行编译。
代码编辑	维护节点处理逻辑。
底部面板	包含“编译日志”“节点信息”“参数定义”页签。

输入 this. 可补全当前节点中的用户方法、字段和参数属性；输入调用的括号和逗号后可查看参数说明。为方法、字段或属性添加 /// XML 注释后，补全与悬停可显示业务说明。默认语言服务为 https://roslyn.thingsgateway.cn，也可连接自建 Studio，详见代码编辑、补全与错误定位。

节点信息

“节点信息”页签用于维护基础信息。

字段	说明
节点名称	节点显示和引用名称。修改后需要编译保存。
分类	节点分类。
描述	节点用途和维护说明。

参数定义

“参数定义”页签按输入、输出、输入输出三类维护参数。参数定义会影响规则流程中节点的连线和数据传递。

参数类型	说明
输入参数	从上游节点传入，节点内部读取使用。
输出参数	节点处理后输出，供下游节点使用。
输入输出参数	同时作为输入和输出，适合需要在节点内部修改后继续传递的值。

参数字段	说明
参数名	参数标识，建议使用清晰的英文或拼音命名。
数据类型	参数值类型。数字选择整数或小数类型，开关量选择布尔类型，文本选择字符串，需要传递结构化内容时选择对象类型。
描述	参数用途说明。

可按业务选择 Int16、Int32、Int64、UInt16、UInt32、UInt64、Byte、Float、Double、Decimal、Boolean、String、Object 和 DateTime。输入、输出和输入输出三种方向分别定义类型；端口名字同时参与代码引用和连线，修改名字时应同步修改代码及所有使用流程。

“初始值表达式”使用 C# 表达式，例如 Decimal 可用 1m + 1m。画布中显式输入和上游连线会覆盖该起点。描述用于解释参数，不改变数值；整数还需检查范围，日期应明确时区，对象应保留实际结构。

编译日志

点击顶部“编译并保存”后，底部“编译日志”会显示保存和编译过程。

日志项	说明
正在保存节点	编译前先保存当前节点信息、代码和参数定义。
节点保存成功	保存成功后开始编译。
编译成功	自定义节点代码通过编译。
输出	显示编译输出信息，便于排查加载问题。
错误 / 警告统计	底部面板右侧显示当前错误和警告数量。

出现编译错误时，先处理第一条红色错误；点击错误项可定位到对应代码位置。

“节点保存成功”表示当前源码和参数已保存，后续仍可能编译失败。失败草稿可以重新打开继续修改；原已发布的有效节点文件和注册不会被失败产物替换。修正后再次编译，并检查“已加载节点”及使用该类型的流程。已有流程实例是否使用了新逻辑，还需按下方步骤重新装载并验证。

如果提示节点已被其他编辑修改，先保留自己的草稿，再重新读取当前版本进行核对，避免覆盖另一位维护人员的修改。

常用操作

操作	步骤
编辑节点	在列表点击“编辑”，进入编辑器维护代码、节点信息或参数定义。
单个编译	在列表点击“编译”，验证当前节点是否可编译。
批量编译	勾选多个节点后点击批量编译，适合升级后统一验证。
删除节点	点击“删除”并确认。删除前应确认规则流程不再引用该节点。
查看已加载节点	切换到“已加载节点”，确认运行时已经注册的节点。

验证节点行为

初始参数、状态与事件端口

参数定义决定画布端口，流程配置决定某个实例的实际输入。参数的“初始值表达式”由节点编译时使用；流程中显式填写的初始输入或上游连线会覆盖该起点。修改参数定义后，应编译当前节点，并重新检查使用它的流程。

参数设置	使用方法
输入	从上游接受值；没有连线时，按界面要求填写实例输入。
输出	把处理结果送到下游；默认状态输出仅在值变化时传播。
输入输出	同时接受上游值并向下游传播，适合需要更新后继续传递的状态。
事件端口	表达一次发生，即使值与上次相同也可再次消费；连线两端应使用相同的事件语义。事件参数不填写状态初始值。

例如两次输入 10.1、10.2，节点均向下取整得到 10：状态输出的下游次数可以保持，事件输出的下游应分别收到两次。比较运行输入、输出和下游次数，才能区分“没有计算”和“结果相同没有传播”。

在流程中验证一个换算节点

1. 在 Web 节点中定义 Decimal 输入 Input 和输出 Output，处理方式使用增益 2、偏置 5。成员代码写法见开发示例。
2. 编译保存后，在“已加载节点”确认当前名称、分类和两个端口；只在本地列表存在还不足以进入流程。
3. 新建暂时禁用的测试流程，依次连接限定来源的变量通知、数值提取、当前节点及下游接收节点。
4. 保存并启用，输入 10 应得到 25，再输入 20 应得到 45；分别核对节点输出、下游输入和执行结果。
5. 如增加输入输出状态或计数，重新启用后应从定义的初始状态开始；需要跨重启保存时另行设计持久化。

Web 编辑器负责生成参数属性，成员代码不应再次声明相同参数或包装一层完整类。使用完整 C# 类时，从脚本管理的完整代码入口编译，按完整类节点定义身份、参数与输出传播，再到已加载节点及实际流程验收。

修改后的运行检查

1. 编译并保存后，在“已加载节点”核对名称、分类和端口类型。新增或删除参数后重新检查每条连线和实例参数。
2. 在独立测试流程中使用两个不同输入。例如平方节点输入 3、5，应依次输出 9、25，下游节点也应收到。
3. 修改同名节点的计算方式并重新编译后，已有流程可能仍运行之前装载的实例。保存并重新装载该流程，再用能区分新旧公式的输入验收。
4. 禁用流程后确认没有活动实例继续消费输入；重新启用会建立新实例，内存计数和初始化状态重新开始，不会自动持久化。
5. 删除节点前，先从所有流程定义中解除引用；只禁用流程仍保留引用，不能作为删除前的解除操作。

Web 节点编辑器、完整 C# 类节点的写法及生命周期要求见自定义节点开发说明。编译、装载、流程绑定和下游反馈四步都完成后，再应用到业务流程。

编译与运行验证

1. 点击“编译并保存”，确认保存日志和编译日志均无错误。
2. 切换到“已加载节点”，确认节点名称、分类和参数已经出现。
3. 在规则引擎中新建最小测试流程，连接输入、当前节点和输出节点。
4. 保存并启用流程，触发一组已知输入，观察节点实时参数和运行日志。
5. 输出值、参数类型和异常处理均符合设计后，再把节点用于正式流程。

只通过编译不代表节点行为正确；未完成规则流程中的实际触发验证时，节点仍不应视为交付完成。

常见问题与注意

场景	建议
参数修改	修改参数后，应同步检查引用该节点的规则流程连线。
分类维护	分类会影响节点查找效率，建议按业务域或功能类型分类。
编译失败	先查看保存日志，再查看编译诊断；保存失败时不会进入真正编译。
节点未出现在规则中	确认节点已编译成功，并刷新规则引擎页面或重新打开流程编辑器。
生产删除	删除前先导出或备份规则流程，避免留下不可解析的节点引用。

相关链接

• 规则引擎
• 自定义节点开发说明
• 脚本管理
• 采集配置