PlcLibrary.Modbus 1.0.0

PlcLibrary

PLC 数据采集库，提供连接池管理、定时采集调度、数据分发管道。

• 协议无关驱动接口，一行注册新协议
• 连接池 + Polly 弹性策略（重试、超时、断路器），每设备独立隔离，覆盖连接和 IO 两级
• 设备配置热更新，差量 reconcile
• Channel 管道 fan-out 到多个 IDataHandler
• 主动读写 + 自动采集双模式
• System.Diagnostics.Metrics 内置可观测性，0 依赖接入 Prometheus / Grafana

支持的驱动

安装

dotnet add package PlcLibrary

按需添加驱动包：

dotnet add package PlcLibrary.S7
dotnet add package PlcLibrary.Modbus
dotnet add package PlcLibrary.OpcUa
dotnet add package PlcLibrary.Mitsubishi
dotnet add package PlcLibrary.Omron
dotnet add package PlcLibrary.AllenBradley
dotnet add package PlcLibrary.Bacnet

快速开始

using Microsoft.Extensions.Logging;
using PlcLibrary.Controller.Interfaces;
using PlcLibrary.DriverDomain.Models;
using PlcLibrary.Extensions;
using PlcLibrary.General.Configuration;
using PlcLibrary.Pipeline.Interfaces;
using PlcLibrary.S7;

var builder = Host.CreateApplicationBuilder(args);

var devices = new[]
{
    new DeviceConfiguration
    {
        Id = "plc-001",
        Name = "1号线",
        Protocol = "S7",
        ConnectionString = "host:10.38.103.107;port:102;timeout:3000;rack:0;slot:0;cpu:S71200;",
        TagPoints = new[]
        {
            new TagPointConfiguration { TagId = "t1", Address = "DB21.DBX10.2", DataType = "System.Boolean" },
            new TagPointConfiguration { TagId = "t2", Address = "DB21.DBX10.0", DataType = "System.Boolean" },
        },
        CollectionInterval = TimeSpan.FromSeconds(1),
    },
};

builder.Services
    .AddPlcLibrary()
    .AddDriver<S7Driver>()
    .AddSingleton<IDataHandler, ConsoleHandler>();

var host = builder.Build();
await host.Services.GetRequiredService<IDeviceScheduler>().ApplyDevicesAsync(devices);
await host.RunAsync();

internal sealed class ConsoleHandler(ILogger<ConsoleHandler> logger) : IDataHandler
{
    public ValueTask HandleAsync(DriverResult result, CancellationToken ct)
    {
        logger.LogInformation("[{DeviceId}] {Address} = {Value} ({Status})",
            result.DeviceId, result.Address, result.Value, result.Status);
        return ValueTask.CompletedTask;
    }
}

设备多时可用 BackgroundService + IConfiguration 从 appsettings.json 读取，参考下文 JSON 配置方式。

使用 JSON 配置

builder.Services.AddPlcLibrary();
builder.Services.Configure<PoolOptions>(builder.Configuration.GetSection("DriverPool"));
builder.Services.Configure<PipelineOptions>(builder.Configuration.GetSection("Pipeline"));

{
  "Devices": [
    {
      "Enabled": true,
      "Id": "plc-01",
      "Protocol": "S7",
      "ConnectionString": "host:192.168.1.1;port:102;rack:0;slot:1;cpu:S71200",
      "CollectionInterval": "00:00:01",
      "TagPoints": [
        { "TagId": "temp", "Address": "DB1.DBD0", "DataType": "Real" },
        { "TagId": "pressure", "Address": "DB1.DBD4", "DataType": "Real" }
      ]
    }
  ]
}

internal sealed class DeviceLoader(IConfiguration config, IDeviceScheduler scheduler) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        var devices = config.GetSection("Devices").Get<DeviceConfiguration[]>();
        if (devices is { Length: > 0 })
            await scheduler.ApplyDevicesAsync(devices, ct);
    }
}

连接字符串

格式 key:value;key:value，大小写不敏感。

S7

示例：host:192.168.1.1;port:102;rack:0;slot:1;cpu:S71500

Modbus TCP / UDP

示例：host:10.0.0.1;port:502;slaveid:2

Modbus 地址格式：使用 5 位十进制数字前缀标记数据类型：

地址为 1-based（PLC 习惯），驱动内部自动转换为 0-based 偏移。连续地址自动合并为单次批量读写。

Modbus RTU / ASCII（待 NModbus 更新）

示例：host:COM3;baudrate:19200;parity:Even;slaveid:1

OPC UA

示例：endpoint:opc.tcp://10.0.0.1:4840;security:None;timeout:10000

Mitsubishi

示例：host:192.168.1.1;port:6000;protocoltype:MC

地址格式：三菱标准地址字符串，取决于所选协议类型：

Omron FINS

地址格式：Omron 标准 FINS 地址字符串。

示例：host:192.168.1.1;port:9600;localnode:1;destinynode:2

Allen-Bradley / Rockwell

地址格式：Logix 标签名。

CompactLogix 示例：host:192.168.1.96

ControlLogix 示例：host:192.168.1.96;path:1,0

BACnet

地址格式：TYPE:INSTANCE（如 AV:1 = Analog Value 1、BI:0 = Binary Input 0）。

支持类型：AI/AO/AV/BI/BO/BV/MI/MO/MV。

示例：host:192.168.1.50;port:47808;deviceinstance:12345

点位数据类型 (DataType)

部分驱动需要 TagPointConfiguration.DataType 指定点位的数据类型，以正确解析 PLC 返回值：

支持的 DataType 值（大小写不敏感）：

// Omron D100 为 32 位浮点数
new TagPointConfiguration { TagId = "temp", Address = "D100", DataType = "float" }

// AllenBradley tag 为布尔量
new TagPointConfiguration { TagId = "run", Address = "MotorRun", DataType = "bool" }

驱动池

{
  "DriverPool": {
    "MaxConnectionsPerDevice": 2,
    "MaxRetryAttempts": 3,
    "RetryDelay": "00:00:01",
    "CircuitBreakerMinimumThroughput": 5,
    "CircuitBreakerDuration": "00:00:30",
    "CircuitBreakerFailureRatio": 0.5,
    "OperationTimeout": "00:00:10"
  }
}

管道

{
  "Pipeline": {
    "Capacity": 10000,
    "MaxHandlerParallelism": 8,
    "HandlerTimeout": "00:00:30"
  }
}

弹性策略

Polly 弹性分为两级，每设备独立隔离：

• 连接级断路器：连续失败达阈值后进入熔断（默认 5 次、失败率 ≥ 50%、冷却 30s），熔断/半开/恢复均有 ILogger 日志。
• IO 级重试：每次 ReadAsync/WriteAsync 失败时自动重试（默认 3 次），排除 OperationCanceledException 和 TimeoutRejectedException。
• 两级策略均复用 DriverPool 配置节中的 MaxRetryAttempts、RetryDelay、OperationTimeout。

可观测性

PlcLibrary 通过 System.Diagnostics.Metrics（.NET 6+ 内置，零 NuGet 依赖）暴露以下指标：

Meter: PlcLibrary

接入方式

OpenTelemetry Collector（推荐）:

dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore

builder.Services.AddOpenTelemetry()
    .WithMetrics(m => m
        .AddMeter("PlcLibrary")
        .AddPrometheusExporter());

启动后访问 /metrics 即可被 Prometheus 抓取，Grafana 中查询 plc_read_duration_seconds_bucket 等指标。

dotnet-counters（本地调试）:

dotnet-counters monitor -n MyApp --counters PlcLibrary

Grafana 面板示例

# 采集吞吐 (points/s)
rate(plc_reads_total[1m])

# 读延迟 p50 / p99
histogram_quantile(0.50, rate(plc_read_duration_seconds_bucket[1m]))
histogram_quantile(0.99, rate(plc_read_duration_seconds_bucket[1m]))

# 错误率
rate(plc_read_errors_total[1m]) / rate(plc_reads_total[1m])

# 通道丢弃率
rate(plc_pipeline_dropped_total[1m])

{
  "Pipeline": {
    "Capacity": 10000,
    "MaxHandlerParallelism": 8,
    "HandlerTimeout": "00:00:30"
  }
}

API

核心接口

主动读写

public class MyService(IDeviceAccessor accessor)
{
    public async Task ReadDevice(DeviceConfiguration device)
    {
        var values = await accessor.ReadAsync(device, device.TagPoints);
    }

    public async Task WriteDevice(DeviceConfiguration device)
    {
        var points = new Dictionary<TagPointConfiguration, object>
        {
            [device.TagPoints[0]] = 123.45
        };
        await accessor.WriteAsync(device, points);
    }
}

设备级连接超时

DeviceConfiguration.ConnectionTimeout 可覆盖全局 PoolOptions.OperationTimeout，在获取驱动时优先使用设备级配置。默认 TimeSpan.Zero 表示使用全局配置。

断路器状态变更（熔断/半开/恢复）通过 ILogger 输出 Warning/Information 级别日志，每设备独立隔离。

健康状态

var scheduler = host.Services.GetRequiredService<IDeviceScheduler>();
var health = await scheduler.GetDeviceHealthAsync();

foreach (var d in health)
    Console.WriteLine($"{d.DeviceId} [{d.Protocol}] {(d.IsRunning ? "OK" : d.Error)}");

返回 IReadOnlyList<DeviceHealthInfo>，每个设备包含 DeviceId、Protocol、IsRunning、Error 和 UpdatedAt。

致谢

本项目基于以下优秀的开源库构建：

许可证

MIT