06 · 自动化 API —— Hmi.Automation(集成主入口)
这是大多数集成场景唯一需要碰的程序集。 组态(改工程 JSON,可逆)+ 感知(只读)统一入口,先校验后落地、全程审计、从不抛异常(用返回值告成败)。
职责:围绕一个 LoadedProject 的统一组态 + 感知 API。依赖 Hmi.Core、Hmi.Project、Hmi.Drivers。
安全边界:只做组态(可逆 JSON)+ 感知(读),没有任何运行态 PLC 写值。这条线在这一层就钉死了,上面的 HostBridge / MCP 只是转发它。
入口 IProjectAutomation / ProjectAutomation
接口 src/Hmi.Automation/IProjectAutomation.cs,实现 ProjectAutomation(public sealed partial class,按域拆成 .Query / .Screens / .Elements / .Tags / .Channels / .Alarms / .History / .Scripts … 多个分部)。
生命周期方法:
| 方法 | 作用 |
|---|---|
static ProjectAutomation Open(string projectDir) |
从目录加载(内部走 ProjectLoader.Load) |
LoadProject / CreateProject |
换工程 / 新建工程 |
AutomationResult Save() |
先校验再落盘 |
Validate() |
只校验不写 |
AttachCompiler(IScriptCompiler) |
挂脚本编译器(见下) |
属性/事件:LoadedProject Loaded、string ProjectDir、string Source、event Action<string> ProjectSwitched、IReadOnlyList<AuditEntry> Audit(审计流水)。
操作分两类
感知 / 只读(约十来个):GetProject、ListScreens、GetScreen、ListElements、ListTags、ListTagTypes、GetTag、ListChannels、ListProtocols、DescribeProtocol、DescribeElementProps。
组态 / 改工程(覆盖多域):画面、元素、点/变量、通道/设备、配方、报警、历史规则、脚本/模块、多语言、按钮皮肤、启动配置、发布信息、通知配置、报表;脚本编译(CheckScript / BuildScripts / ListFunctionCatalog);持久化(Validate / Save / LoadProject / CreateProject / ExportProject / ImportProject / PackProject)。
面偏组态、感知面精悍;但一律不含实时过程控制 / PLC 写。
返回值 AutomationResult
bool Ok; string Message; object? Data; + 静态 Success(...) / Fail(...)。方法不抛异常,失败靠 Ok = false + Message。集成方式统一:
var a = ProjectAutomation.Open(@"D:\HMI工程\锅炉");
var r = a.AddTag(/* … */);
if (!r.Ok) { /* 看 r.Message */ }
var save = a.Save(); // 落盘前自校验
脚本编译接口 IScriptCompiler
src/Hmi.Automation/IScriptCompiler.cs —— ScriptCheckResult CheckFragment(string code, string? screen, bool asCondition)、ScriptBuildResult CheckProject()(+ DTO ScriptCheckResult / ScriptBuildResult / ScriptBuildLocation / ScriptIssue)。接口在这里、实现 RoslynScriptChecker 在 Hmi.ScriptRuntime(依赖倒置:Automation 不必引 Roslyn)。要脚本校验就 AttachCompiler(new RoslynScriptChecker(a.Loaded))。
函数库目录 ScriptFunctionCatalog
src/Hmi.Automation/ScriptFunctionCatalog.cs —— 支撑 ListFunctionCatalog,给编辑器/AI 提供函数库帮助。
小结
- A 路线(只组态):
Open→ 组态/感知方法 →Save,一个程序集搞定。 - 想把这套能力开给前端 → 第 07 章
AutomationRpcDispatcher把方法名映射成 RPC。 - 想开给外部 AI → 第 07 章
Hmi.Mcp.Host把它们包成 MCP 工具。