自定义 C# Object 能力

大多数设备应优先使用已安装功能包提供的 Object 能力。只有现有能力无法覆盖厂商 SDK、非标协议或客户专用设备时，才为当前 App 编写自定义 C# Provider。

什么时候适合

• 需要调用厂商 SDK 或实现非标通信协议；
• 连接、取消、超时和资源释放必须由同一个边界负责；
• Page 和 QG 需要稳定、强类型的业务方法；
• 该能力需要明确拥有当前 App 的持久状态。

普通时序、条件和状态组合优先使用 QG。需要跨项目复用的通用能力，应按团队发布流程制作功能包，而不是复制 App 源码。

创建入口

1. 在 Resources → Scripts 中选择新建 C# Provider。
2. 把源码保持在项目的 providers-src/**/*.cs 中。
3. 为 Object 类型填写简短、面向工程人员的能力描述和适用设备。
4. 保存后先处理当前源码提示，再执行 Build。

不要把编译结果或生成文件复制回项目，也不要通过扫描安装目录推测用法。

源码模型

• 编写继承 ObjectBase 的具体 class，并用 [ObjectType] 声明 Object 类型。
• public 方法直接形成 Page 和 QG 可以使用的方法面。
• 只有需要覆盖稳定 ID 或显示名称时才使用 [ObjectMethod]。
• Object 引用使用 [ObjectReference("...")] ObjectRef<T>；T 是另一个具体 Object 类型，或已安装功能包公开的引用类型。
• 不要另外声明平行 interface、抽象 capability 基类、手写 Provider definition 或自行维护 client class。

名称、描述、参数和单位应表达业务含义。不要把寄存器地址、协议细节或厂商错误码直接扩散到多个 Page 和 QG；在 Provider 边界内转换成稳定的状态、动作和明确错误。

Build 与验收

保存源码只更新项目。完成修改后：

1. 确认所有相关 Object 属性和引用有效；
2. Stop 当前 App；
3. 执行 Build，并修复 Problems 中的源码、类型或引用错误；
4. 从只读方法开始验证，再逐步测试可撤销、幂等的低风险动作；
5. 使用 Start 或 Debug 验证超时、取消、断线、未知结果和恢复路径。

只有 Build 成功，新能力才会进入交付版本。设备调用超时或连接中断后，不要假设动作未执行；先读取独立状态并取得现场反馈。

工程边界

• 凭据只进入专用设置，不要写入源码、日志、对话或版本库。
• 连接和资源由 Provider 明确拥有，并在 Stop、故障或取消时正确释放。
• 对外方法应体现工艺意图，不把底层协议调用顺序交给 Page。
• 软件停止、异常处理和权限检查不能替代硬件急停、安全控制器或工艺互锁。

返回配置 Object 与设备继续完成实例配置和现场验收。