C#调用AF SDK高效读取PI实时数据实战指南-平芜编程栈

上个月给某化工厂做MES二期报表，对方IT负责人把数据库账号一丢：“你要的数据都在PI里，自己连吧。”我拿ODBC驱动怼了三天，查询效率惨不忍睹。后来换成AF SDK，几十个测点的实时曲线秒出。这篇文章就把这次实战踩出来的经验整理一遍，给同样要和PI实时数据打交道的C#工程师做个参考。

你在工厂里一定会遇到这类需求：大屏要显示当前温度、电流、流量，报表要拉最近一个月的趋势，MES系统要对PI里的测点做越限报警。PI系统里存的是带时间戳、带质量码的时序数据，不是传统关系型数据库里的业务表。想用C#读PI实时数据，教科书式的做法已经不够用了，关键是把访问通道选对、把模型理解透、把常见坑避开。

1. 先把PI的访问通道摸清楚，再动手写代码

1.1 四种常见读取方式，别一上来就查ODBC

我见过太多人拿到PI服务器地址后的第一反应是：写个SQL语句连过去查表。这确实是最容易想到的办法，但不是好办法。PI对外提供的访问入口主要有四条路。

访问方式	技术路径	适合场景	需要注意的问题
ODBC/JDBC直连	以SQL查询方式读PI归档数据	临时查数、简单历史报表	本质是关系型查询，读实时快照非常吃力，频繁查询会把PI服务器搞得很累
老版PI SDK	以PI点（Point/Tag）为中心，COM/.NET接口	老项目维护、现有脚本改造	面向点模型，没有资产对象概念，新项目不推荐再重新学
AF SDK	以资产模型（AF）为中心，连接PI Server	大多数新项目的主力方案，强烈推荐	有学习曲线，得先理解AF模型和PI点模型的关系
PI Web API	基于RESTful的JSON接口，走HTTP/HTTPS	跨平台、前端可视化、轻量集成	高频小点并发时HTTP开销大，不适合大量点循环拉取

ODBC方式为什么不适合做实时数据？因为PI内部的数据组织方式和SQL Server、Oracle完全不一样。PI存储的是“时间戳+值+质量码”的事件流，数据写入时按时间顺序归档，读取靠的是针对时间序列优化的底层引擎，而不是索引加扫描的关系表。你拿SQL查询去模拟“取当前最新值”这种操作，每次都要跑到归档文件里找边界，性能天然就差。加上ODBC驱动又是额外收费组件，网络策略上还得单独开端口，很多工厂的IT根本不愿意给ODBC端口开放。

1.2 数据从现场设备到C#应用，到底经过了哪些环节

要理解读取接口，先看PI整个数据链路。现场DCS、PLC或传感器先把信号送给采集服务器，常见方案是用OPC或Modbus协议；然后PI的采集接口组件负责把实时值写入PI Server的Data Archive（归档库）。PI Server内部维护了两套数据：一套是“快照”，保存每个测点最新的当前值，内存驻留、读取极快；另一套是“归档”，把历史事件按压缩算法存到磁盘文件里。

C#应用去读PI实时数据，本质就是两个动作：读快照拿当前值，读归档拿历史区间记录。而AF SDK同时把这两件事封装成了简洁的对象接口。理解这一点特别重要，很多测试脚本读起来慢，就是因为没搞清楚自己应该在快照里拿实时值，却非要去归档里“查最新一条”。

1.3 为什么主力方案是AF SDK

老版PI SDK也能读当前值，接口也很简单，我为什么劝你用AF SDK？核心原因有四个。

第一，AF SDK能利用资产模型。PI里的点通常叫“测点”或“Tag”，命名往往带着区域、设备、变量，比如“反应釜K101.温度”。老SDK直接面对这一串字符串；而AF SDK可以建模成“反应釜”这个对象下挂“温度”“压力”“液位”多个属性，读取时按对象、按属性导航，大规模项目里可维护性差太多了。

第二，AF SDK对.NET支持更现代。老SDK带一大堆COM互操作，部署时容易出权限问题，跑在.NET 6及以上环境里更是别扭。AF SDK可以在.NET Framework或现代.NET运行时下工作，遇到新老项目都能落地。

第三，批量读取能力强。AF SDK提供按点集合一次取值的接口，底层会做数据打包传输，比我写循环一个个点调用快一个数量级。报表场景里这个差距非常明显。

第四，除了实时值，AF SDK还能读历史归档、事件帧、数字状态、计算属性，将来做报警统计、设备效率分析都会用到，学习一次长期受益。

2. 环境和首个连接：让AF SDK在C#里跑起来

2.1 准备清单比想象的多

写代码之前，先把环境确认清楚。很多人卡住不是代码写错，是前置条件没满足。

你至少需要四样东西。第一，PI客户端的AF SDK组件，从PI系统官方下载渠道拿对应版本安装包，安装时选你用的开发语言对应组件。第二，PI服务器名称和通信端口，AF SDK默认走TCP 5450端口连接Data Archive，部分部署还会用到其他动态端口，要提前在PI服务器的防火墙规则里确认。第三，一个可用的PI账号，权限至少包含读取对应测点的权限，很多工厂用域账号集成认证，代码里不用传密码，但也有用基本认证的情况。第四，客户端机器和PI服务器在同一个网络域，DNS能解析到PI服务器名。

我遇到过一种很典型的“半小时没连上”问题：数据库连接串写的是IP地址，但PI Server名称解析用的是主机名，AF SDK内部通过PI服务器名去查找，IP写对了也白搭。所以连接代码里指定的服务器名，应该和PI系统管理员给你的服务器名完全一致。

2.2 最小连接代码：先证明链路是通的

环境准备好后，写一个最简单的连接测试。下面的示例基于AF SDK 2.10及以上版本的API命名，如果你的版本较老，类名和重载可能会有细微差别。

using OSIsoft.AF; using OSIsoft.AF.PI; public class PiConnectionTest { public static void Test(string serverName) { // 从本机已知的PI服务器集合中找到目标服务器 PISystem piSystem = new PISystems()[serverName]; // 连接PI Server piSystem.Connect(); Console.WriteLine($"连接状态: {piSystem.ConnectionInfo.Status}"); Console.WriteLine($"服务器描述: {piSystem.ConnectionInfo.ServerVersion}"); } }

这段代码背后发生的事情比表面看起来多。new PISystems()会扫描客户端本机已注册的PI服务器列表，然后按名称找到PISystem；Connect()会完成身份认证、建立到Data Archive的通信链路、初始化连接池。如果连接成功，你可以继续访问piSystem.PIDataServers拿到具体的Data Archive对象。

有一个容易忽略的细节：AF SDK连接是“重量级”操作，首次连接可能需要几秒甚至十几秒，中间还会有超时判断。这不是程序卡死，也不要在一段代码里频繁new和Dispose连接对象。正确用法是进程内复用同一个PISystem实例，线程安全访问，任务结束后再释放。

2.3 连不上时，从三个方向排查

如果Connect()抛了异常或者状态是Faulted，不要急着改代码，先按下面表格排查。

现象	大概率原因	处理方式
找不到名为XXX的PI服务器	服务器名拼错、DNS不解析、客户端未注册服务器	用`new PISystems()`遍历列表，确认注册名；用ping和nslookup验证网络
连接超时	防火墙拦截了5450端口，或网络隔离策略	找PI系统管理员确认端口是否放行；在客户端用telnet测试端口连通性
Access Denied / 无权限	当前Windows账号没有对应PI用户权限	切换账号或用基本认证；请管理员在PI系统里给账号分配测点读取权限

3. 三类高频实时读取场景的C#实现

3.1 读取当前实时值：拿快照，不要拿归档

读取某一个测点的最新值，是“实时读取”最核心的操作。PI的Data Archive会为每个点维护一个“快照值”，也就是最近一次写入产生的值。这个值存在内存中，读取速度极快。

using OSIsoft.AF; using OSIsoft.AF.PI; using OSIsoft.AF.Asset; public class PiReader { private readonly PISystem _piSystem; public PiReader(string serverName) { _piSystem = new PISystems()[serverName]; _piSystem.Connect(); } public AFValue GetCurrentValue(string dataServerName, string pointName) { PIDataServer dataServer = _piSystem.PIDataServers[dataServerName]; PIPoint piPoint = PIPoint.FindPIPoint(dataServer, pointName); return piPoint.CurrentValue(); } }

调用方式：

var reader = new PiReader("PISRV01"); AFValue v = reader.GetCurrentValue("PISRV01", "REACTOR_K101.TEMPERATURE"); Console.WriteLine($"时间: {v.Timestamp}"); Console.WriteLine($"数值: {v.Value}"); Console.WriteLine($"质量码: {v.Status}"); Console.WriteLine($"单位: {v.UOM?.ToString() ?? "无"}");

这里面有三个要点。

AFValue.Value动态类型，数值点返回double或float，字符串点返回string，数字状态点返回数字状态对象。做报表输出时一定要先判类型再格式化，不能想当然ToString。

AFValue.Timestamp返回的时间是UTC时间，不是本地时间。如果你直接绑定给前端图表，不转本地时区，显示出来的曲线会整整偏8个小时。后面第4章再展开。

AFValue.Status是质量码，里面藏着大坑。你看到PI里读出一个值，不代表这个值就是可靠的生产数据；质量码为坏质量时，数值可能是估算出来的，也可能是设备停运时的残值。怎么处理也放到第4章。

如果只是测试用，也可以直接读AF模型里的属性：

AFDatabase database = _piSystem.Databases["MES_DB"]; AFElement element = database.Elements["反应K101"]; AFAttribute temperatureAttr = element.Attributes["反应温度"]; AFValue attrValue = temperatureAttr.GetValue();

这两种方式读到的都是实时快照。区别在于，PIPoint.CurrentValue()更直接，适合你只知道测点名的情况；AFAttribute适合你知道资产路径、想按对象层级遍历的情况。实际项目里后者更优雅，因为它天然带着模型结构，读出来的值还附带单位的元数据。

3.2 读取历史区间：搞懂边界类型再取数

做趋势曲线、做日报表，都需要读取一段历史区间。这里最大的坑是“边界类型”。

using OSIsoft.AF.Time; public List<AFValue> GetHistory(string dataServerName, string pointName, DateTime startUtc, DateTime endUtc) { PIDataServer dataServer = _piSystem.PIDataServers[dataServerName]; PIPoint piPoint = PIPoint.FindPIPoint(dataServer, pointName); AFTimeRange timeRange = new AFTimeRange(startUtc, endUtc); IList<AFValue> values = piPoint.RecordedValues(timeRange, AFBoundaryType.Inside, "", false); return values.ToList(); }

注意RecordedValues的重载参数很多，核心第一个参数是时间区间，第二个参数就是AFBoundaryType。它决定查询结果的边界行为。

AFBoundaryType.Inside：只返回完全落在区间内部的事件记录。做统计报表时，这个选项最接近“这段时间真实发生了哪些数据变化”。
AFBoundaryType.Interpolated：区间两端自动补一个插值点，保证返回的第一个点和最后一个点正好落在边界时间上。做趋势曲线视觉效果好，但它可能生成“实际上不存在”的数据。
AFBoundaryType.Inside和Outside的差别，我举个直观例子：某温度点上午10点整有个事件，你要查9点到10点半的区间，用Inside就不包含10点整这跳数据，用Outside就把区间左右最近的事件也带进来。

我在做报表时基本默认用Inside，因为报表里每一行都要对应真实发生的生产过程事件。只有做曲线展示时，才考虑用Interpolated补点，图形更好看。

还有一个性能习惯：读取很长时间范围时，不要一次查一个月。PI归档数据本身压缩过，但一次查询跨度太大，服务器端要做大量的盘区扫描，很容易把PI服务器的性能拖下来。我现在的做法是把一个月拆成一天一天查，后台线程分桶并行拉取，最后在内存里合并。速度不慢，对PI服务器压力也小得多。

3.3 批量读取多个测点：循环调用是要挨打的

新手最容易写出来的代码是：

foreach (var tagName in tagNames) { var value = piPoint.CurrentValue(); // 循环里一个个查 }

这样写，点一多就把PI服务器打满。AF SDK提供了批量读取机制，核心思路是把一组PIPoint装进集合，一次请求发过去。

public Dictionary<string, AFValue> BatchGetCurrent(string dataServerName, List<string> pointNames) { PIDataServer dataServer = _piSystem.PIDataServers[dataServerName]; PIPointList pointList = new PIPointList(); foreach (var name in pointNames) { pointList.Add(PIPoint.FindPIPoint(dataServer, name)); } // 按点在集合中的顺序返回对应的当前值集合 IList<AFValue> values = dataServer.CurrentValues(pointList); var result = new Dictionary<string, AFValue>(); for (int i = 0; i < pointNames.Count; i++) { result[pointNames[i]] = values[i]; } return result; }

IDataServer.CurrentValues()这个批量接口返回的集合顺序和传入的点集合顺序是一致的，所以可以靠索引对齐。批量读取的实际收益在点数量超过20个后非常明显，一次网络往返搞定，效率是循环方式的几十倍。

关于异步，再补一句。AF SDK的Connect()和CurrentValue()是同步阻塞接口，在WinForm/WPF里直接调，界面会卡住。正确姿势是放到后台线程或Task里，再把结果通过事件、Invoke或数据绑定推回UI。如果你写的是ASP.NET Core服务，更要注意不要为每个请求创建独立PISystem连接，应该用依赖注入做成单例服务。

4. 生产环境里最容易踩的五个坑

4.1 时间戳：UTC和当地时间一定分清楚

这个坑我踩了三回才算长记性。AF SDK返回的时间是UTC，很多开发者在本地调试时没感觉，因为调试机器时区恰好和PI服务器一致。一旦部署到云服务器或跨时区环境，时间差马上暴露。

举个具体例子。某设备操作员在系统里看到“14:00报警”，但数据库里存的时间戳显示“06:00”，于是误判报警时间。这不是数据丢了，而是时间展示层没做时区转换。

处理原则两条：

内部存储、查询参数统一用UTC时间。构造查询区间时，用DateTime.UtcNow，或者用AFTime字符串带后缀“Z”，例如new AFTime("2025-02-11T08:00:00Z")。
界面展示时再转本地时间。前端图表组件如果支持时区属性，可以直接传本地时区名；如果是自绘文本，用TimeZoneInfo.ConvertTimeFromUtc。

4.2 质量码：读到的数值不等于可靠的生产数据

PI数据的“质量码”（Quality Code）极其重要。PI的数值不只包含大小，还带一个状态描述，常见状态包括：好质量、坏质量、清零、替换值、估算值、停机值等。默认状态下，很多PI点即使现场设备已经断线，也会在历史归档里留下“最后已知值”配合坏质量标记。如果你只读取Value字段，完全不管Status，报表里统计到的可能就是一堆断电瞬间的残值。

我在项目里养成了一个习惯：数据落入业务库之前，先做质量码过滤。逻辑大致是：

if (!afValue.Status.IsGood) { // 记录日志或者标记该值不可用 continue; }

注意，Status.IsGood只是一个布尔简化判断，实际生产中还可能存在“可疑”“置换”等中间状态，对应特定的质量码数值。稳妥的做法是把原始质量码也存进业务表，需要时再回溯分析。

4.3 归档查询的“无中生有”问题

用AFBoundaryType.Interpolated查历史数据时，如果某个时间段里根本没有事件记录，PI会按照前后事件做插值，硬生生造出一个时间点。这对趋势曲线没问题，画出来是连续的；但对统计报表就是灾难。比如某台泵实际运行了10分钟，中间没有事件，用Interpolated拉出来的每分钟一个点，会让你以为它一直稳定运行；而用Inside拉出来，可能只有起点和终点两条事件记录，才能反应真实启停。

结论很简单：历史统计一律用Inside，趋势展示视情况用Interpolated。如果数值变化频繁、事件很密，两者差别不大；如果测点变化稀疏，差别就非常大。

4.4 单位换算：别想当然地乘系数

PI点本身可以配置工程单位（Engineering Units），比如摄氏度、兆帕、立方米每小时。但这个单位更多是“标注性”的，PI存储的数值通常是采集上来时的原始工程值，比如DCS给的是0到100的量程百分比，那PI里存的就是0到100的小数，并不自动转成你想要的工艺量。

我做DCS数据对接时，就见过工艺人员抱怨“PI里温度明明是50，为什么换算后变成500”。原因出在PI点是按“百分比”存储的，而DCS的量程是0到500度，转换公式是实际值 = 量程下限 + 采集百分比 * (量程上限 - 量程下限)。这种换算关系，AF SDK不会替你算，必须自己从PI点的属性里读量程范围和单位元数据，再按公式处理。

所以建议里有一条：建点的时候尽量让PI采集接口直接存储工程单位下的实际值，避免在应用层反复换算。如果你无法控制建点规则，也要把换算规则写进配置中心，不要让每个报表各自理解。

4.5 连接对象和内存：服务跑几天就卡，多半是连接泄漏

AF SDK对象模型里，PISystem、PIDataServer这些对象默认实现了IDisposable。很多开发者只记得new，不记得Dispose，在循环或高频请求里反复创建连接，最终把进程的句柄数拉爆，服务越来越卡。

我踩过一次印象很深的故障：某数据同步服务上线两周后内存逐步上涨，最后整个Windows服务假死。排查后发现问题出在我每次处理一批测点时就new了一个PISystem，虽然局部变量会被GC回收，但内部连接资源并没有及时释放。

正确做法是这样的：

长时间运行的服务：全局只创建一个PISystem连接，作为单例复用。程序退出时再Dispose。
短命令行的工具程序：用using块包裹，确保连接随作用域释放。
多线程环境：同一个PISystem实例在AF SDK内部通常做了线程安全处理，但在拿值和批处理时，不建议多个线程并发写同一个集合对象，要有明确的边界。

如果非要频繁建立短连接，至少做成连接池：复用已建立的连接对象，不要裸new。

5. AF SDK与PI Web API的选型建议

5.1 PI Web API真香，但别拿它硬扛高频轮询

PI Web API是基于HTTP的RESTful接口，最大的优点是跨平台、不需要装SDK、防火墙策略好做。如果你写的是前端JavaScript应用，或者用Python做数据分析，走Web API顺手得多。C#里用HttpClient也能轻松调用。

读取当前值的HTTP请求大概长这样：

GET /piwebapi/streams?path=\\PISRV01\REACTOR_K101.TEMPERATURE&value=current

返回JSON：

{ "Timestamp": "2025-02-11T08:00:00Z", "Value": 92.5, "UnitsAbbreviation": "deg C", "Good": true, "Questionable": false, "Substituted": false }

C#侧用System.Text.Json反序列化即可：

public class StreamValue { public DateTime Timestamp { get; set; } public double Value { get; set; } public string UnitsAbbreviation { get; set; } public bool Good { get; set; } public bool Questionable { get; set; } public bool Substituted { get; set; } } public async Task<StreamValue> GetCurrentViaWebApi(string baseUrl, string pointPath) { using var client = new HttpClient(); client.BaseAddress = new Uri(baseUrl); string url = $"/piwebapi/streams?path={Uri.EscapeDataString(pointPath)}&value=current"; var json = await client.GetStringAsync(url); return JsonSerializer.Deserialize<StreamValue>(json, new JsonSerializerOptions { PropertyNameCaseInsensitive = true }); }

但Web API的短板也很明显：HTTP协议本身有消息头、连接握手、序列化开销，高频小点轮询时会把时间和带宽都消耗在协议上。我见过一个看板项目，前端每5秒拉20个点，走Web API直接把PI Web API服务拖到超时。后来改成边缘服务用AF SDK把数据回传到本地内存，前端走后端接口，问题立刻消失。