脚本管理
脚本管理用于维护网关运行时脚本。脚本可用于变量数据转换、内存变量计算、数据转发模板、动态 SQL（自定义入库语句或表结构）、MQTT RPC（MQTT 反向写入或查询请求）等场景。脚本保存后需要编译成功，相关功能才会使用最新内容。
先看术语
| 术语 | 现场理解 |
|---|---|
| 脚本 | 网关内部可复用的计算或转换逻辑，用来处理变量值、生成上传内容或处理外部请求。 |
| 编译 | 检查脚本能否被网关运行。编译失败时，相关变量、规则或转发不会使用新内容。 |
| 数据转换 | 把设备原始值换算成现场需要的工程值，例如比例换算、单位转换、状态文本转换。 |
| 内存变量脚本 | 计算网关内部变量的脚本，不直接读取 PLC，而是读取已有变量或内部状态。 |
| 动态模型 / 模板 | 按外部系统约定的格式生成上传内容，例如自定义 JSON 字段、设备字段或报警字段。 |
| 动态 SQL | 自定义写入数据库的语句或表结构，常用于项目要求固定宽表或特殊字段命名的场景。 |
| MQTT RPC | 通过 MQTT 接收外部系统的写入、查询或控制请求，并由脚本解析和返回结果。 |
| 完整代码 | 高级扩展方式。需要理解 C# 代码和运行影响，普通现场配置不建议从这里开始。 |
页面入口
登录 GatewayRuntime Web 后，点击左侧菜单“开发配置 → 脚本管理”。
页面结构
| 区域 | 说明 |
|---|---|
| 本地脚本 | 维护当前运行时保存的脚本，支持新增、编辑、编译、删除和批量操作。 |
| 已加载脚本 | 查看已经可被网关使用的脚本，只读展示名称、分类、类型和数据类型等信息。 |
| 名称搜索 | 按脚本名称过滤列表。 |
| 分类筛选 | 按脚本分类过滤，本地分类来自已保存脚本。 |
| 类型筛选 | 按脚本类型过滤，例如数据转换、内存变量、MQTT RPC。 |
| 工具按钮 | 依次为新增、批量编译、批量删除、刷新；批量按钮需要先勾选脚本。 |
列表字段
| 字段 | 说明 |
|---|---|
| 名称 | 脚本在系统中的唯一名称。 |
| 分类 | 用于按业务、设备或用途组织脚本，可为空。 |
| 类型 | 脚本表达式类型，决定编辑器模板、可用输入和后续引用方式。 |
| 更新时间 | 最近一次保存或编译写库时间。 |
| 操作 | 编辑、编译、删除当前脚本。 |
新建脚本
点击列表右上角新增按钮，打开“新建脚本”弹窗。
| 配置项 | 说明 |
|---|---|
| 脚本名称 | 必填。建议使用英文、数字和下划线，名称保存后会被变量、规则、数据转发或 RPC 配置引用，不建议频繁修改。 |
| 脚本类型 | 必填。选择后弹窗底部会显示对应编写提示。 |
| 分类 | 可选。可以选择已有分类，也可以直接输入新分类。 |
| 描述 | 可选。记录脚本用途、引用位置和维护注意事项。 |
| 类型说明 | 只读提示，说明当前脚本类型的用途和编写要求。 |
点击“确定”后，系统会创建脚本并自动进入脚本编辑器。
脚本类型
| 类型 | 适用场景 |
|---|---|
| 数据转换 | 对采集变量的原始值做单位换算、格式化、范围映射或状态转换。 |
| 内存变量 | 计算内存变量，可读取其它变量后生成派生结果。 |
| 动态模型-变量数据 | 为变量数据转发生成自定义上传对象。 |
| 动态模型-设备数据 | 为设备状态转发生成自定义上传对象。 |
| 动态模型-告警变量 | 为报警数据转发生成自定义上传对象。 |
| 动态模型-插件事件 | 为插件事件转发生成自定义上传对象。 |
| 动态 SQL-* | 按变量、设备、报警或插件事件维度自定义入库逻辑。 |
| MQTT RPC | 处理 MQTT RPC 消息，适合需要按现场约定解析消息和组织应答内容的写入场景。 |
| 完整代码 | 编写完整 C# 代码，适合高级扩展。使用前应先确认编译要求和运行影响。 |
脚本编辑器
脚本编辑器包含顶部操作栏、代码编辑区和底部信息面板。
| 区域 | 说明 |
|---|---|
| 返回按钮 | 返回脚本列表。未保存内容应先执行编译保存。 |
| 脚本名称标签 | 显示当前脚本名称、分类和脚本类型。 |
| 编译并保存 | 顶部右侧主按钮。执行编译，成功后保存脚本并加载编译结果。 |
| 代码编辑 | 维护 C# 代码，支持语法高亮、撤销、重做和注释切换。 |
| 底部面板 | 包含“编译日志”“节点信息”“输入参数”页签。 |
底部页签
| 页签 | 说明 |
|---|---|
| 编译日志 | 显示编译过程、错误、警告和成功信息。点击错误或警告可定位到对应代码位置。 |
| 节点信息 | 维护脚本名称和分类。修改后需要编译保存才会持久化。 |
| 输入参数 | 仅“数据转换”和“内存变量”类型显示。用于定义可配置参数。 |
输入参数字段
| 字段 | 说明 |
|---|---|
| 参数名 | 参数标识，脚本中按该名称读取。 |
| 数据类型 | 参数值类型。数字选择整数或小数类型，开关量选择布尔类型，文本选择字符串，时间选择日期时间；应与脚本实际输入值保持一致。 |
| 初始值 | 参数默认值，留空时按类型默认处理。 |
| 描述 | 参数用途说明，便于后续维护。 |
编译日志
点击顶部“编译并保存”后，底部“编译日志”页签会显示完整过程。
| 日志项 | 说明 |
|---|---|
| 开始编译脚本 | 标记本次编译开始，并显示脚本名称。 |
| 脚本类型 | 显示当前表达式类型，例如“数据转换”。 |
| 编译成功 | 表示脚本已经通过编译。 |
| 编译输出 | 显示编译输出信息，用于现场排查加载问题。 |
| 错误 / 警告统计 | 底部面板右侧会显示错误和警告数量。 |
编译失败时，应先处理红色错误；警告不一定阻止编译，但建议在上线前一并处理。
常用操作
| 操作 | 步骤 |
|---|---|
| 编辑脚本 | 在列表中点击“编辑”，进入编辑器，修改代码或参数后点击“编译并保存”。 |
| 单个编译 | 在列表中点击“编译”，适合快速验证已有脚本是否还能通过编译。 |
| 批量编译 | 勾选多个脚本，点击工具栏批量编译按钮。常用于升级后统一验证。 |
| 删除脚本 | 点击“删除”并确认。删除前应确认变量、数据转发、MQTT RPC 或规则中不再引用该脚本。 |
| 查看已加载脚本 | 切换到“已加载脚本”页签，确认运行时当前可用的表达式。 |
使用注意
| 场景 | 建议 |
|---|---|
| 脚本命名 | 使用稳定命名，不要频繁改名。变量、规则、数据转发和 RPC 配置可能会按脚本名称引用。 |
| 生产修改 | 生产环境修改脚本前先导出配置或记录原脚本内容。 |
| 编译失败 | 查看编译日志的第一条错误，通常后续错误是连锁结果。 |
| 已加载列表为空 | 先确认脚本已成功编译，再刷新“已加载脚本”页签。 |
| AOT发布 | AOT 场景下动态编译能力可能受发布方式限制，应在发布前完成脚本验证。 |