Plugin Development Guide

Relevant source files

• Directory.Build.targets
• PackNuget.props
• README.md
• ThingsGateway.Plugin.slnx
• src/ThingsGateway.Plugin.Kafka/Kafka/KafkaProducer.cs
• src/ThingsGateway.Plugin.Mqtt/MqttCollect/MqttCollect.other.cs
• src/ThingsGateway.Plugin.Mqtt/MqttServer/MqttServer.cs
• src/ThingsGateway.Plugin.OpcDa/OpcDaMaster/OpcDaMaster.cs
• src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs
• src/ThingsGateway.Plugin.OpcUa/Pages/OpcUaMaster.razor
• src/ThingsGateway.Plugin.RabbitMQ/RabbitMQ/RabbitMQProducer.cs

This document provides a comprehensive guide for developers creating custom plugins for the ThingsGateway platform. It covers the plugin architecture, base classes, lifecycle management, property systems, and integration patterns. For detailed step-by-step implementation guides, see Creating a Custom Collection Plugin for data acquisition plugins and Creating a Custom Publishing Plugin for data distribution plugins.

Purpose and Scope

This guide explains:

• Plugin architecture and type taxonomy
• Base class selection criteria
• Plugin lifecycle phases and methods
• Property and configuration systems
• Variable management and data flow
• Common integration patterns

This page focuses on architectural concepts and patterns. For protocol-specific implementations, see the individual plugin documentation pages (e.g., OPC UA Master Plugin, MQTT Server Plugin).

---

Plugin Architecture Overview

The ThingsGateway plugin system is organized around three base classes that define distinct plugin categories. Plugins integrate with the core platform through well-defined interfaces for configuration, lifecycle management, and data exchange.

Plugin Type Taxonomy

Base Class Selection Criteria

Base Class	Purpose	Use When	Key Features
CollectBase	Inbound data acquisition	Reading from industrial devices/protocols	Connection management, variable loading, source reading, write-back
BusinessBase	Outbound data publishing	Basic data distribution without caching	Simple publish patterns, event handling
BusinessBaseWithCacheIntervalScriptAll	Advanced publishing	Complex distribution with buffering/scripting	Caching, interval processing, C# scripting, batch operations

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs31 src/ThingsGateway.Plugin.Mqtt/MqttServer/MqttServer.cs32 src/ThingsGateway.Plugin.Kafka/Kafka/KafkaProducer.cs22

---

Plugin Lifecycle Management

All plugins follow a standardized lifecycle with well-defined initialization, execution, and disposal phases. Understanding this lifecycle is critical for proper resource management and integration with the platform.

Lifecycle State Machine

Lifecycle Methods by Base Class

CollectBase Methods

Method	Phase	Purpose	Implementation Required
InitChannelAsync	Initialization	Initialize protocol client, load configuration	Override
ProtectedLoadSourceReadAsync	Initialization	Group variables into read operations	Override
ProtectedStartAsync	Starting	Establish connections, start subscriptions	Optional override
ReadSourceAsync	Execution	Execute read operation for variable group	Override if polling mode
WriteValuesAsync	RPC	Write values back to device	Override if write-back supported
IsConnected	Status	Check connection status	Override
AfterVariablesChangedAsync	Runtime	Handle variable configuration changes	Optional override
DisposeAsync	Disposal	Release resources	Override

BusinessBaseWithCacheIntervalScriptAll Methods

Method	Phase	Purpose	Implementation Required
InitChannelAsync	Initialization	Initialize publisher (MQTT, Kafka, DB), configure client	Override
ProtectedStartAsync	Starting	Start server/client, attach event handlers	Optional override
ProtectedExecuteAsync	Execution	Process cached data, publish to destination	Override
IsConnected	Status	Check publisher/connection status	Override
DisposeAsync	Disposal	Flush buffers, close connections	Override

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs60-130 src/ThingsGateway.Plugin.Mqtt/MqttServer/MqttServer.cs49-158

---

Plugin Lifecycle Implementation Patterns

Collection Plugin Lifecycle Pattern

Key Patterns:

1. Lazy Connection: Connections established in ProtectedStartAsync, not InitChannelAsync
2. Variable Grouping: Variables chunked by GroupSize property for efficient batch reads
3. Reconnection: Connection checks in periodic tasks (e.g., CheckConnectAsync)
4. Safe Disposal: Protocol clients disposed before plugin disposal

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs60-130 src/ThingsGateway.Plugin.OpcDa/OpcDaMaster/OpcDaMaster.cs56-195

Publishing Plugin Lifecycle Pattern

Key Patterns:

1. Server Initialization: Web hosts (Kestrel) or clients initialized in InitChannelAsync
2. Event-Driven: Event handlers attached for incoming connections/messages
3. Cache Integration: Uses platform's variable cache for interval/change-based publishing
4. Script Support: Optional C# script execution for data transformation
5. Topic Configuration: Topics configurable per data type (Variable, Device, Alarm)

Sources: src/ThingsGateway.Plugin.Mqtt/MqttServer/MqttServer.cs49-158 src/ThingsGateway.Plugin.Kafka/Kafka/KafkaProducer.cs55-103

---

Property and Configuration System

Plugins expose configuration through strongly-typed property classes that integrate with the ThingsGateway UI. The property system supports both channel-level (global) and variable-level (per-tag) configuration.

Property Class Architecture

Property Exposure Pattern

Collection Plugin Properties:

Publishing Plugin Properties:

Common Configuration Properties:

Property Category	Examples	Used In
Connection	OpcUrl, IP, Port, BootStrapServers	Collection & Publishing
Security	UseSecurity, UserName, Password, SaslMechanism	All with authentication
Performance	UpdateRate, GroupSize, CheckRate	Collection
Publishing	VariableTopic, DeviceTopic, AlarmTopic	Publishing
Scripting	BigTextScriptRpc, Script-based transformations	Publishing with BusinessBaseWithCacheIntervalScriptAll
Variable-Level	RegisterAddress, Topic, JsonPath, Expression	Variable properties

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs33-77 src/ThingsGateway.Plugin.Kafka/Kafka/KafkaProducer.cs24-71

---

Variable Management and Data Flow

Variables are the fundamental unit of data in the ThingsGateway platform. Collection plugins write to variables, and publishing plugins read from them. Understanding the variable lifecycle is essential for correct plugin implementation.

Variable Lifecycle in Collection Plugins

Variable Update Methods:

Method	Signature	When to Use
SetValue(value, time)	void SetValue(object value, DateTime time)	Quality good, value valid
SetValue(value, time, quality)	void SetValue(object? value, DateTime time, bool quality)	Explicit quality control (e.g., OPC bad quality)

Variable Grouping Pattern:

Collection plugins group variables into VariableSourceRead objects for efficient batch operations:

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs209-292 src/ThingsGateway.Plugin.OpcDa/OpcDaMaster/OpcDaMaster.cs109-142

Variable Access in Publishing Plugins

Publishing plugins access variables through the platform's caching system:

Cache Integration Pattern:

Variable Properties in Publishing:

Publishing plugins can define variable-level properties for per-tag configuration:

Sources: src/ThingsGateway.Plugin.Mqtt/MqttCollect/MqttCollect.other.cs47-111 src/ThingsGateway.Plugin.Kafka/Kafka/KafkaProducer.cs110-113

---

Connection Management Patterns

Collection Plugin Connection Pattern

Collection plugins must manage connection state, reconnection logic, and connection status reporting:

Standard Connection Management:

Key Principles:

1. Non-Blocking: Connection attempts should not block initialization
2. Periodic Retry: Use scheduled tasks for reconnection attempts
3. Status Reporting: Update CurrentDevice.SetDeviceStatus on connection state changes
4. First-Failure Logging: Log first failure, suppress repeated failures to avoid log spam

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs95-150

Publishing Plugin Connection Pattern

Publishing plugins often need bidirectional connection management (accept incoming + maintain outgoing):

MQTT Collector Connection with Retry:

Key Principles:

1. Thread-Safe: Use locks (WaitLock) to prevent concurrent connection attempts
2. Timeout Handling: Use CancellationTokenSource with timeout
3. Double-Check: Check connection state before and after lock acquisition
4. Linked Cancellation: Combine method cancellation token with timeout token

Sources: src/ThingsGateway.Plugin.Mqtt/MqttCollect/MqttCollect.other.cs135-183

---

Integration with ThingsGateway Platform

Platform-Provided Services

Plugins receive services and context through base class properties:

Property	Type	Purpose	Available In
LogMessage	ILog	Structured logging	All plugins
CurrentDevice	DeviceRuntime	Device status/variables	All plugins
ReadWriteLock	AsyncLock	Thread-safe read/write operations	All plugins
IdVariableRuntimes	Dictionary<long, VariableRuntime>	Variable lookup by ID	All plugins
PluginDirectory	string	Plugin installation directory	All plugins
TaskSchedulerLoop	TaskScheduler	Task execution scheduler	All plugins

Logging Patterns

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs143-358

UI Integration

Plugins can provide custom UI components for configuration and debugging:

UI Component Types:

1. DriverDebugUIType: Testing interface for manual read/write operations
2. DriverUIType: Runtime management interface (certificates, configuration)
3. DriverPropertyUIType: Custom property editor (advanced configuration)

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs56-58 src/ThingsGateway.Plugin.OpcUa/Pages/OpcUaMaster.razor1-111

---

Common Implementation Patterns

Subscription vs. Polling Pattern

Collection plugins should support both active subscription (push) and polling (pull) modes when the protocol allows:

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs114-404 src/ThingsGateway.Plugin.OpcDa/OpcDaMaster/OpcDaMaster.cs106-262

Write-Back (RPC) Pattern

Collection plugins supporting bidirectional communication implement WriteValuesAsync:

Key Principles:

1. Write Lock: Always acquire ReadWriteLock.WriterLockAsync() to prevent read/write conflicts
2. Result Mapping: Map protocol addresses back to variable names
3. Verification: Use Check() to optionally verify writes by reading back
4. Error Handling: Return OperResult per variable with success/failure status

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs295-312 src/ThingsGateway.Plugin.OpcDa/OpcDaMaster/OpcDaMaster.cs159-178

Topic-Based Publishing Pattern

Publishing plugins often support multiple topics for different data types:

Sources: src/ThingsGateway.Plugin.Mqtt/MqttServer/MqttServer.cs90-101 src/ThingsGateway.Plugin.Kafka/Kafka/KafkaProducer.cs89-100

---

Build and Distribution

Project Configuration

Plugin projects inherit configuration from root Directory.Build.props and PackNuget.props:

Key Build Settings:

Setting	Value	Purpose
TargetFrameworks	net8.0;net10.0	Multi-targeting for compatibility
Version	$(PluginVersion)	Centralized version (12.5.6)
GeneratePackageOnBuild	true	Automatic NuGet package generation
PackageOutputPath	../nupkgs	Centralized package output
SignAssembly	true	Strong-name signing with ThingsGateway.snk

Conditional Dependencies:

This dual-mode system enables:

• Monorepo Development: Direct project references for rapid iteration
• Independent Distribution: NuGet package references for stable releases

Sources: Directory.Build.props PackNuget.props1-43 README.md

---

Next Steps

For detailed implementation guides, proceed to:

• Creating a Custom Collection Plugin - Step-by-step guide for data acquisition plugins
• Creating a Custom Publishing Plugin - Step-by-step guide for data distribution plugins

For protocol-specific examples, see:

• OPC UA Master Plugin - Complete collection plugin with subscription
• MQTT Server Plugin - Complete publishing plugin with broker
• SQL Database Producer Plugin - Database persistence with scripting

Sources: src/ThingsGateway.Plugin.OpcUa/OpcUaMaster/OpcUaMaster.cs1-408 src/ThingsGateway.Plugin.Mqtt/MqttServer/MqttServer.cs1-161