一个库存登记的小工具,在自己电脑上跑了半年,配置就写在 exe 旁边,从没出过事。装到客户那台 Windows 11 上,第一次点「保存设置」就弹异常:System.UnauthorizedAccessException: 对路径 C:\Program Files\CoolDesign\Stock\config.json 的访问被拒绝。远程连过去看,程序确实装在 Program Files,登录的是普通员工账号。代码一行没改,换台机器就废了。
第二个现场更难受。第一版把配置和 SQLite 数据库都放在安装目录,升级时安装包按惯例先清空旧目录,再铺新文件。用户升级完打开程序,操作员名字回到空白,上个月录的两千多条库存记录也没了。售后只能让用户重新录。这不是数据库坏了,是升级流程把数据目录一起当成了程序的一部分。
第三个现场是开发期埋的。第二版给设备表加了一个「备注」列,本地测试一切正常,因为开发机上的库每次都是重建的。老用户升级后一打开就崩,日志里是 SQLite Error 1: 'no such column: Note'.。建表语句明明写了 CREATE TABLE IF NOT EXISTS,可它只保证表存在,不会替旧表补上新列。
三件事看着不一样,根子是同一个:程序和数据放在了同一个位置,又默认数据和代码版本永远匹配。这篇要把数据挪到该去的地方,把写入做成断电不会坏一半,再给数据库记一本版本账。做完会得到一个能保存设置、能建库、能从第一版平滑升到第二版的小程序。
版本说明:按 .NET 8 的 WPF 和 Microsoft.Data.Sqlite 讲。本机用 dotnet-install.ps1 装了 SDK 8.0.427,下面的代码实际编译运行过:迁移前查询报 SQLite Error 1: 'no such column: Note'.,执行加列迁移后查询正常,事务回滚后旧值仍在。包版本以还原结果为准。
三个现场,同一个根源
先看权限那条。Windows 对 C:\Program Files 的访问控制很严格,只有管理员组能写。普通用户启动的 .NET 程序带应用程序清单,默认请求级别是 asInvoker,也就是「用户有多少权限就用多少」,不会自动弹 UAC 提权。于是程序能读自己的文件,唯独写配置时被拒绝。
有人会问:以前不是会把写入偷偷重定向到 VirtualStore 吗。那是 UAC 文件虚拟化,只照顾没有清单的 32 位旧程序;带清单的 .NET 程序不享受这个待遇,写失败就是写失败。所以「在自己机器上能跑」完全不能证明「在客户机器上能跑」——开发账号往往是管理员,异常被环境掩盖了。
第二次丢数据,问题出在安装器的所有权。安装目录归安装器管,升级、修复、卸载都可能整目录替换。只要配置文件或数据库还躺在里面,它就会被当成程序的附属物一起处理。更隐蔽的是路径本身也会变:程序从 Stock.exe 改名为 StockDesk.exe,按 exe 位置拼出来的数据路径就跟着变,旧数据还在,程序却去找新位置了。
第三次崩溃,是版本账没记。数据库里的表结构会随着需求变,字段只加不减是常态,但 CREATE TABLE IF NOT EXISTS 对已存在的表完全不做事。旧库没有新列,新代码却按有新列来查,第一条 SELECT 就报错。要解决它,不能靠每次启动去猜表结构,得有一个明确的版本号,让程序知道「这个库现在处于第几版,下一步该执行哪段升级脚本」。
所以顺序是这样的:先把数据路径固定到一个安装器碰不到的地方;再保证写配置时不会留下半截文件;最后用 SQLite 自带的版本号管理表结构。三件事各自独立,但缺一件,另外两件的效果都会打折。
安装目录不是你的地盘
Windows 桌面程序的数据一般有三个候选位置,选哪个取决于数据是什么,而不是取决于哪个写着顺手。
Environment.GetFolderPath(SpecialFolder.LocalApplicationData) 取,不写死盘符。反过来,几个常见写法都不该用来定位数据:AppDomain.CurrentDomain.BaseDirectory 把数据绑在安装目录上;Environment.CurrentDirectory 会随文件对话框改变;写死 D:\ 也不行,客户机器未必有 D 盘,网络盘还可能断开。
便携版:数据跟着 exe
适合绿色软件、现场工具、U 盘巡检。启动时先探测 exe 目录是否可写,能写就用,不能写就退回 %LOCALAPPDATA%,并在界面上说明数据在哪。代价是要处理两种位置并存的情况,用户拷走 exe 时也可能只拷了一半。
安装版:数据固定到用户目录
适合正式交付。程序目录只读,数据放 %LOCALAPPDATA%,安装器升级时只替换程序文件。代价是「同一台机器多个 Windows 用户各有一份数据」,售后排查前要先确认登录的是哪个账号。
%LOCALAPPDATA% 被 OneDrive 等同步工具接管,SQLite 的 -wal、-shm 会被单独同步,数据库很容易损坏。看实际路径是否在同步目录下,是的话排除同步或换本地目录——把数据库直接放 OneDrive 是常见的「偶尔打不开」来源。场景走查:从空目录到能保存设置
需求:库存台账窗口能填操作员名字,保存后下次启动还记得;再准备一个 SQLite 库,能写入两条设备记录。先建项目并装包:
dotnet new wpf -n StockDesk -f net8.0
cd StockDesk
dotnet add package Microsoft.Data.Sqlite
dotnet run
项目根目录下新增一个 AppPaths.cs。所有数据路径都从这里出,别在窗口里散着拼:
using System;
using System.IO;
namespace StockDesk;
public static class AppPaths
{
public static string Root { get; } = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"CoolDesign",
"Stock");
public static string SettingsFile => Path.Combine(Root, "settings.json");
public static string DatabaseFile => Path.Combine(Root, "stock.db");
public static string BackupDir => Path.Combine(Root, "backup");
public static void Ensure()
{
Directory.CreateDirectory(Root);
Directory.CreateDirectory(BackupDir);
}
}
窗口只有输入框、两个按钮和两行文字。把 MainWindow.xaml 换成:
<Window x:Class="StockDesk.MainWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
Title="库存台账" Height="360" Width="640">
<StackPanel Margin="16">
<TextBlock Text="操作员"/>
<TextBox x:Name="OperatorBox" Margin="0,4,0,12"/>
<StackPanel Orientation="Horizontal">
<Button Content="保存设置" Click="SaveSettings_Click" Padding="12,6"/>
<Button Content="写入两条测试数据" Click="Seed_Click"
Padding="12,6" Margin="8,0,0,0"/>
</StackPanel>
<TextBlock x:Name="StatusText" Margin="0,16,0,0" TextWrapping="Wrap"/>
<TextBlock x:Name="PathText" Margin="0,8,0,0"
Foreground="#667085" TextWrapping="Wrap"/>
</StackPanel>
</Window>
窗口启动时先确保目录存在,再执行迁移,最后读出配置。注意顺序:目录不存在时打开数据库会直接报错,所以 Ensure 必须排在前面。
using System;
using System.Windows;
using Microsoft.Data.Sqlite;
namespace StockDesk;
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
AppPaths.Ensure();
Migrator.Run();
var settings = SettingsStore.Load();
OperatorBox.Text = settings.Operator;
PathText.Text = "数据目录:" + AppPaths.Root;
}
private void SaveSettings_Click(object sender, RoutedEventArgs e)
{
var settings = SettingsStore.Load();
settings.Operator = OperatorBox.Text.Trim();
SettingsStore.Save(settings);
StatusText.Text = "设置已保存";
}
private void Seed_Click(object sender, RoutedEventArgs e)
{
try
{
using var conn = Database.Open();
using var tx = conn.BeginTransaction();
using var cmd = conn.CreateCommand();
cmd.Transaction = tx;
cmd.CommandText = @"
INSERT INTO Device (Code, Name, Quantity, UpdatedAt)
VALUES ($code, $name, $qty, $at);";
var now = DateTime.UtcNow.ToString("O");
foreach (var (code, name, qty) in new[]
{
("PUMP-01", "一号泵", 3),
("VALVE-07", "七号阀", 5)
})
{
cmd.Parameters.Clear();
cmd.Parameters.AddWithValue("$code", code);
cmd.Parameters.AddWithValue("$name", name);
cmd.Parameters.AddWithValue("$qty", qty);
cmd.Parameters.AddWithValue("$at", now);
cmd.ExecuteNonQuery();
}
tx.Commit();
StatusText.Text = "已写入 2 条设备记录";
}
catch (SqliteException ex)
{
StatusText.Text = "写入失败:" + ex.Message;
}
}
}
运行 dotnet run,预期看到一个窗口,底部显示类似 C:\Users\yourname\AppData\Local\CoolDesign\Stock 的路径。点「保存设置」后,目录里多出 settings.json;关闭程序再打开,操作员名字还在。第一次启动还会出现 stock.db,以及 stock.db-wal、stock.db-shm 两个副文件,这是 WAL 的正常产物,别手动删。
点「写入两条测试数据」,状态显示已写入 2 条。再点一次会撞上 Code 的唯一约束,状态栏显示写入失败,两条都不会进库——这正是事务在起作用。
JSON 配置:读的时候容错,写的时候原子
配置量小、结构简单时,JSON 最省事:人可读,现场能直接看,System.Text.Json 又不用装包。要花心思的是两个边界:文件不存在时不能崩,文件写坏时不能连累程序启动。
using System;
using System.IO;
using System.Text.Json;
namespace StockDesk;
public sealed class AppSettings
{
public string Operator { get; set; } = "";
public string Theme { get; set; } = "light";
public int PageSize { get; set; } = 50;
}
public static class SettingsStore
{
private static readonly JsonSerializerOptions Options = new()
{
WriteIndented = true,
PropertyNameCaseInsensitive = true
};
public static AppSettings Load()
{
try
{
if (!File.Exists(AppPaths.SettingsFile))
return new AppSettings();
var json = File.ReadAllText(AppPaths.SettingsFile);
return JsonSerializer.Deserialize<AppSettings>(json, Options)
?? new AppSettings();
}
catch (JsonException)
{
// 配置坏了不该让程序起不来:留证,然后回到默认值
File.Move(AppPaths.SettingsFile,
AppPaths.SettingsFile + ".bad",
overwrite: true);
return new AppSettings();
}
}
public static void Save(AppSettings settings)
{
AppPaths.Ensure();
var tmp = AppPaths.SettingsFile + ".tmp";
using (var stream = new FileStream(tmp, FileMode.Create,
FileAccess.Write, FileShare.None))
{
JsonSerializer.Serialize(stream, settings, Options);
stream.Flush(flushToDisk: true);
}
File.Move(tmp, AppPaths.SettingsFile, overwrite: true);
}
}
写法的核心是「先写临时文件,成功后再替换目标文件」。直接打开目标文件边序列化边写,写到一半断电或进程被杀,留下的就是半截 JSON,下次启动解析失败。用临时文件,最坏只损失这次修改,旧配置还在。
Flush(flushToDisk: true) 让数据真正落到磁盘,而不是停在系统缓存里,代价是多一次磁盘同步,对低频的配置保存完全值得。替换用 File.Move 的覆盖模式即可;想同时保留上一版,换成 File.Replace,它会先把旧文件挪到备份路径。
读的时候只捕获 JsonException,不要顺手 catch (Exception) 一把梭。文件被占用、磁盘掉线这类问题应该冒出来;只有「内容不是合法 JSON」才适合回默认值。坏文件改名成 .bad 而不是删掉,现场还能拿回来分析。
ProtectedData)按当前用户加密后再落盘,并想清楚换机器、换账号后还能不能用。配置只存偏好,多实例同时改会互相覆盖。SQLite:一个文件,一个连接串
数据量到几千条、需要按条件查询、还要保证批量写入不写一半,就该上 SQLite 了。它不用装服务,整个库就是一个文件。Microsoft.Data.Sqlite 是官方维护的 ADO.NET 实现,比老牌的 System.Data.SQLite 更适合新项目。
连接串用 SqliteConnectionStringBuilder 拼,路径里有空格或分号也不会出错。两个超时容易混:DefaultTimeout 是命令执行超时,单位秒;busy_timeout 是遇锁等待,单位毫秒。两个都要设。
using Microsoft.Data.Sqlite;
namespace StockDesk;
public static class Database
{
public static string ConnectionString { get; } =
new SqliteConnectionStringBuilder
{
DataSource = AppPaths.DatabaseFile,
Mode = SqliteOpenMode.ReadWriteCreate,
Pooling = true,
DefaultTimeout = 5
}.ToString();
public static SqliteConnection Open()
{
var conn = new SqliteConnection(ConnectionString);
conn.Open();
using var cmd = conn.CreateCommand();
cmd.CommandText =
"PRAGMA journal_mode=WAL;" +
"PRAGMA foreign_keys=ON;" +
"PRAGMA busy_timeout=5000;";
cmd.ExecuteNonQuery();
return conn;
}
}
WAL 是 SQLite 的一种日志模式:写入先落到 -wal 文件,读操作不用等写操作结束。对桌面程序很直接——后台正在批量导入时,界面上的列表仍然能读。代价是多了两个副文件,而且数据库不能放在网络共享上,因为 WAL 依赖同机的共享内存,SMB 上的锁语义不可靠。
连接的使用方式是「短连接 + 连接池」:每次操作 Open,using 结束就关闭,底层会归还到池里,不会真的反复建文件句柄。不要在整个程序生命周期里静态持有一个连接,也不要跨线程共用一个连接,SQLite 的连接不是线程安全的。批量写入一定要包事务,否则每条 INSERT 都是一次独立提交,慢不说,中途失败还会留下写了一半的数据。
$code 是 Microsoft.Data.Sqlite 的写法,和 SQL Server 的 @code 不同,混用会找不到参数。建表只做一次,放在迁移流程里。时间字段统一存 UTC 的 ISO 8601 字符串(DateTime.UtcNow.ToString("O")),显示时再转本地时区,排序和比较才稳定。
改表结构:用 user_version 记账
SQLite 的文件头里有一个整数 user_version,默认是 0,程序可以随便用。拿它记「当前库的结构版本」正合适:新库是 0,跑完第一段建表脚本写成 1,跑完加列脚本写成 2。启动时读一次版本号,就知道该从哪一步开始补。
迁移脚本必须「从旧版本往前走」,不能假设从空库开始。第一版建表,第二版加列,第三版也许建索引。旧脚本发布后不要再改,用户手里的库可能已经跑过它;要修就加新版本号,再写一段迁移。
using System;
using System.IO;
using System.Linq;
using Microsoft.Data.Sqlite;
namespace StockDesk;
public static class Migrator
{
private const int TargetVersion = 2;
public static void Run()
{
AppPaths.Ensure();
var isNew = !File.Exists(AppPaths.DatabaseFile);
using var conn = Database.Open();
var version = Convert.ToInt32(Scalar(conn, "PRAGMA user_version;"));
if (version == TargetVersion) return;
if (version > TargetVersion)
throw new InvalidOperationException(
$"数据库版本 {version} 高于程序支持的 {TargetVersion},请升级程序。");
if (!isNew) Backup(conn);
using var tx = conn.BeginTransaction();
if (version < 1)
{
Execute(conn, tx, @"
CREATE TABLE Device (
Id INTEGER PRIMARY KEY AUTOINCREMENT,
Code TEXT NOT NULL UNIQUE,
Name TEXT NOT NULL,
Quantity INTEGER NOT NULL DEFAULT 0,
UpdatedAt TEXT NOT NULL
);");
}
if (version < 2)
{
Execute(conn, tx,
"ALTER TABLE Device ADD COLUMN Note TEXT NOT NULL DEFAULT '';");
}
Execute(conn, tx, $"PRAGMA user_version={TargetVersion};");
tx.Commit();
}
private static object? Scalar(SqliteConnection conn, string sql)
{
using var cmd = conn.CreateCommand();
cmd.CommandText = sql;
return cmd.ExecuteScalar();
}
private static void Execute(SqliteConnection conn, SqliteTransaction tx, string sql)
{
using var cmd = conn.CreateCommand();
cmd.Transaction = tx;
cmd.CommandText = sql;
cmd.ExecuteNonQuery();
}
private static void Backup(SqliteConnection source)
{
var file = Path.Combine(AppPaths.BackupDir,
$"stock-{DateTime.Now:yyyyMMdd-HHmmss}.db");
using var target = new SqliteConnection($"Data Source={file}");
target.Open();
source.BackupDatabase(target);
foreach (var old in Directory.GetFiles(AppPaths.BackupDir, "stock-*.db")
.OrderByDescending(f => f).Skip(5))
{
File.Delete(old);
}
}
}
备份不能直接复制 stock.db:WAL 模式下还有一部分数据在 -wal 文件里,只拷主文件会得到旧内容甚至不完整的状态。用 BackupDatabase 走 SQLite 自己的页复制接口,拿到一致的快照。备份放在迁移之前,且只在真要升级时做。
版本高于程序支持时,直接抛异常并提示升级程序,不要「试试看能不能打开」——旧代码不认识新列,硬改只会把数据写坏。整个迁移包在一个事务里,user_version 也在同一事务里更新;中途失败就全部回滚,下次从旧版本号重跑。
两个人同时写库:busy 与重试
桌面程序也会并发:主窗口在保存,后台定时任务在同步,用户又开了第二个实例。WAL 允许一个写者和多个读者同时工作,但写者只能有一个。第二个写请求不会排队等,默认直接拿到 SQLITE_BUSY,翻译成异常就是「database is locked」。
第一道防线是连接上的 busy_timeout,前面设了 5000 毫秒,SQLite 会在锁释放前自己重试。第二道是在业务层做有限次退避重试,只对 BUSY、LOCKED 重试,别的错误照常抛。重试要放在整个事务外层,不能只重试事务里的某一条语句,否则会重复插入。
using System;
using System.Threading;
using Microsoft.Data.Sqlite;
public static class DbRetry
{
public static T Run<T>(Func<T> action, int attempts = 5)
{
for (var i = 1; ; i++)
{
try
{
return action();
}
catch (SqliteException ex) when (
(ex.SqliteErrorCode == 5 || ex.SqliteErrorCode == 6)
&& i < attempts)
{
Thread.Sleep(100 * i);
}
}
}
}
这段代码只该在后台线程或异步任务里用,别在界面线程上 Thread.Sleep,否则锁没等到,窗口先白了。更根本的做法是缩短写事务:把数据准备好再开事务,事务里只做插入,不要在里面弹窗、读文件、等网络。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
保存配置报 UnauthorizedAccessException | 数据写在 exe 目录或 Program Files,普通用户没有写权限 | 打印实际写入路径,确认它是否落在安装目录;再看进程是否以普通用户运行 |
| 升级后配置和记录全没了 | 安装器清理旧目录,数据被当成程序文件一起替换 | 查安装包里是否包含数据文件,确认数据根目录是否在 %LOCALAPPDATA% |
| 配置文件变成 0 字节,启动解析失败 | 直接覆盖写目标文件,写到一半进程退出或断电 | 看目录里有没有 .tmp,确认保存逻辑是否先写临时文件再替换 |
老用户打开就崩,报 no such column | 只执行了 CREATE TABLE IF NOT EXISTS,没有迁移旧表 | 读 PRAGMA user_version 和 PRAGMA table_info(Device),对比代码期望的列 |
报 database is locked | 有长事务占着写锁,或第二个实例、后台任务同时写 | 看谁持有写事务、busy_timeout 是否设置、库是否放在网络盘 |
| 批量导入只成功了一半 | 每条语句独立提交,没有包事务 | 检查循环里是否在 BeginTransaction 之内,异常时有没有回滚 |
| 数据库偶尔打不开,重试后又好了 | 库被放进了 OneDrive 等同步目录,WAL 副文件被单独同步 | 看数据路径是否在同步盘,把库移出同步范围并排除整个目录 |
边界与代价
第一,这套方案默认「一台机器一个用户一份数据」。换 Windows 账号登录看到的是另一个人的库;域账号漫游时,%LOCALAPPDATA% 也不跟着走。售后和文档要写清楚,真需要多用户共享就得上服务端数据库。
第二,SQLite 的写入并发有天花板。单写者模型在桌面场景足够,但不适合几十个客户端同时写。把库放共享盘、用同步软件实时同步,都是看起来能跑、随时会坏的做法;遇到多机共享数据的需求,越早换架构越省事。
第三,迁移是单向的。升级脚本只保证旧库变新库,不保证新库变回旧库。程序降级时正确做法是提示升级,而不是让旧代码硬读新库。迁移前备份能救急,但不是版本兼容策略。
第四,原子写入保证的是「不会留下半截文件」,不是「不会丢最后一次修改」。磁盘满、权限变化、文件被占用,保存仍会失败,界面必须告诉用户,不能点完就显示「已保存」。配置回默认值也要在状态栏提示「配置文件损坏,已恢复默认」。
第五,JSON 不适合当数据表用。有人把几百条业务记录塞进配置文件,不建库,结果查询、分页、并发修改全要自己实现。配置存偏好,业务数据进 SQLite,边界清楚。
小结与练习
把数据从安装目录挪到 %LOCALAPPDATA%,是能不能顺利交付的分水岭;配置用临时文件加替换,数据库用连接串、WAL、事务和超时,表结构用 user_version 记版本,迁移前做一致性备份。这四件事做完,「装到客户机器上就报错」「升级丢数据」「老用户打不开」基本就堵住了。
当天可以自己验证的练习:
- 把程序拷到
C:\Program Files下运行,点保存设置,复现访问被拒绝;再把数据根目录改回%LOCALAPPDATA%,确认恢复正常。 - 手工把
settings.json改成一段非法 JSON,重启程序,确认它回到默认值并留下.bad文件。 - 同时开两个程序实例,各自改一次操作员名字再保存,观察最后留下的是哪一个,理解「最后写入者获胜」。
- 复制一份
stock.db做实验,用 SQLite 命令行把user_version改成 0 再启动,观察迁移脚本因为表已存在而失败——这能说明迁移必须按版本分支,不能假设从零开始。 - 在「写入两条测试数据」的事务里故意插入一条重复的
Code,确认两条都不进库,再去掉事务对比结果。
下一篇讲后台任务与界面线程。数据的位置和写法定了,接下来是「什么时候写」。导入两万行、保存大文件、建库迁移都可能跑几百毫秒到几秒,如果这些都放在按钮点击的事件处理里同步执行,窗口就会白屏、点不动。下一篇把耗时的活挪到后台,再讲清楚结果怎么安全地回到界面。