脚本管理

打开“开发配置 → 脚本管理”。普通采集不需要脚本；要把原始值换算成工程值、计算多个点位或自定义上传格式时再使用。

把原始值缩小十倍

例如设备读到 1234，希望页面显示 123.4。先准备一个正常采集的数值变量，再执行以下步骤。

新建脚本

1. 在“本地脚本”点击列表右上方的加号。
2. 脚本名称填 ScaleByTen，类型选择“数据转换”，分类留空即可。
3. 点击“确定”，进入编辑器。
4. 将代码编辑区内容替换为下面两行。这里只写计算内容，不要再包一层类或方法。

// 将设备的整数原始值换算为带一位小数的工程值。
return Math.Round(Convert.ToDouble(raw) * 0.1, 1);

5. 点击编辑器右上角的“编译并保存”图标；鼠标停在图标上可看到名称。在底部“编译日志”确认出现“编译成功”，没有加载或保存失败提示。

绑定到变量

1. 返回“开发配置 → 采集配置”，编辑要换算的变量。
2. 在“基本信息”的“表达式配置”区域，将“读表达式”选择为 ScaleByTen，点击“确定”。
3. 等待下次采集，查看“原始值”和“当前值”：原始值为 1234 时，当前值应为 123.4。
4. 读到的原始数据类型仍按设备寄存器设置，不要为了显示小数就把原来读取整数寄存器的类型改成浮点类型。

仅编译脚本不会自动绑定变量。读表达式会修改变量的最终运行值，后续内存计算、报警、规则和转发均使用换算后的值；原始值仍保留设备读数。它不修改设备寄存器，也不自动提供反向写入换算。

取消换算时，重新编辑变量，把鼠标移到“读表达式”选择框上，点击右侧出现的清除图标，再点击“确定”。下次采集后，当前值恢复为未经这个脚本换算的值。

编辑脚本与参数

修改已有脚本

在列表点击“编辑”，修改后再次点击“编译并保存”。返回变量或目标页面检查实际结果，不能只看编译成功。

同名脚本可能被多个变量或目标使用，修改前先记录原代码并确认引用范围。只是调整一个变量的比例时，优先使用带输入参数的脚本，为该变量单独填写参数。

补全、注释与错误定位

编辑器将撤销、重做、格式化和“编译并保存”集中在顶部。Roslyn 连接配置默认隐藏，点击顶部“Roslyn 服务”可展开；默认地址为 https://roslyn.thingsgateway.cn，也可以连接自建 Studio。

输入 GlobalData. 或按 Ctrl+Space 查看网关成员；用户源码中声明的成员也参与补全。悬停在 GlobalData.GetEnableVariables() 上，可以查看中文 XML 摘要、备注和返回值。连接、用户方法注释及参数提示的完整操作见代码编辑、补全与错误定位。

同名修改后的生效检查

编译、运行时注册、消费者绑定和执行结果需要分别确认。内存计算等消费者可能保留之前建立的脚本实例；同名编译成功后，如果结果仍符合旧公式，重新编辑并保存引用它的变量，让消费者重新建立实例，再用两个不同输入核对新公式。修改前应确认所有引用对象，按维护范围逐一验证。

现象	处理方法
编译失败	本次错误源码不会通过“编译并保存”覆盖原已保存源码。保留当前草稿，按诊断修复；旧业务结果不能当作新脚本的执行结果。
编译成功但变量离线	查看变量的表达式错误；合法代码仍可能在运行时因输入、转换或主动抛错而失败。
已加载脚本存在但没有结果	检查脚本类型、消费者绑定、参数和触发方式。完整代码类型需要对应调用入口。
只改参数却没变化	重新打开消费者确认参数已保存，再按其触发方式等待执行。

输入参数

“数据转换”和“内存变量”类型在编辑器底部提供“输入参数”。

1. 添加参数，填写参数名、数据类型、初始值和描述。
2. 在代码中按参数名使用它，点击“编译并保存”。
3. 到引用这个脚本的变量配置中选择读表达式，在出现的参数区域填写该变量的值并保存。

参数定义中的初始值与消费者填写的实参是两个位置。变量参数编辑器要求填写时，空文本不能替代默认值，也不等于 JSON null。例如两路和为 40，倍率先填 0.5 应得 20，只改倍率为 2 应得 80；核对这一组结果可以确认参数确实被当前变量使用。

区分脚本初值和绑定参数格式

类型	脚本定义中的初始值	变量绑定的参数
Int32、Int64	C# 数值表达式，按类型范围填写。	JSON 数字，超范围会失败。
Float、Double、Decimal	使用相应 C# 表达式，例如 Decimal 19.95m。	JSON 数字，例如 19.95，不写 C# 类型后缀。
Boolean	true 或 false。	JSON 布尔 true 或 false。
String	C# 字符串，例如 "Alpha"。	JSON 字符串，例如 "运行"，保留双引号。
DateTime	明确时区的 C# 日期表达式。	带时区的 ISO 日期 JSON 字符串，例如 "2026-10-11T00:00:00Z"。
Byte	0～255 范围内的表达式。	范围内的 JSON 数字。
Object	与实际类型一致的 C# 初始化表达式。	JSON 对象、数组或标量，按脚本实际处理方式使用。

参数表单按 JSON 解析，与手动写入窗口的内容识别规则不同。已绑定的显式参数优先于脚本初值；修改描述只改变说明文字。

重命名、增加或删除输入参数时，同步修改代码引用并重新编译。再清除消费者的表达式选择、重新选择该脚本，填写当前参数并保存，确认不再保留旧参数键。只调整已有参数值则不需要重新编译，但仍要核对保存结果和下一次实际执行。

普通乘十或除十不必先学习参数配置。需要可调比例、偏移量时，使用带参数的线性换算示例。

脚本类型

要做什么	选择类型	在哪里使用
换算设备原始值	数据转换	采集变量的读表达式；写入换算使用写表达式
根据已有变量计算新值	内存变量	内存计算的读表达式
改变上传对象或 JSON 字段	动态模型-变量数据等	转发目标的对应模型脚本属性
自定义历史或实时表的入库逻辑	动态 SQL-变量数据	支持该脚本的数据库转发目标
自定义 QuestDB、TDengine、IoTDB 历史入库	时序库逻辑脚本-变量数据	历史目标的“时序历史脚本”，与自定义 SQL 互斥
自定义报警入库逻辑	动态 SQL-告警变量	历史报警目标
自定义 MQTT 请求格式	MQTT RPC	MQTT 客户端或服务端的 RPC 脚本属性
开发完整扩展	完整代码	二次开发调用，不是普通变量计算入口

设备、插件事件等其他脚本类型只在对应调用功能支持时使用，不能因为列表里能创建，就认为所有转发目标都能选择它。详细代码格式见脚本开发说明。

已经保存的脚本在编译时保持原类型。需要另一种脚本类型时，按正确类型新建脚本，并重新配置消费者引用。

编译与维护

编译日志

编译失败时先看第一条红色错误，点击错误定位代码。修正后再次编译。出现“编译成功但加载失败”或“保存失败”时，本次操作还没完成，不要离开页面丢失修改。

“编译并保存”先验证并加载编译结果，再保存本次源码和参数。编译或加载失败时，原已发布文件和注册保持；如果提示已发布但保存失败，应保留当前代码、处理存储错误后重新提交，并核对重新打开的源码。运行发布与数据库保存是两个结果，不能只看到编译通过就离开。

“已加载脚本”页签用于查看运行时可用脚本；“本地脚本”用于编辑已保存的源码。两者用途不同。

常用操作

操作	步骤
单独重新编译	在本地脚本列表点击该行“编译”
批量编译	勾选脚本，点击批量编译按钮，查看每项结果
删除	先解除变量、目标或其他功能中的引用，再点击“删除”并确认
找不到刚创建的脚本	清空列表筛选；确认编译、加载和保存均成功后刷新

AOT 运行时不支持动态加载脚本。需要在 Web 中编译并使用脚本时，应使用支持动态代码加载的 Runtime 发布包。

相关链接

• 采集配置
• 内存计算
• 数据转发
• 脚本开发说明