Business Plugin Development

This document uses “business plugin” as a collective term for data forwarding targets derived from DataForwardBase, protocol servers, database writers, cloud integrations, and synchronization bridges. Business plugins do not collect raw data from field devices. They consume collected variables, device states, alarms, or plugin events and write them to external systems or expose server-side protocol capabilities.

To extend drivers for PLCs, instruments, OPC, MQTT collection, or other devices, see Collection Plugin Development.

Reading path

Implementation templates → Parameters and cache contracts → Troubleshooting and acceptance

Start with one minimal example, then use the reference for parameters, failures and cleanup. Optional MCP materials are collapsed at the end of this page.

Preparation and base classes

Source Code Entry

Boundaries between Business Plugins and Collection Plugins

Do not write the business plugin as “then scan all variables globally.” The variable range is determined by the forwarding group. Business plugins should read the currently visible data from the target via GetVariables(), IdVariableRuntimes, CollectDevices or the group production entry.

Plugin Discovery Rules

Base Class Selection

If the goal is simply to “convert variables to JSON and send to a certain system,” prioritize using DataForwardBaseWithCacheIntervalScriptAll. If the goal is to simulate a protocol server externally and allow external systems to actively read and write memory point tables, prioritize using DataForwardBase.

Define configuration properties

Target Attributes and Variable Attributes

When implementing the target attribute, ensure that both the instance and type of the target attribute are consistent:

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

For variable-level configuration, apply [VariablePropertyModel(typeof(MyVariableProperty))] to a partial plugin class and return that property’s instance from VariablePropertys. The generator emits VariablePropertyType; do not declare a duplicate override. Check generated fields and verify the form through the instance metadata API.

DataForwardVariablePropertyBase.Enable is not a dynamic property, so the page will not have a second enable switch. Whether to forward a variable is determined by the range of group variables, the enabled status of variables within the group, the enabled status of the target, and the trigger conditions.

DynamicProperty Contract

business plugins and collection plugins use the same set of dynamic property rules.

Runtime and cache contracts

Lifecycle Hooks

The forwarding group is the only entry point to the variable range

DataForwardGroupRuntime.RebuildVariables() generates two runtime indexes based on the group configuration.

Business plugins should read data through these entry points:

The target variable attribute cannot “pull” the variable into the forwarding range. When “variable has value but target hasn’t been sent” appears on site, first check the forwarding group range, variable enabled within the group, trigger mode, target enabled, and target connection.

Data Entry: Direct Events and Group Production

cached base classes fix UsesGroupDataProducer to true. The forwarding manager unifies production data based on group trigger mode, batch mode, and maximum batch size, then calls AcceptProduced*. This way, multiple targets won’t have to perform scope parsing and batch processing separately.

Caching and Failure Semantics

DataForwardBaseWithCache Maintain independent memory queues and file caches for each model.

Normal sending also follows the cache outbox path. CacheEnable controls retention and retry after failure. Script targets retain generated, unconfirmed TopicArray entries in the Topic outbox; ReplayTopicUploadCache replays old entries before new data after recovery. Retries may duplicate delivery, so use business-key idempotency. A forced termination can lose in-memory batches not yet committed.

Topic, Script, and Upload Template

DataForwardBaseWithCacheIntervalScriptAll has handled these tasks:

These plugins usually only need to implement Upload(TopicArray topicArray, CancellationToken cancellationToken).

Implementation templates

Script Upload Target Template

Use BatchHttpForwarder.cs.txt, BatchHttpProperties.cs.txt and PlantGatewayPlugins.csproj.txt from the skill ZIP for a complete buildable example. See skill retrieval and packaging. Preserve these boundaries:

1. Reuse the parent class’s group production, four model families, scripts, templates and cache; implement final sending in Upload.
2. Reuse HttpClient for the target lifetime. Send to TopicArray.Topic using borrowed Payload.Memory; finish sending before the borrowed memory expires, and do not retain or dispose the parent’s input.
3. Return failed OperResult for non-2xx, connection failures and timeouts. Propagate lifecycle cancellation. Release response resources before a bounded, cancellable failure delay. Let the cache parent retry instead of starting another retry loop.
4. On shutdown, await base.SafetyDisposeAsync to finish in-flight cache operations, then dispose HttpClient in finally.

In Data forwarding → Details, verify group scope, triggers, batch size, online state and cache settings. In Debug, inspect the pipeline, cache outboxes and special methods. Verify actual requests and records at the receiver; see communication validation.

In Debug → Special methods, call the example’s GetLastHttpStatus with []. The result below is 200, identifying the last HTTP response. Receiver content checks and failure recovery remain separate acceptance steps.

Protocol Server Target Template

Protocol server targets usually do not use script upload base classes, but instead maintain an external protocol memory mapping.

[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, and IEC61850Server all follow this model: variable changes first enter a mapping or queue maintained by the plugin, then the protocol server exposes read/write services.

Existing plugin reference

Current Source Code Business Plugin Reference Matrix

The table below checks 15 business plugins based on the current source code. Before developing new goals, prioritize looking for the type closest to your reference.

Plugin Type References

Troubleshooting and acceptance

Common Development Errors

Validation Checklist