File

把其他程序写在本地或网络文件夹中某个文件里的值（试验机的 CSV、数据记录仪的日志、JSON 或 XML 格式的结果）作为点位读取，并为其他程序写入行或整个文件：“文件夹和文件”“文件文本”“写入”三张卡片，点位在每种格式中读取什么，收件文件夹，为每一列或每个字段提供一个点位的扫描，三个完整示例，以及驱动不做的事。

File 驱动读取其他程序写入文件的值：试验机在每个样品之后追加一行的 CSV、数据记录仪的日志、JSON 或 XML 格式的结果文件、只含一个批号的文本文件。每个点位读取文件中的一个值，它的值和其他任何点位的值一样送达各处：Logic、仪表画面，以及 Process 测试台的运行记录。在设备允许时，驱动也为其他程序写入：向文件追加一行，或替换整个文件。

读取是主要用途，只需要三个答案：文件夹、文件和它的格式。文件文本的读法（编码、列分隔符、小数分隔符）在保持识别时从文件本身读出，扫描为每一列或每个字段提供一个点位，每个点位新建时都是只读。属于写入的内容，只有在设备打开写入之后才会出现。

本驱动的一台设备就是一个文件夹以及它在其中读取的文件：同一文件夹中的两个文件是两台设备。文件夹是驱动器加文件夹（C:\TestMachine\Logs），或网络共享加其下的文件夹（\\lab-pc\results），工作站用运行它的账户的 Windows 权限访问它。设备位于驱动之下，可以归入文件夹，与任何没有串行线路也没有 MQTT Broker 的驱动一样，形成 驱动 → 文件夹 → 设备 → 点位。

驱动页面

标题下的一行写着“每台设备读取一个文件，或到达某个文件夹的文件。添加设备，填写其文件夹、文件和格式，然后扫描它，把其中的值添加为点位。”对有“配置 Connector”权限的角色，页面上有本驱动自己的扫描范围卡片，里面是扫描要读取的文件（见设备发现）。它下面是任何驱动都有的设备表（见设备表），用标题右侧的添加设备增加；为空时显示“还没有设备。”驱动的命令栏上有发现设备，在扫描范围卡片填写完整之前呈灰色。本驱动列在文件和数据库之下，在每个驱动列表中，这个类别位于 Web 与 API 和测试之间。

设备

本驱动的设备没有“连接”卡片：文件夹和文件卡片占据它的位置，后面是文件文本卡片，在读取单个文件的设备上还有写入卡片。“设备”卡片的轮询间隔（ms）默认为 1000，表示点位多久读取一次文件，与任何驱动一样，每个点位都可以覆盖它。

新设备没有文件夹：显示“尚未填写文件夹”，它的页面写着“在这台设备填写文件夹之前，工作站不会读取它，因此暂时不读取任何数据，也没有错误可显示。在下面的‘文件夹和文件’卡片里填写文件夹，工作站就会开始读取。”在填写文件夹之前不读取任何内容。标题栏显示的 Base URI 就是运行时地址，文件夹和名称以 URI 形式书写，后面是没有设为识别的设置：file://single?folder=C%3A%5CTestMachine%5CLogs&name=Log_%7Byyyy-MM-dd%7D.csv&format=delimited，收件文件夹则为 file://inbox?...。

“文件夹和文件”卡片

带日期部分的名称用花括号书写，里面是 .NET 日期时间格式，按工作站自己的时钟：Log_{yyyy-MM-dd}.csv 今天是 Log_2026-10-03.csv，过了午夜就是第二天的文件，而 Data_{yyyy-MM}.txt 每月更换一次。框下方，卡片显示它现在对应哪个文件：“今天：Log_2026-10-03.csv”。双写的花括号 {{ 和 }} 是名称中的花括号。日期部分从不写冒号，因为文件名不允许冒号：写 {HH-mm}，不写 {HH:mm}。

设备运行后，卡片会说明它读取的是哪个文件：

卡片无法接受的设置会在卡片下方说明，改正之前设备不会保存：

保存时遵守相同的规则，拒绝时操作记录条会这样说：“设备‘Tensile tester’有驱动无法使用的文件设置。请打开它并修正面板标出的字段。”

“文件文本”卡片

文件的字符、列和数字如何读取。每项设置一开始都是从文件识别，驱动从正在使用的文件中读出它。保持这样的设置下方，在设备读过文件之后，会有一行说明它发现了什么，例如“在文件中发现：UTF-8”。对于前几行看不出来的文件，可以选择任一设置把它固定下来。

“写入”卡片

读取单个文件的设备有写入卡片；收件文件夹只被读取，没有这张卡片。

只有在设备没有任何点位写入时，才能关闭写入。仍有点位写入时，开关保持显示并呈灰色，并说明原因：“此设备有 2 个点位会写入文件。关闭写入前，请先把它们设为只读。”（只有一个点位时为“此设备有一个点位会写入文件。关闭写入前，请先把它设为只读。”）。

在线、等待和离线

点位寻址

点位读取什么

本驱动的点位没有自己的地址框：它的信号源卡片询问它读取什么，对于值，还询问值在设备格式中的位置。

信号源不能读取为的类型会被拒绝，并列出可以读取为的类型：“请从可读取为的数据类型中选择一个：Int64。”选择另一个信号源会带来它自己的类型。从文件中取出的文本，按点位的类型读取，方式与 Generic serial and TCP 驱动读取消息相同，并使用文件的小数分隔符：Boolean 读取 1、true、on 或 yes 和 0、false、off 或 no，整数读取整数，String 按原样取字符，所以像 0412 这样的代码只有作为 String 才保留开头的零。

每个点位新建时都是只读，在不允许写入的设备上，访问字段不提供其他选项。设备允许写入后，读取数值或整个文件的点位可以设为读写或只写，读取文件名的点位可以设为读写；文件信息（是否存在、大小、最后修改、行数）永远不会被写入：“文件信息无法写入。请让点位保持只读。”

CSV 与分列文本

用双引号括起来的字段可以包含分隔符；包含换行的字段不会被读取。字段无法工作的点位不会保存，它的页面会说明缺少什么：

只读的源地址（总线）一行显示驱动收到的内容：column?name=Force 表示最后一行的 Force，column?number=3&row=number&rowNumber=5 表示第五行的第三列，column?name=Force&row=match&key=Sample&equals=0412 表示样品 0412 的那一行。

自由文本

位置和字段从 1 开始计数，模式是 .NET 正则表达式，恰好有一个包住数值的捕获组，读取时间超过 250 ms 的行不会被读取。拒绝信息与通用驱动本身相同，例如“请填写数值的第一个字符位置，从 1 开始数。”或“模式必须恰好有一个包住数值的捕获组。”总线地址写作 line 加上适用的部分，例如 line?row=match&contains=Result&extract=regex&pattern=...。

JSON 与 XML

JSON 数字、true 或 false 按原样取用，字符串按点位的类型读取；对象或列表只能作为 String 读取，即它的 JSON。JSON 或 XML 文档在变化时整体读取，最多 4 MiB，不读取任何 DTD。总线地址为 json?path=result.force 或 xml?path=Result%2FForce。

读取

每次读取时，驱动向 Windows 询问文件的大小和时间，这在网络共享上同样有效，而 Windows 的变更通知在那里无效；只有其中之一变化时才打开文件。它总是以共享读、写和删除的方式打开文件，因此写入该文件的程序从不会被阻塞。

每个读数的时间戳是文件的最后修改时间，而不是读取的时刻，所以运行记录会把样品放在另一个程序写入它的时刻。

收件文件夹

读取来源设为收件文件夹，用于每个样品写一个文件的设备（Test_0412.json、Test_0413.json……）：每个符合模式的新文件按到达顺序读取一次。

从不删除任何内容：子文件夹 Processed 会一直增长，直到有人清空它。收件文件夹从不被写入。

写入

在读取单个文件且允许写入的设备上，读取数值或整个文件、访问方式包含写的点位，会说明一次写入做什么：

{value:FORMAT} 接受 .NET 数字格式，{datetime:FORMAT} 接受 .NET 日期时间格式，按工作站的时钟，未给出时为 yyyy-MM-dd HH:mm:ss。数字用文件的小数分隔符书写，所以同一个模板在使用逗号的文件中写成 12,50。Boolean 点位的模板可以省略 {value}：写入真时会追加该行，就像一条命令。驱动无法填充的模板会在点位页面上被拒绝：

名称所指向的文件夹和子文件夹，会在写入需要时创建，并且总在设备的文件夹之内。

设备发现

“扫描范围”卡片

对有“配置 Connector”权限的角色，驱动页面上有它的扫描范围卡片，卡片下方的一行是“读取一个文件，为找到的每个列或字段以及文件信息各提供一个点位。请选择设备以读取其文件，或输入文件夹、文件和格式。”

范围仍缺少的内容会以红字显示在卡片下方，范围完整之前，发现设备一直呈灰色：

要扫描的设备有无法保存的修改时，扫描不会开始：“设备发现没有开始，因为要扫描的设备的修改无法保存。”

扫描提供的内容

扫描读取单文件设备现在读取的文件，或收件文件夹中最新的文件（扫描不移动它）；文件不存在、文件夹无法访问、文档无法解析，都会使扫描附原因结束。它提供一个候选项，把找到的值作为候选点位，全部为只读：

一次扫描最多提供 500 个值，CSV 文件的列也算在内；在此截断的扫描会在结束扫描的那一行和扫描结果上方显示“result.json 的扫描提前停止。一次扫描最多提供 500 个值：请按列、JSON 路径或 XML 路径将其余的值添加为点位。”

输入的文件的候选项以文件命名（run.csv 为 run），名称带日期部分或是收件文件夹时，以文件夹命名。文件夹、名称和读取来源都已被本驱动某台设备读取的候选项（被扫描的设备，或另一台相同的设备），标为已经配置过：它的卡片只列出该设备尚无点位读取的值，并已勾选，添加所选点位位于打开之前，把勾选的值添加到该设备，均为只读。扫描的其余行为见设备发现。

设备自己的页面不经过驱动页面也能做同样的事：“点位”卡片标题栏里的发现点位按设备保存的样子读它的文件，只列出它还没有点位的值（见发现一台设备的点位）。

示例：试验机的每日 CSV

一台拉伸试验机每天在 C:\TestMachine\Logs 中写一个 CSV，名为 Log_2026-10-03.csv，标题行为 Sample;Force;Elongation，每个样品之后写一行，例如 0412;12,5;3,1。按简单路径读取它：

1. 在驱动页面点添加设备；命名为 Tensile tester。
2. 在文件夹和文件卡片中，文件夹路径填写 C:\TestMachine\Logs，文件名填写 Log_{yyyy-MM-dd}.csv；保持单个文件和 CSV 与分列文本。卡片显示“今天：Log_2026-10-03.csv”，设备读取它之后显示“正在读取：Log_2026-10-03.csv”。文件文本卡片保持从文件识别：它会找出分号和小数逗号。
3. 在驱动页面的要扫描的文件中选择 Tensile tester，然后点发现设备。候选项标为已经配置过，列出 Sample（String，保留 0412 的零）、Force 和 Elongation（Double），以及文件信息。点添加所选点位。

每个点位读取最后一行；最后修改随每个新样品变化，Logic 的动作由此知道有样品到达。到了午夜，设备转向第二天的文件，在试验机写出它之前，这些值没有读数，文件是否存在读为假。智能体用工具也能做到：

device_upsert name="Tensile tester" driver=File fileFolder="C:\TestMachine\Logs" fileName="Log_{yyyy-MM-dd}.csv" fileFormat=Delimited
device_discover driver=File fileDevice="Tensile tester"
tag_upsert device="Tensile tester" name=Force address=Force opcUaType=Double
tag_upsert device="Tensile tester" name=Sample address=Sample opcUaType=String
tag_upsert device="Tensile tester" name="Last change" fileSource=Modified

示例：JSON 结果文件的收件文件夹

一个试验单元每个样品在 C:\Results\Inbox 中放一个结果文件，例如内容为 {"sample":"0413","result":{"force":12.5,"ok":true}} 的 Test_0413.json：

1. 点添加设备；命名为 Results，文件夹路径为 C:\Results\Inbox，读取来源为收件文件夹，要读取的文件为 Test_*.json，文件格式为 JSON。
2. 添加点位 Force，JSON 路径 result.force，Double；添加点位 Pass，JSON 路径 result.ok，Boolean；添加点位 Sample，JSON 路径 sample，String。
3. 添加点位 Source file，读取内容为文件名：它显示这些值来自哪个文件。

每个文件在静止 1 秒且没有程序为写入而打开它之后读取一次，按文件到达的顺序；每个文件都是单独的一个读数，时间戳为文件的时间；每个点位都读过之后，它被移到 C:\Results\Inbox\Processed。不会删除任何内容。用工具：

device_upsert name=Results driver=File fileFolder="C:\Results\Inbox" fileName="Test_*.json" fileMode=Inbox fileFormat=Json
tag_upsert device=Results name=Force address=result.force opcUaType=Double
tag_upsert device=Results name=Pass address=result.ok opcUaType=Boolean
tag_upsert device=Results name=Sample address=sample opcUaType=String
tag_upsert device=Results name="Source file" fileSource=Name

示例：为另一个程序追加一行

另一个程序读取 D:\Records\run.csv，每秒一行，包含时间和压力：

1. 点添加设备；命名为 Run log，文件夹路径为 D:\Records，文件名为 run.csv。
2. 在写入卡片中打开允许写入，标题文本填写 Time;Pressure。
3. 添加点位 Line，Double，访问为只写，写入方式为追加一行，行模板为 {datetime};{value:0.00}。

向 Line 写入 12.5 会追加 2026-10-03 14:05:12;12.50，文件已使用逗号或小数分隔符设为小数逗号 (12,5) 时使用逗号；写入新建的文件会先写入 Time;Pressure。快速连续的写入全部保留，并保持顺序。要每次运行写一个文件，再添加一个点位 File，读取内容为文件名，读写：运行开始时，Logic 写入序列号加 .csv，之后的行就写进那个文件。用工具：

device_upsert name="Run log" driver=File fileFolder="D:\Records" fileName=run.csv fileFormat=Delimited fileWrites=true fileHeaderText="Time;Pressure"
tag_upsert device="Run log" name=Line opcUaType=Double accessType=WriteOnly fileWriteMode=AppendLine fileLineTemplate="{datetime};{value:0.00}"
tag_upsert device="Run log" name=File fileSource=Name accessType=ReadAndWrite

智能体工具

driver_capabilities 在 file 下描述本驱动：简单路径、设备的每个字段、文件夹规则以及只能在该文件夹内操作的限制、文件名的各种形式、两种读取方式、各格式及其地址语法、各信号源及其类型、文本设置、读取与写入的行为、设备发现，以及三个完整示例。device_upsert driver=File 接受 fileFolder、fileName、fileMode（默认的 SingleFile 或 Inbox）、fileFormat（默认的 Delimited、Text、Json 或 Xml）、fileEncoding（Automatic、Utf8 或 Windows1252）、fileSeparator（Automatic、Semicolon、Comma 或 Tab）、fileDecimal（Automatic、Point 或 Comma）、fileHeaderRow（0 到 1000）、fileWrites，以及写入打开时的 fileHeaderText 和 fileLineEnd（Automatic、CrLf 或 Lf）；它返回的设备带有 file，其中的 fileStatus 是运行中的驱动发现的内容：正在使用的文件、它是否存在、读到的编码、分隔符和行尾，以及收件文件夹中等待的文件。tag_upsert 接受 fileSource（Value、WholeFile、Exists、Size、Modified、Name 或 Lines）、fileRow（Last、Number 或 Matching）、fileRowNumber、fileKeyColumn、fileMatchText、fileWriteMode（AppendLine 或 ReplaceFile）和 fileLineTemplate；列或路径就是 address，自由文本的值使用通用驱动的 valueExtraction、valueStart、valueLength、valueSeparator、valueField 和 valuePattern，新点位为只读，除非 opcUaType 另行指定，否则取信号源自身的类型。device_discover driver=File 读取 fileDevice（本驱动一台设备的名称），或者为扫描输入的 fileFolder、fileName、fileMode 和 fileFormat；已配置设备缺少的点位用 tag_upsert 添加。connector_browse 为每台设备返回 fileFolder、fileName、fileMode 和 fileFormat。其他工具见智能体工具。

值得了解的限制

• 不读取 Excel 工作簿：工作簿要等它的程序另存为 CSV 后才能读取。
• 驱动从不删除文件。收件文件夹把读过的文件移到 Processed，唯一会被移除的只有替换失败时的临时文件。
• “读取文件夹中最新的文件”不是一种读取方式：它会丢失同时到达的文件，还可能显示上一个样品的值。每个样品写一个文件的设备，用收件文件夹读取。
• 不会在文件内原地修改某个值（CSV 的一个单元格、另一个程序的 JSON 中的一个成员）：写入只追加一行或替换整个文件，因为两个程序写同一个文件，可能会丢失对方的修改。
• 网络共享用运行工作站的账户的 Windows 权限访问：设备不保存用户名和密码，所以共享必须允许该账户进入（读取；对于会写入的设备或收件文件夹，还要能写入和移动）。
• 驱动从不触碰其文件夹以外的任何内容：指向别处的名称，在输入时和写入时都会被拒绝。
• 每次读取时查看文件：变化在下一次读取时才会看到，而不是另一个程序写入的那一刻。
• 包含换行的 CSV 字段不会被读取，JSON、XML 或整个文件的点位最多读取 4 MiB。