业务插件二开说明

本文把继承 DataForwardBase 的数据转发目标、协议服务端、数据库写入、云平台对接、同步桥接统一称为“业务插件”。业务插件不负责从现场设备采集原始数据，而是消费采集变量、设备状态、报警或插件事件，把它们写入外部系统，或对外提供服务端协议能力。

如果要扩展 PLC、仪表、OPC、MQTT 采集等设备驱动，请阅读 采集插件二开说明。

阅读路线

实现模板 → 参数与缓存契约 → 排障与验收

首次开发先验证一个最小例，再按参考补全参数、失败处理和释放流程。MCP 材料入口位于页末，可按需展开。

开发准备与基类选择

源码入口

业务插件和采集插件的边界

不要把业务插件写成“再去全局扫描所有变量”。变量范围由转发组决定，业务插件应通过 GetVariables()、IdVariableRuntimes、CollectDevices 或组生产入口读取当前目标可见的数据。

插件发现规则

基类选择

如果目标只是“把变量转成 JSON 发到某个系统”，优先使用 DataForwardBaseWithCacheIntervalScriptAll。如果目标要对外模拟一个协议服务端，让外部系统主动读写内存点表，优先使用 DataForwardBase。

定义配置属性

目标属性和变量属性

实现目标属性时要同时保证目标属性实例和类型一致：

private readonly MyTargetProperty _properties = new();
 
public override DataForwardPropertyBase TargetProperties => _properties;
 
public override Type TargetPropertyType { get; } = typeof(MyTargetProperty);

插件有变量级配置时，在插件类上声明 [VariablePropertyModel(typeof(MyVariableProperty))]，将类声明为 partial，并通过 VariablePropertys 返回该类型的属性实例。VariablePropertyType 由生成器生成，不再手写同名覆盖成员。检查生成目录包含变量属性字段，再用实例元数据接口验证页面表单。

DataForwardVariablePropertyBase.Enable 不是动态属性，页面不会出现第二个启用开关。是否转发某个变量由转发组变量范围、组内变量启用状态、目标启用状态和触发条件共同决定。

DynamicProperty 约定

业务插件和采集插件使用同一套动态属性规则。

运行时与缓存契约

生命周期钩子

转发组是变量范围的唯一入口

DataForwardGroupRuntime.RebuildVariables() 会根据组配置生成两个运行态索引。

业务插件应通过这些入口读取数据：

目标变量属性不能把变量“拉进”转发范围。现场出现“变量有值但目标没有发送”时，先查转发组范围、组内变量启用、触发模式、目标启用和目标连接。

数据入口：直接事件和组生产

缓存型基类会把 UsesGroupDataProducer 固定为 true。转发管理器会根据组触发模式、批处理模式和最大批量统一生产数据，再调用 AcceptProduced*。这样多个目标不会各自重复做范围解析和批处理。

缓存和失败语义

DataForwardBaseWithCache 为每种模型维护独立的内存队列和文件缓存。

正常发送同样经过缓存出站流程，CacheEnable 控制失败后的保留与重试。脚本类上传目标还会把已经生成但未确认的 TopicArray 写入 Topic outbox，连接恢复后 ReplayTopicUploadCache 先补发旧数据，再处理新数据。重试可能重复，接收端应按业务键做幂等；强杀前仍在内存、尚未提交的批次可能丢失。

Topic、脚本和上传模板

DataForwardBaseWithCacheIntervalScriptAll 已经处理了这些工作：

这类插件通常只需要实现 Upload(TopicArray topicArray, CancellationToken cancellationToken)。

实现模板

脚本上传目标模板

完整可构建模板使用技能 ZIP 的 BatchHttpForwarder.cs.txt、BatchHttpProperties.cs.txt 与 PlantGatewayPlugins.csproj.txt，见 技能获取与打包步骤。实现时重点保持以下边界：

1. 复用 DataForwardBaseWithCacheIntervalScriptAll 的组生产、四类模型、脚本、模板和缓存，只在 Upload 完成最终发送。
2. 在目标生命周期内复用 HttpClient，用 TopicArray.Topic 作为地址、Payload.Memory 作为借用载荷；发送完成前不缓存其内存引用，不释放父链拥有的输入。
3. 非 2xx、连接失败与超时返回失败 OperResult，生命周期取消继续传播。失败等待有界、可取消且先释放本次响应资源，不在插件内另建重试循环；由缓存父链重试。
4. 停止时先等待 base.SafetyDisposeAsync 使缓存在途操作退场，再在 finally 中释放 HttpClient，避免发送尚未结束就销毁客户端。

配置目标后，在 数据转发 → 详细信息 核对组范围、定时/变化触发、批量、在线状态和缓存参数，再到 调试 检查管线、缓存出站和插件特殊方法。接收端同时记录实际请求与条数；详见 通讯与业务链验收。

示例的 GetLastHttpStatus 可在 协议调试 → 特殊方法 中用空参数数组 [] 查询最近 HTTP 状态。返回 200 只表示最近一次 HTTP 响应，完整交付仍需接收端内容核对与故障恢复验收。

协议服务端目标模板

协议服务端目标通常不使用脚本上传基类，而是维护一份外部协议内存映射。

[VariablePropertyModel(typeof(MyServerVariableProperty))]
public sealed partial class MyServerTarget : DataForwardBase
{
    private readonly MyServerProperty _properties = new();
    private readonly MyServerVariableProperty _variableProperties = new();
    private readonly ConcurrentQueue<VariableRuntime> _changedVariables = new();
    private MyServer? _server;
 
    public override DataForwardPropertyBase TargetProperties => _properties;
 
    public override Type TargetPropertyType { get; } = typeof(MyServerProperty);
 
    public override DataForwardVariablePropertyBase VariablePropertys => _variableProperties;
 
    public override bool IsConnected() => _server?.IsRunning == true;
 
    protected override async Task ProtectedInitAsync(CancellationToken cancellationToken)
    {
        _server = new MyServer(_properties.BindUrl);
        await base.ProtectedInitAsync(cancellationToken).ConfigureAwait(false);
    }
 
    public override async Task AfterVariablesChangedAsync(CancellationToken cancellationToken)
    {
        await base.AfterVariablesChangedAsync(cancellationToken).ConfigureAwait(false);
        foreach (var variable in GetVariables())
        {
            var map = GetVariableProperty<MyServerVariableProperty>(variable);
            if (map != null)
                _server!.Register(map.Address, variable.DataType);
        }
    }
 
    protected override async Task ProtectedStartAsync(CancellationToken cancellationToken)
    {
        await _server!.StartAsync(cancellationToken).ConfigureAwait(false);
        await base.ProtectedStartAsync(cancellationToken).ConfigureAwait(false);
    }
 
    public override void OnVariableChanged(VariableRuntime variableRuntime, VariableBasicData variableData, CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested)
            return;
        _changedVariables.Enqueue(variableRuntime);
    }
 
    protected override Task ProtectedExecuteAsync(object? state, CancellationToken cancellationToken)
    {
        while (_changedVariables.TryDequeue(out var variable))
        {
            var map = GetVariableProperty<MyServerVariableProperty>(variable);
            if (map != null)
                _server!.SetValue(map.Address, variable.Value);
        }
        return Task.CompletedTask;
    }
}

ModbusSlave、IEC104Slave、OpcUaServer、IEC61850Server 都属于这种思路：变量变化先进入插件维护的映射或队列，再由协议服务端对外提供读写。

现有插件参考

当前源码业务插件参考矩阵

下表按当前源码快照整理业务插件参考。实际可选目标会随安装包、授权、平台和运行时扫描条件变化；开发新目标前，优先找最接近的类型参考。

插件类型参考

排障与验收

常见开发错误

验证清单