简介面向C#开发者与工业数据采集方向的二次开发人员这套Proficy Historian API示例围绕GE Digital历史数据库的接口调用展开帮助读者理解如何通过ClientAccess API完成历史数据查询、实时值读取、数据写入、报警与事件处理以及导入导出和简单可视化等常见任务适合已具备C#基础、希望把Historian接入自有系统或报表分析流程的开发者参考。压缩包共18个文件以8个C#源码文件和2个XAML界面文件为主辅以resx资源、解决方案与项目配置等整体约18KB体量轻便便于快速浏览工程结构与核心调用示例。目前已有560人学习说明其在同类接口示例中具有一定参考价值。读者可从中了解API初始化、查询执行、数据写入和界面展示的组织方式并借此熟悉Historian的数据模型与访问流程为后续集成、排错和功能扩展提供可直接借鉴的起点。1. 从一条停机曲线说起C# Proficy Historian API demo 能落地到什么程度C# Proficy Historian API demo 这份资源最适合放在“历史站已经跑着但业务系统还在手工导 CSV”的现场。它把连接、点位查询、历史读取、批量写入和异常处理拆成可运行的 C# 示例让你能把停机曲线、批次追溯、能耗日报接到 Historian 上而不是停在接口文档里。适合做 MES 报表、设备告警、数据对账的后端和上位机开发者也适合刚接手历史库、需要先验证账号和网络通不通的运维。读下去先跑连接再做点位映射最后用回读对账收口。2. 把连接跑通引用、配置与 ServerConnection 的最小闭环Historian 类项目最容易出现的误判是把“能 ping 通服务器”当成“API 能用”。实际落地时连接层要同时解决程序集位数、账号权限、服务端别名和超时四件事任何一件没对齐后面查点位、读历史都会变成玄学。下面这套顺序是我在多个现场反复用过的先让控制台程序连上再用一个已知点位做轻量探测最后才把连接对象交给查询层。2.1 先认清 SDK 与进程位数Proficy Historian 的 Client Access 程序集常见命名以Proficy.Historian开头引用时不要从别的机器随手拷一份 DLL 进来尽量用现场 SDK 安装目录里的同一套程序集。更关键的是位数如果程序集是 32 位而主程序以 AnyCPU 或 x64 启动运行时会直接抛BadImageFormatException错误信息看起来像“文件损坏”实际是进程位数不匹配。我一般会先把启动项目固定成 x86确认能连上之后再评估是否把采集服务拆成独立的 x86 进程。不要只改解决方案配置里的 “Any CPU”还要看项目属性里的“平台目标”和实际运行进程。任务管理器里看进程有没有(32 位)标记是最快的确认方式。注意如果现场已经有 64 位的主业务系统不要把 Historian SDK 强行塞进主进程单独做一个 x86 采集服务通过队列或本地接口把数据交给主系统稳定性会好很多。2.2 配置文件里不要硬编码连接串连接信息建议放在配置文件里但密码不要落盘。常见做法是配置文件只写服务器、账号和环境变量名密码由部署环境注入。这样开发机、测试机、生产机可以用同一份代码只换环境变量。{ Historian: { Server: historian-app-01, UserName: svc_hist_read, PasswordEnv: HIST_PASSWORD, Domain: , ConnectTimeoutMs: 8000 } }这段配置把“连接目标”和“凭据来源”分开了。Server写 Historian 服务端别名或主机名UserName用专门的只读服务账号PasswordEnv指向环境变量名而不是密码本身Domain留空表示走本地账号或现场约定的认证方式。ConnectTimeoutMs不是 SDK 的硬性参数而是业务层自检的超时预算避免启动时无限等待。public sealed class HistorianOptions { public string Server { get; set; } ; public string UserName { get; set; } ; public string PasswordEnv { get; set; } HIST_PASSWORD; public string Domain { get; set; } ; public int ConnectTimeoutMs { get; set; } 8000; public string ReadPassword() { var pwd Environment.GetEnvironmentVariable(PasswordEnv); if (string.IsNullOrWhiteSpace(pwd)) throw new InvalidOperationException($环境变量 {PasswordEnv} 未设置); return pwd; } }ReadPassword把密码读取集中在一个入口后面不管换成交付脚本、容器注入还是 Windows 服务账号都只改这一处。ConnectTimeoutMs留给启动自检使用不要让连接动作散落在每个业务方法里。账号权限上读历史和写历史最好拆成两个账号报表服务只给读权限回填工具才给写权限。2.3 用一段代码验证认证、别名与超时连接对象不要每次查询都新建。一个进程维持一个ServerConnection查询串行执行并发高的场景按线程或按任务建会话但要有上限。下面这段是 demo 里常见的连接封装重点是把“连接”和“轻量探测”放在一起避免出现“连接成功但账号没有点位权限”的假在线。using Proficy.Historian.ClientAccess.API; public sealed class HistorianSession : IDisposable { private ServerConnection _connection; public ServerConnection Connection _connection ?? throw new InvalidOperationException(连接尚未打开); public void Open(HistorianOptions opt) { _connection new ServerConnection(); _connection.Connect(opt.Server, opt.UserName, opt.ReadPassword()); // 用已知点位做一次轻量探测确认账号至少能读点位 var p new TagQueryParams { NamePattern LINE1.TIC101.PV, MaxNumber 2 }; var q new TagQuery(_connection); q.Query(p); if (q.Tags.Count 0) throw new InvalidOperationException(连接成功但探测点位不存在或无权限); } public void Dispose() { _connection?.Disconnect(); _connection null; } }这段代码做了三件事建立连接、用精确点位做权限探测、在探测失败时尽早抛错。NamePattern不要在生产环境写成*全库通配在点位多的现场会拖慢启动MaxNumber只是本次返回上限不是分页游标。Disconnect放在Dispose里Windows 服务停止或命令行退出时能释放会话。若现场 SDK 的Connect重载不同只改这一层适配不要把业务代码绑死在具体签名上。3. 标签不是字符串TagQuery 的过滤、别名与点位映射Historian 里的点位名往往带着工段、设备、测点类型业务代码直接拿字符串拼接短期能跑半年后就会变成“改一个点名崩三个报表”。demo 里值得抄的部分不是TagQuery那一行调用而是把点位查询收敛成“前缀过滤 业务键映射 元数据缓存”三层。这样报表只认业务键Historian 点名变了只改映射表。3.1 用 TagQuery 做前缀过滤而不是全量拉取TagQuery适合按名称模式找点位但*放在开头会放大服务端扫描成本。常见做法是先按工段前缀缩小范围比如LINE1.*、AREA2.REACTOR.*再在客户端做二次过滤。下面这段按前缀查点位并把元数据转成业务层对象避免后续代码直接依赖 SDK 的Tag类型。public sealed class TagInfo { public string Name { get; set; } ; public string Description { get; set; } ; public string DataType { get; set; } ; public string Units { get; set; } ; } public IReadOnlyListTagInfo SearchTags( ServerConnection conn, string prefix, int pageSize 200) { var p new TagQueryParams { NamePattern prefix *, MaxNumber pageSize }; var q new TagQuery(conn); q.Query(p); var list new ListTagInfo(); foreach (Tag tag in q.Tags) { list.Add(new TagInfo { Name tag.Name, Description tag.Description ?? , DataType tag.DataType.ToString(), Units tag.EngineeringUnits ?? }); } return list; }prefix建议由配置表提供不要由前端直接拼。pageSize控制在 200 到 500 之间太大一次返回的元数据会占用内存太小又需要多次请求。MaxNumber不是游标命中数超过上限时不会自动翻页如果前缀命中太多按首字母或数字区间继续切片或者让现场导出一份点位清单做离线映射。DataType和EngineeringUnits要保留后面做量程校验和单位换算时用得上。3.2 把点名收敛到业务键业务代码里不要出现LINE1.TIC101.PV这种点名统一走映射表。映射表至少包含业务键、Historian 点名、工程单位、缩放系数和偏移量。缩放系数不要写死在查询语句里读出来之后统一应用写入之前做逆变换。业务键Historian 点位单位ScaleOffsetline1.reactor.tempLINE1.TIC101.PV℃1.00.0line1.reactor.pressureLINE1.PIC102.PVkPa0.10.0plant.energy.totalPLANT.KWH.TOTALkWh1.00.0这张表是 demo 里最该落到数据库或配置中心的部分。Scale和Offset用来处理原始值到工程值的线性变换比如原始整数 1234 表示 123.4 kPa就配Scale0.1。写入时用(value - Offset) / Scale反算别在两个地方各写一套。业务键命名要稳定不要把中文描述直接当键后面做多语言或报表改版会很难受。3.3 元数据缓存与失效点位元数据不会每秒变但也不能永久缓存。常见做法是进程内缓存 10 分钟点位不存在时不要缓存空结果避免现场刚建点、服务端还没同步时被负缓存拖住。下面这段用ConcurrentDictionary做最小缓存生产环境可以换成带过期的内存缓存组件。private static readonly ConcurrentDictionarystring, CacheItem TagCache new(); private sealed class CacheItem { public TagInfo Value { get; init; } public DateTime ExpireAt { get; init; } } public TagInfo GetTag(ServerConnection conn, string name) { var now DateTime.UtcNow; if (TagCache.TryGetValue(name, out var item) item.ExpireAt now) return item.Value; var p new TagQueryParams { NamePattern name, MaxNumber 10 }; var q new TagQuery(conn); q.Query(p); var tag q.Tags.FirstOrDefault(t string.Equals(t.Name, name, StringComparison.OrdinalIgnoreCase)); if (tag null) throw new InvalidOperationException($点位不存在: {name}); var info new TagInfo { Name tag.Name, Description tag.Description ?? , DataType tag.DataType.ToString(), Units tag.EngineeringUnits ?? }; TagCache[name] new CacheItem { Value info, ExpireAt now.AddMinutes(10) }; return info; }缓存键用 Historian 点名命中后直接返回业务层TagInfo。ExpireAt用 UTC避免服务器时区变化导致缓存提前或延后失效。点位不存在时直接抛错不写空缓存现场新增点位后最迟 10 分钟能自动恢复。若点位改名频繁缓存时间缩短到 1 到 2 分钟或者在配置变更时主动清空对应键。4. 历史数据读写采样模式、时间窗与批量写入历史数据这部分翻车最多的不是 API 调用而是采样模式和时间窗。原始点查询、按点数抽样、插值查询返回的曲线形状不一样报表上看到一个“尖峰消失”就怀疑 Historian 丢数实际是查询模式选错了。写入侧则相反接口返回成功不代表数据可查必须用原始查询回读确认时间戳、值和质量码都对得上。4.1 Raw、Interpolated、Lab 三种查询别混用模式适用场景主要代价RawByTime故障追忆、原始点对账点多时返回量大RawByNumber趋势预览、固定点数展示可能漏掉短时尖峰Interpolated日报、班报、固定周期报表受插值算法和边界影响Lab实验室数据、批次化验值与过程数据混用要单独标记故障追忆用原始点报表用插值或聚合趋势预览可以用按点数抽样。不要把RawByTime直接套在几个月的查询上也不要用插值结果做报警回放插值会平滑掉瞬时异常。demo 里通常把采样模式做成配置项业务层传枚举适配层再映射到 SDK 的SamplingMode。4.2 读历史数据的最小代码时间统一用 UTC 传入显示层再转本地时区。下面这段读原始点强制检查DateTimeKind.Utc避免本地时间混进查询窗口。SamplingInterval按现场最小采集周期设置不要为了“看起来平滑”把间隔设得比采集周期还小。public sealed class SampleRow { public DateTime TimeUtc { get; set; } public double Value { get; set; } public Quality Quality { get; set; } } public IReadOnlyListSampleRow ReadRaw( ServerConnection conn, string tag, DateTime startUtc, DateTime endUtc, int stepSeconds 1) { if (startUtc.Kind ! DateTimeKind.Utc || endUtc.Kind ! DateTimeKind.Utc) throw new ArgumentException(时间必须显式使用 UTC); var p new DataQueryParams(); p.Tags.Add(tag); p.StartTime startUtc; p.EndTime endUtc; p.SamplingMode SamplingMode.RawByTime; p.SamplingInterval TimeSpan.FromSeconds(stepSeconds); var q new DataQuery(conn); q.Query(p); var rows new ListSampleRow(); foreach (Sample s in q.Samples[tag]) { rows.Add(new SampleRow { TimeUtc s.TimeStamp.ToUniversalTime(), Value Convert.ToDouble(s.Value), Quality s.Quality }); } return rows; }这段代码的关键参数是StartTime、EndTime、SamplingMode和SamplingInterval。StartTime和EndTime必须是 UTCstepSeconds默认 1 秒现场采集周期是 5 秒就改成 5不要用 1 秒去“补”出并不存在的点。q.Samples[tag]按点名取样本集合若现场 SDK 返回的是扁平集合用Where过滤即可。Quality要保留后面报表要区分好值、坏值和不确定值。4.3 写入与回填质量码和批量提交写入不要逐点调用。一个点一次网络往返回填一万个点会非常慢。常见做法是每批 500 到 1000 条批量提交批次失败时整批重试并记录业务幂等键。质量码要显式设置回填数据不要一律给Good否则坏值会被洗成好值后面排查没有后悔药。public int WriteBatch( ServerConnection conn, string tag, IReadOnlyListSampleRow rows, int maxBatch 800) { var written 0; foreach (var chunk in rows.Chunk(maxBatch)) { var p new DataWriteParams(); p.Tags.Add(tag); foreach (var r in chunk) { if (r.TimeUtc.Kind ! DateTimeKind.Utc) throw new ArgumentException(写入时间必须是 UTC); p.Samples.Add(new Sample(r.TimeUtc, r.Value, r.Quality)); } var w new DataWrite(conn); w.Write(p); written chunk.Length; } return written; }maxBatch默认 800现场网络差就降到 200 到 300内网稳定可以到 1000。每批写入前检查时间戳Sample的时间统一用 UTC。Quality从上游数据带过来不要统一填Good。写入完成后不要只看返回值立刻用原始查询回读同一时间窗比对点数、时间戳、数值和质量码重复时间戳在不同采集器上的行为可能不同回填工具要有业务幂等键不能靠“覆盖”当幂等。5. 避坑排查连接、点位、时间与写入的四类翻车Historian 的问题有一个特点现象在业务层根因在连接层或点位层。报表说“没数据”可能是账号没有点位权限写入说“成功”可能是写到了另一个采集器。下面这几条是按现场排查顺序整理的每条都按“现象、原因、解决”走遇到问题先照着对一遍比在代码里盲改快得多。5.1 连接层的翻车位数不对与假在线现象控制台程序一启动就报BadImageFormatException或者引用明明加了运行时却提示找不到程序集。原因SDK 程序集是 32 位主程序以 x64/AnyCPU 启动或者引用的 DLL 被复制到了输出目录但依赖的附属程序集没带过去。解决把启动项目平台目标改成 x86清理输出目录后重新生成用任务管理器确认进程位数依赖程序集从现场 SDK 目录整体引用不要只拷一个 DLL。现象Connect没有抛异常但后面TagQuery返回 0业务层以为“没有点位”。原因连接成功只代表网络和认证过了不代表账号有点位读权限也不代表点位名拼写正确。解决用已知点位做精确探测不要用*做生产自检本文还有配套的精品资源点击获取