简介：面向西门子WinCC平台学习用户归档（User Archive）的实践案例包，适合已掌握组态基础、希望打通数据存储与检索环节的自动化工程师及工控自学者。内容围绕动作（Actions）与标准模块的协同展开，涉及归档触发条件设置、数据过滤与格式转换、压缩存储、归档间隔与保留期限等策略设计，可解决实时数据与历史数据难以规范落盘、后期报表与故障排查缺少依据的问题。压缩包共290个文件、约36.21MB，以250个rpl归档数据文件和配套mdf、ldf数据库文件为主体，辅以dum、dcf、pdl画面、xml与ini配置及脚本模块文件，完整保留了项目现场结构与运行痕迹，便于还原环境对照学习。已有1153人学习下载。读者可从中获得可复用的归档配置思路、模块调用方式与项目文件组织参考，通过模仿与调试逐步搭建起完整的用户归档系统。

1. 用户归档不是过程值归档：一条批次记录为什么要单独落一张表

配方号、批次号、投料量、操作员、开停机时间、检验结论——这些不是按周期采集上来的过程值，是一条一条发生在某个时刻的业务记录，写完基本不再改。把它们塞进过程值归档里，一个批次会散成几千行周期数据，做一次追溯还得自己拼时间窗、剔除停机段的断点。用户归档（User Archive）就是给这类数据准备的：一个归档对应一张自定义表，字段自己定，记录由 VBS 脚本或画面控件在事件点写入，和采集周期彻底解耦，事后能直接用 SQL 查、能按批次号过滤、能整表导出。这套案例适合已经在用 WinCC 做上位机、批次数据还靠 Excel 手工登记或者靠过程值归档硬凑的现场工程师；后面按字段设计、脚本写入、画面查询、SQL 侧校验四段拆，每一步都能直接抄。

2. 拆开一个用户归档：字段、表结构和写入链路

2.1 归档编辑器建出来的三样东西

在 WinCC 项目管理器里双击「用户归档」，新建一个归档，取名uaBatch，然后一个字段一个字段往里加。这一步做完，项目里实际产生了三样互相关联的东西，理解它们的对应关系，后面排错能省一大半时间。

第一样是归档定义本身，存在 WinCC 项目的组态数据里，包含归档名、归档大小（最大记录数）、是否循环、是否按数据集组织。第二样是元数据表，运行时要靠它知道「这个归档有哪些字段、每个字段是什么类型」，脚本里Fields("BatchNo")能不能取到值，取决于这里有没有登记。第三样才是真正的业务表，落在项目数据库里，表名以UA开头，归档里定义的每个字段变成表里的一列，每执行一次写入就多一行。

三者是「定义 → 元数据 → 物理表」的生成关系，所以有一条血泪经验必须提前说：归档的字段结构一旦开始灌数据，就不要再随便删字段或者改类型。删列、改类型这类操作在底层往往意味着重建表，已经写进去的历史记录大概率保不住。稳的做法是先在纸面上把字段列全，用几条假数据跑通流程，确认没有要补的列了，再清空归档正式投用。

顺带把一个常见误解拆掉：很多人下意识拿过程值归档和用户归档对比，然后问哪个「更省空间」。这不是一个维度的问题。过程值归档是按时间切片存连续量，适合画趋势、算平均值；用户归档是按事件存离散记录，适合做追溯和配方。同一个项目里两者可以并存，温度曲线走过程值归档，批次结论走用户归档，各干各的活，别硬凑。

2.2 五类字段类型怎么选

归档编辑器里能选的字段类型就那么几类，选错的代价往往要到项目跑了两三个月、数据攒到几十万行才暴露。下面这张表是我按现场使用频率排的，附上踩过的坑。

字符串字段是问题最集中的地方。设长度 20，操作员输入了个 22 个字符的工号加姓名，写入不会报错，存进去的就是前 20 个字符，等你三个月后做追溯才发现记录对不上人。稳妥做法是给关键标识类字段留足余量，同时在画面输入控件上做长度校验，双重保险。

浮点字段的坑在查询侧。用浮点存重量，然后写过滤条件「重量等于 100.5」，大概率一条都查不出来，因为存进去的是 100.49999999。要做等值过滤的字段,干脆存成整型乘以 1000 的定点数，或者查询时用区间判断。

日期时间字段是新手翻车率最高的。从 PLC 或者画面取上来的时间，如果中途被转成字符串再赋值给字段，写入要么失败要么变成空值。正确做法是保持它是日期类型一路传到底，脚本里只做格式化显示，不做类型转换。

2.3 一次 Write 到底发生了什么

知道链路长什么样，排错才有方向。VBS 里调用Write的那一行，背后是这样一条路径：运行时先检查归档是否存在、当前客户端有没有写权限，然后把Fields集合里每个字段的当前值按定义的类型做一次校验和转换，接着通过 WinCC 的数据通道提交到项目数据库，数据库侧插入一行，最后回调给归档对象、更新ArchiveValueID。整个调用是同步的，写完才返回，所以在高频率触发点里连续写会明显感觉到画面卡顿。

' 最小写入骨架：把当前批次信息写进 uaBatch 归档 ' 归档名和字段名都必须和归档编辑器里定义的完全一致，区分大小写 Dim ua Set ua = HMIRuntime.UserArchives("uaBatch") ua.Fields("BatchNo").Value = HMIRuntime.Tags("s_BatchNo").Read ua.Fields("Product").Value = HMIRuntime.Tags("s_Product").Read ua.Fields("Qty").Value = HMIRuntime.Tags("r_TotalQty").Read ua.Fields("StartTime").Value = HMIRuntime.Tags("t_BatchStart").Read ua.Fields("Operator").Value = HMIRuntime.Tags("s_LoginUser").Read ua.Write Set ua = Nothing

这段代码里，HMIRuntime.UserArchives("uaBatch")拿到的是归档对象，参数是归档名而不是数据库表名，这两者在现场经常被混为一谈。中间五行是把变量值逐个塞进字段，左边的字符串是字段名，右边的.Read是读 WinCC 变量当前值。最后一行Write才是真正落库的动作，前面五行只是准备数据，不写这一行什么都不会发生。

参数上还有两个必须注意的点。一是字段类型要和变量类型对得上，Qty定义成浮点，变量就得是浮点或者整型，如果变量是个字符串类型的内部变量，.Read回来的是文本，赋值给浮点字段要么被隐式转换、要么直接失败。二是要留意变量质量位，.Read只返回值不管质量，通讯断了的时候它返回的是最后一次有效值或者 0，不判断质量位就写库，会往归档里灌一批看起来正常、实际是陈旧的假数据。

写入失败时看哪里？先看 WinCC 的运行日志和全局脚本诊断窗口，脚本语法错误、对象不存在这类问题都会在那里留下痕迹；再看归档对象本身，Write之后立刻读一下ArchiveValueID，如果它没变化，说明这一行根本没落库。

3. VBS 写入的四种姿势与一套可抄的骨架

3.1 四条写入路径的边界

同一个归档，现场至少有四种往里写数据的方式，选错路径带来的维护成本差别很大。

第一种是画面控件手工录入，调试期非常好用，运行期基本只用于补录和修正。第二种是 VBS 脚本写入，按按钮、按变量变化、按计划任务触发，是生产环境的主力。第三种是配方模式，用RecipeWrite按数据集名整组覆盖，适合「一个产品对应一组参数、参数整体切换」的场景。第四种是外部程序直连数据库写表，看起来最灵活，实际最危险——绕过了 WinCC 的锁和索引维护，轻则控件显示错乱，重则归档对象状态和数据库不一致，出问题几乎没法排查。

我的建议很明确：能用脚本就不要手工，能用归档对象就不要直连数据库。只有在做纯只读报表的时候，才走 SQL 直查这条线，而且是通过视图，不给外部程序写权限。

3.2 建归档的六个步骤

动手之前把这六步走完，后面写脚本基本不会卡。

第 3 步那个「是否循环」是整个流程里最容易被忽略的开关。选不循环，记录数写到上限之后，后续的Write调用不会报错、不会抛异常，就是默默写不进去。等你发现的时候，可能已经丢了一个月的批次数据。现场设备数据量可控的话，建议直接开循环，同时把导出任务挂上，别指望人工清理。

3.3 带锁的写入脚本

多客户端同时写同一个归档时，不带锁的脚本会出现覆盖和错行。归档对象提供Lock和Unlock，把「定位—修改—提交」这三步圈起来，是成本最低的防并发手段。

' 带锁的批次结束写入：先定位到当前批次记录，锁住，改完再放 Dim ua, sBatch Set ua = HMIRuntime.UserArchives("uaBatch") sBatch = CStr(HMIRuntime.Tags("s_BatchNo").Read) ' 过滤器是 WHERE 子句的写法，不带 WHERE 关键字 ua.Read "BatchNo = '" & sBatch & "'" If ua.Fields("BatchNo").Value = "" Then ' 没读到记录，说明是首次写入，直接建行 ua.Fields("BatchNo").Value = sBatch ua.Fields("Product").Value = HMIRuntime.Tags("s_Product").Read ua.Fields("StartTime").Value = Now ua.Write Else ' 记录已存在，锁住再改结束时间和结论 ua.Lock ua.Fields("EndTime").Value = Now ua.Fields("Result").Value = HMIRuntime.Tags("i_Judge").Read ua.Write ua.Unlock End If Set ua = Nothing

这段逻辑的关键在判断分支。Read带过滤器之后，如果没命中记录，字段值是空的，用主键字段判空是最直接的判断方式。首次写入走的是新建分支，不需要锁；已经存在的记录走修改分支，Lock之后才改，改完Write，再Unlock。

Lock锁住的是当前定位到的那条记录（配方模式下锁的是整个数据集），锁的粒度决定了并发能力。单条记录锁的代价很小，但有一个必须遵守的纪律：Lock和Unlock必须成对出现，中间不管发生什么异常都要保证解锁。稳妥写法是在Lock之后立刻把主体逻辑包进错误处理，Unlock放到收尾段，别指望脚本某一行报错之后运行时替你解锁——锁不释放，其他客户端会一直卡在写不进去的状态，而且看不出任何报错。

3.4 读回、过滤与遍历

写入解决的是存，读回解决的是用。归档对象的Read方法接受一个过滤器字符串，语法就是 SQL 的 WHERE 子句内容，日期和字符串字面量要带单引号。

' 按时间区间读一批记录并逐条处理 Dim ua, dtFrom, dtTo, sFilter, n Set ua = HMIRuntime.UserArchives("uaBatch") dtFrom = DateAdd("d", -1, Now) ' 最近 24 小时 dtTo = Now ' 日期格式化成 yyyy-mm-dd hh:nn:ss，避免区域设置差异导致解析失败 sFilter = "StartTime >= '" & FormatDateTime(dtFrom, 2) & " " & FormatDateTime(dtFrom, 4) & "'" & _ " AND StartTime <= '" & FormatDateTime(dtTo, 2) & " " & FormatDateTime(dtTo, 4) & "'" ua.Read sFilter n = 0 Do While ua.Fields("BatchNo").Value <> "" n = n + 1 ' 这里可以对每条记录做统计、累加、导出 ua.Move 1 ' 指针后移一条，参数为 0 表示原地 Loop

Move是遍历的核心，参数 1 表示向后移动一条，移动到末尾之后主键字段变空，用这个作为循环结束条件。这里有个细节坑：Move的行为在不同版本上略有差异，稳妥做法是在循环里加一个最大次数保护，避免死循环把运行时拖死。

过滤器的书写要注意地区设置。日期字面量写成2024/1/1在某些系统区域设置下能解析，换一台机器就失败；统一用FormatDateTime显式格式化成yyyy-mm-dd和hh:nn:ss再拼，跨机器就稳了。

3.5 触发时机的选择

脚本写好了，什么时候调它决定了数据质量。按变量变化触发最省事，也最容易重复写。一个布尔变量从 0 翻到 1，如果这个变量本身有抖动，或者脚本执行时间超过了扫描周期，同一条批次可能被写进去三四遍。

我的做法是加一层状态机：变量触发只负责置一个「待写入」标志，真正的写入放在独立的周期脚本里，判断标志为真且当前批次号在归档里还不存在，才执行写入，写完清标志。多花二十行代码，能省掉后面几周的数据清洗。

计划任务适合做班次汇总和日终结算，但要留意运行时启动时计划任务会不会立刻补跑一次，补跑逻辑没写好，凌晨重启会出现一条重复的空批次记录。

4. 画面端落地：控件绑定、自定义查询与导出

4.1 UserArchive 控件的配置项

画面里拖一个 UserArchive 控件出来，右键属性，需要配的东西就那么几项，但每一项都直接影响使用体验。

「过滤条件必须设」这条不是洁癖。一个跑了半年的归档，几十万行记录，控件一打开就全量加载，画面能卡到鼠标都动不了，而且在低配工控机上这个操作还可能直接把运行时拖崩。初始过滤设成「最近 7 天」或者「当前批次」，配合画面上的时间范围选择，体验完全不一样。

4.2 控件做查询画面的落地顺序

先放控件、绑归档、配列，然后放三个输入控件：起始日期、结束日期、批次号关键字。查询按钮里挂一段脚本，把用户输入拼成过滤器，赋给控件的过滤属性，再触发刷新。

' 查询按钮：按界面输入的条件刷新区件显示 Dim oCtrl, dtFrom, dtTo, sKey, sFilter ' 控件名按你画面里实际的对象名替换 Set oCtrl = ScreenItems("uaBatchCtrl") dtFrom = ScreenItems("dtpFrom").DateTime dtTo = ScreenItems("dtpTo").DateTime sKey = Trim(ScreenItems("ioBatchKey").Text) sFilter = "StartTime >= '" & FormatDateTime(dtFrom, 2) & " " & FormatDateTime(dtFrom, 4) & "'" & _ " AND StartTime <= '" & FormatDateTime(dtTo, 2) & " " & FormatDateTime(dtTo, 4) & "'" If Len(sKey) > 0 Then sFilter = sFilter & " AND BatchNo LIKE '%" & sKey & "%'" End If oCtrl.Filter = sFilter ' 属性名以实际控件为准 oCtrl.Update ' 触发一次刷新

拼过滤器时LIKE的模糊匹配很好用，但要注意两点：一是关键字里如果包含单引号，拼出来的语句会语法错误，输入侧要么限制字符、要么做转义；二是LIKE '%关键字%'用不上索引，记录量大了会慢，能精确匹配的时候就别用模糊。

日期输入控件我给的是日期选择器，取.DateTime属性，别让操作工在文本框里手打日期——现场十个手打九个格式不对。

4.3 SQL 视图 + ADO 做自定义报表

控件能解决「看」，解决不了「算」。要做班次产量汇总、月度合格率这类统计，绕不开 SQL。但我不建议报表脚本直接去查底层表，一是表名和字段名带前缀，写死在脚本里，归档一改名全废；二是底层表结构不该暴露给业务脚本。中间加一层视图，把脏活隔离掉。

-- 在 WinCC 项目数据库里建只读视图，屏蔽底层表名和字段前缀 -- 表名请在 SSMS 里按 UA 前缀找，替换成你项目里实际的表 CREATE VIEW vw_BatchReport AS SELECT BatchNo, Product, Qty, StartTime, EndTime, Operator, Result FROM UAuaBatch;

建好视图之后，脚本侧只认vw_BatchReport，归档表结构怎么变，只要视图跟着改一行，上层脚本一行不动。

' 用 ADO 查视图，统计指定时间段的合格率 Dim conn, rs, sConn, sSQL, nTotal, nOk ' 连接串里的库名和认证方式按现场实际改，口令不要写死在画面脚本里 sConn = "Provider=SQLOLEDB;Data Source=.\WINCC;Initial Catalog=<项目库名>;Integrated Security=SSPI;" sSQL = "SELECT COUNT(*) AS Total, " & _ "SUM(CASE WHEN Result = 1 THEN 1 ELSE 0 END) AS OkCnt " & _ "FROM vw_BatchReport WHERE StartTime >= '2024-01-01'" Set conn = CreateObject("ADODB.Connection") conn.Open sConn Set rs = conn.Execute(sSQL) If Not rs.EOF Then nTotal = rs("Total") nOk = rs("OkCnt") End If rs.Close conn.Close Set rs = Nothing Set conn = Nothing

参数上有三处要按现场改：Data Source是实例名，本机默认实例一般写.\WINCC；Initial Catalog是项目数据库名，去 SSMS 里看一眼就知道；认证方式用SSPI走 Windows 集成认证最省事，用 SQL 账号就要在连接串里带用户名口令，而口令写进画面脚本等于公开，生产环境别这么干。

这套查询放在按钮里同步执行，数据量大时会卡界面。记录超过十万行的项目，把统计结果缓存到一张中间表，用计划任务在夜间重算，画面只读缓存。

4.4 CSV 导出脚本

操作工最认的还是 Excel。导出的实现就是遍历归档、拼字符串、写文件。

' 把当前过滤结果导出成 CSV，Excel 可直接打开 Dim ua, fso, f, sLine Set ua = HMIRuntime.UserArchives("uaBatch") ua.Read "StartTime >= '" & FormatDateTime(DateAdd("m", -1, Now), 2) & " 00:00:00'" Set fso = CreateObject("Scripting.FileSystemObject") Set f = fso.CreateTextFile("D:\Export\Batch_" & FormatDateTime(Now, 2) & ".csv", True, True) f.WriteLine "批次号,产品,数量,开始时间,结束时间,操作员,结论" Do While ua.Fields("BatchNo").Value <> "" sLine = ua.Fields("BatchNo").Value & "," & _ ua.Fields("Product").Value & "," & _ ua.Fields("Qty").Value & "," & _ FormatDateTime(ua.Fields("StartTime").Value, 2) & "," & _ FormatDateTime(ua.Fields("EndTime").Value, 2) & "," & _ ua.Fields("Operator").Value & "," & _ ua.Fields("Result").Value f.WriteLine sLine ua.Move 1 Loop f.Close Set f = Nothing Set fso = Nothing

CreateTextFile的第三个参数设成True是 Unicode 编码，中文表头在 Excel 里不会乱码；设成False就是 ANSI，某些环境下打开是乱码。目标路径要确认运行账户有写权限，工控机上D:\Export这种目录经常是只读的，脚本会静默失败，日志里只留一行权限错误。

5. 避坑：用户归档跑不起来时，先看这五个地方

5.1 归档对象取不到，脚本报「对象不支持该属性或方法」

现象：脚本执行到HMIRuntime.UserArchives("uaBatch")就中断，诊断窗口里是一句「对象不支持该属性或方法」或者干脆拿到Nothing。

原因按概率从高到低排：项目里压根没添加「用户归档」编辑器，集合是空的；归档名拼错或者大小写不一致；归档编辑器存在但当时没激活；再往下就是授权——用户归档属于需要单独授权的选件，授权缺失时归档对象建不起来，脚本层看到的就是空集合。

解决顺序是先确认项目树里有没有那个节点、归档名逐字符核对，再打开授权管理器看选件的授权状态。最后这条最容易被排到最后，因为前几条都太常见了，反而把真正的原因盖住。

5.2 记录写进去了，字段值是空的或者全是 0

现象：Write没报错，控件里能看到新行，但主键字段是空的，数值字段全是 0，时间字段显示成 1899 年。

原因基本是赋值环节出的问题。要么是字段名写成了变量名，两边名字长得像；要么是类型不匹配，把字符串变量赋给浮点字段，运行时没抛错但值丢了；要么是读取的变量当时质量位不好，.Read返回的是默认值 0。

解决靠三张对照：归档字段清单、脚本里的字段名、变量表里的变量名，三张表逐行比对。类型问题在赋值前做一次显式转换，日期字段直接赋Now而不要赋格式化后的字符串。质量位问题在读值之后先判断.QualityCode，不为 192 就不要写库，宁可这一条留空等人补录，也别往里灌假数据。

5.3 同一批次出现多条记录，时间戳还扎堆

现象：一个批次号在归档里有三四条记录，开始时间相差不到一秒，结束时间全是空的。

原因是触发点重复执行。变量沿触发碰上变量抖动，或者画面按钮没做防连击，操作工手快点了两下，脚本就跑了两遍。还有一种是计划任务在运行时重启时补跑，把当天已经执行过的逻辑又跑了一次。

解决分两层：脚本内部先做幂等判断，写入前用主键Read一次，命中就改成更新而不是新增；外部加防抖，按钮脚本第一句先禁用自身、最后一句再启用，变量触发用状态机过渡，别直接挂写入逻辑。

5.4 控件显示条数和数据库里对不上

现象：SQL 里COUNT(*)出来是五千多条，画面控件里只显示几百条，或者反过来，控件里能看到记录，SQL 查视图查不到。

前者通常是过滤条件残留。控件上一次查询时设置了时间范围，下次打开画面没有重置，看起来就是「数据丢了」。后者多半是归档满了且设成不循环，新的写入被静默丢弃，或者视图建在了错误的表上、字段名对不上导致筛选条件失效。

排查方法很笨但有效：控件侧先把过滤条件清空，看总数能不能对上；对不上就直接在 SSMS 里SELECT COUNT(*)打底。两边都确认之后，再回头查归档属性的循环设置和视图定义。

5.5 数据库文件一路膨胀，还原之后归档打不开

现象一：项目数据库的日志文件涨到几十个 G。原因是归档里塞了二进制字段，加上长期没有清理策略，事务日志从不收缩。现象二：把备份还原到另一台机器后，画面控件报无法显示数据，或者归档对象直接不可用。

前者的解法是两件事：二进制字段能不用就不用，非要存附件就把文件放到共享目录、归档里只存路径；同时给归档设最大记录数并开循环，再挂一个定时导出任务把历史数据挪出去。

后者的关键是还原顺序。还原数据库之前必须先停掉运行系统，还原完成后检查归档元数据和物理表是否一致，不一致的话在归档编辑器里打开对应归档，通常能触发一次结构校验。千万别在运行时还在跑的时候去覆盖.mdf文件，那是给自己制造一个解不开的黑匣子。

6. 进阶：循环归档、备份策略与一条一致性校验语句

归档跑起来只是开始，能不能长期稳定跑，取决于三件事：满了怎么办、丢了怎么恢复、数据准不准。

「满了怎么办」在归档属性里设，最大记录数和是否循环两个参数决定行为。循环归档到上限后覆盖最旧记录，适合只关心近期数据的场景；不循环则写满即停，适合需要长期留存的批次记录，但必须配套导出，否则就是定时炸弹。我在现场的组合是：归档设循环、上限按三个月数据量估算，同时挂每日凌晨的导出任务把新增记录追加到外部文件，两头都不丢。

「丢了怎么恢复」有三条路，成本差别很大：

我的习惯是三条都留：每月一次项目复制、每周一次数据库备份、每天一次 CSV 导出。前两条保配置和历史，第三条是给业务部门看的，也是最容易验证的一条。

「数据准不准」靠校验。最简单的一条语句，每次改动归档结构或者做数据迁移之后都跑一遍：

-- 条数校验：和画面控件显示的总数、导出文件的记录数三方对齐 SELECT COUNT(*) AS RecCnt, MAX(StartTime) AS LastTime FROM vw_BatchReport; -- 元数据校验：确认归档里定义的字段都还在 SELECT COUNT(*) AS FieldCnt FROM <元数据表> WHERE <归档标识列> = 'uaBatch';

第一句查业务表的记录数和最新时间，第二句查元数据里的字段数量。三个数字对上了——控件条数、SQL 条数、导出文件行数——心里才踏实。数字对不上就先别往下走，八成是过滤条件、视图定义或者循环覆盖在作祟。

从那以后我每次动归档结构之前，都会先跑一遍这三方校验并把结果截图存档，改完再跑一遍对比，只要有一个数字对不上就回滚，不给自己留「大概是缓存没刷新」这种自我安慰的余地。希望帮到你。

本文还有配套的精品资源，点击获取