第一个 WinForms 应用

这一篇带你做一个最小 WinForms 点表面板：从 zeus.json 装载虚拟 Modbus，显示通道状态、炉温、设定值和报警。

完整项目骨架请用 dotnet new zeus-winforms。仓库示例 Zeus.Samples.WinForms.QuickStart 与模板同一条路径。通道回显请看控制台示例。

先运行示例

在仓库的 code 目录执行：

dotnet run --project samples/Zeus.Samples.WinForms.QuickStart

窗口打开后：

通道状态应显示 Open。
温度应显示采集值（空虚拟从站默认 0.0 C）。
点击「模拟高温」后，温度变为 96.5 C，报警状态变为 High。

这说明宿主、JSON 点表、采集循环和 WinForms 绑定都通了。

你的项目需要哪些包

dotnet add package Zeus.Communications
dotnet add package Zeus.Configuration
dotnet add package Zeus.Presentation.WinForms
dotnet add package Zeus.Protocols.Modbus

项目文件需要是 Windows 桌面目标：

<TargetFramework>net8.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>

最小窗口代码

布局放在 MainForm.Designer.cs，后台只挂接 Zeus。把 zeus.json 复制到输出目录后：

using Zeus;

public partial class MainForm : Form
{
    public MainForm()
    {
        InitializeComponent();

        var attachment = this.AttachZeus(builder =>
            builder.AddJsonFile(Path.Combine(AppContext.BaseDirectory, "zeus.json")));
        attachment.Host.Channels.Get("bus").BindState(stateLabel);
        attachment.Host.Points.BindText("temperature", temperatureLabel, value => $"{value:0.0} C");
    }
}

stateLabel、temperatureLabel 由设计器声明。仓库示例还会绑定设定值、加热器和报警色，并用「模拟高温」写虚拟从站寄存器。核心就是：JSON 声明点表，窗口只绑 host.Points。

这段代码怎么理解

代码	作用
`this.AttachZeus(...)`	把 Zeus 宿主挂到窗体生命周期上：窗口加载时启动，关闭时释放
`builder.AddJsonFile("zeus.json")`	装载通道、虚拟 Modbus 从站和点表
`Channels.Get("bus")`	取出 JSON 里声明的通道
`InitializeComponent()`	加载设计器里的布局，不要在后台手写控件坐标
`BindState(stateLabel)`	把通道状态显示到设计器里的 Label
`Points.BindText("temperature", ...)`	把采集值写到 Label，并封送到 UI 线程

为什么不用自己 Invoke

采集回调通常不在 UI 线程上。BindText、BindState 已经做了线程封送，不必在每个事件里手写 Invoke。

换成真实串口

模板和本页示例都读 zeus.json。把通道从虚拟从站改成串口即可，窗口代码不用动：

{
  "name": "bus",
  "type": "serial",
  "options": {
    "portName": "COM3",
    "baudRate": 9600
  }
}

校验位、数据位、停止位目前只能在代码里用 AddSerialPort(name, options => …) 设置；JSON 串口参数写在 options.portName 和 options.baudRate。如果串口打不开，先确认端口名、波特率和是否被串口助手占用。

常见问题

现象	原因	处理
状态一直不是 `Open`	宿主启动失败或通道打开失败	看弹窗和控制台日志
温度一直空白	第一轮采集未完成，或 JSON 未复制到输出目录	确认 `CopyToOutputDirectory`，稍等一轮或订 `BatchChanged`
绑定后界面没刷新	没用 Zeus 的绑定扩展，或点名与 JSON 不一致	确认 `BindText("temperature", …)` 与 `zeus.json` 点名一致
换真实串口后无数据	程序结构没问题，问题可能在接线或参数	先改回 `type: virtual` 确认界面，再查硬件

下一步：了解 WinForms 适配器，或直接看串口。

先运行示例​

你的项目需要哪些包​

最小窗口代码​

这段代码怎么理解​

为什么不用自己 Invoke​

换成真实串口​

常见问题​