简介System.Data.SQLite 是 SQLite 在 .NET 平台上的增强版本其优势是内置 ADO.NET 2.0 引擎让 .NET 开发者无需完整 .NET 框架即可直接使用 SQLite部署时仅需一个动态库文件。这份 PDF 资料围绕该组件展开先介绍 SQLite 轻量级单文件数据库的基本特征包括对 SQL92 标准的兼容、灵活的类型处理、跨平台支持再说明其在 ADO.NET 集成、自包含部署、VS2005/VS2008 及实体框架兼容上的增强并演示在 Visual Studio 中添加 SQLite 数据连接、像操作 SQL Server 一样设计数据库表。资料还提供了针对 System.Data.SQLite 的通用数据库操作类覆盖建库、返回数据表或数据阅读器、增删改返回影响行数、统计查询、获取所有表名等场景同时强调使用参数化 SQL 语句避免注入攻击。在仅安装 Office 而无 Access 的受限环境中将 Excel 导入 SQLite 后用 SQL 函数与连接查询分析效率远高于在内存 DataTable 中手动处理。资源为 1 个 PDF 文件约 300KB已有 209 人学习下载适合需要在轻量级或独立部署场景下进行 .NET 数据处理的开发人员快速了解与上手。1. System.Data.SQLite 到底解决什么问题桌面端本地存储的选型困境做客户端开发的人早晚会撞上同一个问题程序要存数据但用户机器上没有装数据库服务也不可能为了一个单机工具要求他去配一个 SQL Server 实例。早期方案是存文件、写 XML数据量一上来就卡而且并发写几乎不可控。System.Data.SQLite 就是在这个场景里被反复选中的答案——它是一个让 .NET 程序直接操作 SQLite 数据库文件的 ADO.NET 提供程序把你的本地存储变成一张张真正的关系表不需要安装任何服务程序里引用一个程序集就能跑。它能解决的核心痛点有三个一是单机数据从文件读写升级为 SQL 查询二是随应用分发成本极低几 MB 的 DLL 搞定三是 SQL 语法和事务机制让数据安全性和开发效率同时在线。适合谁用WPF/WinForms 桌面工具、本地缓存层、内嵌式数据服务、测试环境的临时库这些场景基本闭眼选它。2. 把 System.Data.SQLite 接入项目的三种姿势包、DLL 与平台目标的选择2.1 NuGet 包与程序集的对应关系别再拿错包了System.Data.SQLite 在发行体系里不是简单的一个 DLL而是一族包常见做法是根据项目类型去选主包。官方发布的核心是System.Data.SQLite.Core它包含托管代码和对应平台的原生库安装后会自动按项目的目标平台x86/x64拷贝对应的SQLite.Interop.dll。而完整的System.Data.SQLite包则额外带上了设计时组件和 Entity Framework 6 的支持文件适合 WinForms 项目里用可视化设计器拖数据源的场景。还有一种少见但有用的组合是只引用System.Data.SQLite.Linq它提供 LINQ to SQLite 的能力不过它本身依赖 Core 包单独引用没有意义。这里最容易翻车的点是包版本与 .NET 版本的匹配。System.Data.SQLite 官方发布周期里很早就兼容 .NET Framework 2.0 往上所有版本也长期提供 .NET Core/.NET 5 的构建产物。但在新式 SDK 风格的工程里不加约束地安装最新版 Core 包后常常出现运行时找不到原生 SQLite.Interop.dll 的情况原因多数是项目没有显式声明RuntimeIdentifier或者平台目标跑到了 AnyCPU 但引用库里没有对应的互操作文件。我在项目里默认的接法是PackageReference IncludeSystem.Data.SQLite.Core Version1.0.118 / RuntimeIdentifierwin-x64/RuntimeIdentifier逻辑说明第一行把 Core 包固定到 1.0.118 这个长期维护的版本线不追求追新第二行把运行时标识显式锁定为 win-x64这样还原包时 NuGet 会把对应平台的 SQLite.Interop.dll 放进输出目录。如果工程是多平台的就不要写死 RuntimeIdentifier改为在每个发布配置里分别指定。设置的依据是只要目标机器是 64 位 Windows这套组合能在 95% 以上的环境里直接跑通不用再去手动复制 DLL。2.2 连接字符串与数据库文件初始化从“打开就报错”到稳定连接连接字符串是 System.Data.SQLite 里被低估的复杂度来源。最简单的写法是Data Sourceapp.db但它默认的很多行为对生产不友好没有连接超时、没有 busy 超时、journal 模式是默认的 delete 模式。我一般起手会用一个更完整的模板var connString new SQLiteConnectionStringBuilder { DataSource Path.Combine(AppContext.BaseDirectory, appdata.db), Version 3, JournalMode SQLiteJournalModeEnum.Wal, BusyTimeout 5000, DefaultTimeout 10, Pooling true }.ToString();逻辑说明Version 3必须保留它对应 SQLite 3 的数据库格式省略时程序会尝试按旧版本规则推断虽然也能工作但在新库文件上会有兼容警告。JournalMode Wal让并发读不再阻塞写桌面单进程场景收益不大但为后续做多线程访问留了路。BusyTimeout的单位是毫秒它控制当数据库文件被别的事务持锁时当前连接最多等待多久5000 是一个保守值能规避大量“database is locked”的偶发报错。Pooling true启用连接池桌面应用里高频短连接省掉重复初始化开销。文件初始化有个容易忽略的问题SQLiteConnection 对象如果不调用Open()是既不会创建文件也不会创建 schema 的。很多人写完new SQLiteConnection(connString)就直接执行 SQL得到一个“no such table”错误就是因为连接从未打开。正确的初始化顺序是先 Open再执行建表命令然后关闭连接让文件真正落在磁盘上。2.3 托管代码与原生互操作x86/x64 目录下的那个 Interop DLLSystem.Data.SQLite 的结构是典型的托管壳加原生核C# 程序集负责实现 ADO.NET 接口、SQL 解析、类型映射真正的 SQLite 引擎跑在一个独立的原生 DLL 里。这个设计带来一个现实问题不同平台必须加载各自的互操作 DLL否则启动时直接抛DllNotFoundException或BadImageFormatException。常见做法是在项目的运行目录下保留x86和x64两个子目录NuGet 包安装时已经把这套目录带进来了。我见过最多的问题是把项目设为 AnyCPU然后复制文件到目标机器时报“无法加载 DLL”再换 x64 又报错。核心原因在于 AnyCPU 在 .NET Framework 下默认按 x86 运行而复制集成了 x64 的互操作 DLL。排查时不要盯着托管代码看先确认实际运行进程的平台位数再检查对应位数的 Interop DLL 是否在输出目录。3. 用 System.Data.SQLite 跑通第一个本地库从建表到事务的完整链路3.1 最小可运行的建表与写入代码GetType 为 SQLite 时的完整范式一个完整的 System.Data.SQLite 使用流程应该包括打开连接、创建表、参数化插入、查询、关闭。很多人上来就用拼接字符串拼 SQL这在 SQLite 下不是不能跑但一旦字段值里出现单引号或中文引号就是事故。下面这段是标准的最小代码using (var conn new SQLiteConnection(connString)) { conn.Open(); using (var cmd conn.CreateCommand()) { cmd.CommandText CREATE TABLE IF NOT EXISTS device_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, device_name TEXT NOT NULL, log_level INTEGER NOT NULL, message TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); cmd.ExecuteNonQuery(); } using (var insert conn.CreateCommand()) { insert.CommandText INSERT INTO device_log (device_name, log_level, message) VALUES (name, level, msg); insert.Parameters.AddWithValue(name, device-a-001); insert.Parameters.AddWithValue(level, 2); insert.Parameters.AddWithValue(msg, temperature sensor over threshold); insert.ExecuteNonQuery(); } }逻辑说明连接对象用 using 包裹释放时即关闭连接这是避免文件句柄残留的基础。CREATE TABLE IF NOT EXISTS让初始化逻辑天然幂等重复执行不会报错。参数化语句用name这类占位符接参数能杜绝大部分 SQL 注入和转义问题。值得注意的坑AddWithValue在小数据量下很方便但它会强制按传入值的 CLR 类型推断 SQLite 类型——如果传入的int被当作long写入日后做类型比对时会有微妙差别。更稳的做法是显式指定DbType。另外AUTOINCREMENT在 SQLite 里不是必需的只要声明INTEGER PRIMARY KEY内部自增 rowid 就已经生效加不加 AUTOINCREMENT 只影响删除最大行后是否复用旧 id桌面端日志表一般不加更合适。3.2 批量写入性能一万行数据事务拆分的边界在哪单条插入在 System.Data.SQLite 下每秒大约只能执行几百到一千次瓶颈不是 SQLite 本身而是每次插入都触发一次磁盘同步。批量写入的标准做法是用显式事务把多次插入包在一起让所有写操作在一个提交点落盘。using (var conn new SQLiteConnection(connString)) { conn.Open(); using (var tx conn.BeginTransaction()) using (var cmd conn.CreateCommand()) { cmd.Transaction tx; cmd.CommandText INSERT INTO device_log (device_name, log_level, message) VALUES (name, level, msg); for (int i 0; i 10000; i) { cmd.Parameters.Clear(); cmd.Parameters.AddWithValue(name, $device-{i % 50}); cmd.Parameters.AddWithValue(level, i % 5); cmd.Parameters.AddWithValue(msg, $batch insert #{i}); cmd.ExecuteNonQuery(); } tx.Commit(); } }逻辑说明关键在cmd.Transaction tx如果不把这个关联写上ADO.NET 会在连接上自动开启隐式事务每一句 insert 都独立提交性能直接掉回单条模式。把参数 Clear 掉再重新 Add是为了避免参数集合膨胀实测比循环外建参数、循环里只改 Value 的方式要干净。事务大小需要控制。SQLite 的一个事务写入太多行会把整个数据库变更页缓存在内存里提交时一次性 flush最直观的现象是内存飙升、提交瞬间卡顿。我的经验值是控制在 5000 到 20000 行之间超过十万行分多个事务提交。每提交一次SQLite 会做一次 checkpoint 式的落盘也能给后续长时间写入提供稳定的吞吐。3.3 查询与 DataReader为什么不用 DataTable 兜底查询结果的消费方式直接影响内存占用。很多人习惯用SQLiteDataAdapter把结果塞进DataTable这在几十行数据时无所谓但查询上百万行的调试日志时内存直接被打满。更合适的做法是走 DataReader 流式读取边读边消费。using (var conn new SQLiteConnection(connString)) using (var cmd conn.CreateCommand()) { conn.Open(); cmd.CommandText SELECT device_name, message FROM device_log WHERE log_level level ORDER BY id DESC LIMIT 1000; cmd.Parameters.AddWithValue(level, 2); using (var reader cmd.ExecuteReader()) { while (reader.Read()) { var deviceName reader.GetString(0); var message reader.GetString(1); // 逐行消费不缓存 } } }逻辑说明ExecuteReader返回的是一个前向只读的流式结果集Read()一次只往内存加载一行。配合LIMIT 1000这样的分页约束内存占用稳定在一个极小值。这里有另一层考虑System.Data.SQLite 在读取时若同时有写操作WAL 模式下读与写不冲突但在 delete journal 模式下可能锁住整个文件所以查询里排序字段尽量走索引避免扫表时间过长导致写端超时。4. 并发写入、加密与备份System.Data.SQLite 在生产环境里的三个边界问题4.1 多线程读写WAL 模式与 busy_timeout 共同兜底桌面应用里多线程访问同一个 SQLite 库文件的场景越来越多后台线程写日志UI 线程查状态。同一进程内多个连接读同一个库文件在默认 rollback journal 模式下任何写操作都会拿独占锁读操作稍不注意就来一个SQLITE_BUSY。解决办法有两步连接字符串里开 WAL 模式同时把所有连接的 BusyTimeout 设成一个非零值。// 在连接已打开的情况下单独执行 using (var cmd conn.CreateCommand()) { cmd.CommandText PRAGMA journal_modeWAL;; cmd.ExecuteNonQuery(); }逻辑说明WAL 模式把写入内容先追加到一个独立的-wal文件里读操作照常读主库文件写操作之间才互斥读写不再互相阻塞。这个 PRAGMA 是持久的一旦设置库文件后续所有连接都会保持 WAL不需要每次打开都重复执行。但注意WAL 模式在低配机械硬盘或网络磁盘上表现反而可能劣化因为它对文件系统的一致性保证要求更高。如果目标平台是某些老旧嵌入式设备建议回退到默认模式。配合BusyTimeout两种模式的差异体会明显。在 delete journal 模式下遇到锁的写操作会立刻回SQLITE_BUSY异常而设了 BusyTimeout 后连接会等待持锁方释放。这个等待不是无限等待超过时间依然报错——这个“报错”意味着你的多线程写频率超过了 SQLite 单库的串行化能力此时该考虑加写锁队列或分库。4.2 加密能力System.Data.SQLite 自带加密与 SQLCipher 的边界System.Data.SQLite 官方发行版里包含一套加密扩展连接字符串加Password...就能给数据库文件加密。这个功能用的是 SQLite 的加密接口实现的加密后的文件是一堆密文直接拖到十六进制编辑器里看不到表结构。var connString new SQLiteConnectionStringBuilder { DataSource secret.db, Password s3cret!key, Version 3 }.ToString();逻辑说明加密在文件第一次创建时生效之后每次打开都必须带 Password否则抛出file is encrypted or is not a database异常。加密的强度对绝大多数桌面工具场景是够用的但要注意它的加密算法依赖 SQLite 官方代码分支和 SQLCipher 并不互通。如果项目预期要从这套库无缝切换到 SQLCipher 生态代价是全部数据要导出重灌。另一个隐形成本是加密后的写入性能下降实测大约有 20%30% 的吞吐折损磁盘操作频繁的场景要提前做压测。这里的常见误用是把密码硬编码在代码里一旦二进制被反编译加密就和没有一样。至少从配置文件读再进一步用系统凭据管理器。4.3 备份与恢复SQLite 在线备份 API 的正确姿势对 SQLite 做备份不能直接复制 .db 文件特别是在 WAL 模式下-wal文件里可能还存着未 checkpoint 的数据单纯复制主库文件会丢最近提交的记录。System.Data.SQLite 封装了 SQLite 的在线备份接口代码层面可以这样用using (var source new SQLiteConnection(backupSource)) using (var dest new SQLiteConnection(backupDest)) { source.Open(); dest.Open(); source.BackupDatabase(dest, main, main, 4096, null, 200); }逻辑说明BackupDatabase是连接对象的扩展方法它按页复制源库到目标库期间源库允许继续读写目标库在备份完成后是一个一致性的快照。第四个参数 4096 是每批复制的页数直接影响备份速度与内存占用最后一个参数是每批之间的暂停毫秒数200 毫秒是一个偏保守的节流值避免备份过程抢占业务 IO。注意目标库文件如果已存在且包含数据备份操作会覆盖它执行前要确认目标文件可以被清空。备份完成后记得对目标库跑一次PRAGMA integrity_check这是确认备份有效的最低成本手段。5. System.Data.SQLite 常见问题排查五个真实踩坑记录5.1 问题一Unable to load DLL SQLite.Interop.dll——平台位数对不上现象程序部署到目标机器后启动即崩异常信息是DllNotFoundException。原因开发机是 x64但发布时打了 x86或者反过来NuGet 包在还原时只带入了当前 RuntimeIdentifier 的互操作 DLL。解决先在任务管理器里确认进程位数再检查输出目录下x86/x64子目录是否存在对应文件。规范操作是把项目的平台目标固定为x64同时关闭 AnyCPU 下的“首选 32 位”开关。还有一个隐蔽情况在 IIS 或 Windows 服务里宿主进程是 64 位但站点应用池的位数为 32 位这种只看应用层配置看不出来要看宿主进程的位数。5.2 问题二中文乱码——TEXT 类型与 UTF-8 的隐性约定现象插入的中文正常但某些查询返回的字符串变成???或乱码。原因SQLite 存储 TEXT 时按 UTF-8 编码System.Data.SQLite 在写入时会按连接字符串或列类型做编码转换但如果你在 C# 侧拼了 SQL 绕过参数化并且连接字符串里没指明编码字符串可能走了系统默认的 ANSI 编码写入。解决所有文本写入都走参数化确保 Clr 侧类型是 string用一个最小复现脚本验证SELECT与INSERT的往返一致性。若与旧库文件交互优先排查写入端而非读取端因为读取侧在做 UTF-8 到 UTF-16 的转换时基本不会出问题。5.3 问题三database is locked 频繁出现——事务未提交而是未关闭现象程序多跑一会儿就开始随机抛SQLiteException: database is locked重启程序后恢复正常一段时间。原因前面某个事务没有 Commit 也没 Rollback连接对象被 Dispose 时事务被回滚但锁在回滚前一直没释放若连接池启用连接归还池后锁紧跟着被连接池复用下一个操作直接撞到未完成的锁。解决所有写操作包裹在 using 块里事务块内保证 Commit 或 Rollback 一定执行排查时打开数据库文件的独占进程列表确认哪些进程还攥着句柄。救治手段是 PRAGMA busy_timeout但根治必须规范事务生命周期。5.4 问题四TransactionScope 与 BeginTransaction 冲突——事务提升的隐性开销现象代码里用了TransactionScope又在其中调用BeginTransaction()偶发报错“该操作对事务状态无效”。原因TransactionScope会尝试把连接登记到分布式事务里而 System.Data.SQLite 的本地事务和它不是一个管理上下文两者叠加时会造成事务状态机错乱。解决二选一。SQLite 单机场景用不到分布式事务直接放弃 TransactionScope全程用BeginTransaction如果业务代码为了可替换性必须保留 TransactionScope那就不要在方法栈里再开本地事务。日常建议凡是项目里确定使用 System.Data.SQLite 的统一要求写事务时走连接对象的本地事务接口。5.5 问题五DATETIME 读出来变了样——存储格式与读取类型不匹配现象用DATETIME列存DateTime.Now读回来却变成字符串且格式不对排序也乱。原因System.Data.SQLite 没有原生的日期时间类型它把 DateTime 序列化成了 ISO8601 文本但你建表时如果用了DATETIME而插入时传入的是stringSQLite 直接把字符串原样存入读出来自然是字符串。解决参数化写入时统一用DateTime类型的 .NET 值让提供程序按内部规则做序列化查询侧可以用DateTime.Parse兜底但更干净的是读写都保持同一类型的参数。涉及比较与排序时一定统一为 ISO8601 格式形如2025-04-11 10:30:00不要存2025/4/11 10:30这类变体否则ORDER BY的语义会出问题。6. 把 System.Data.SQLite 用得更顺手自定义函数、连接池调优与验证清单System.Data.SQLite 的优势之一是能在托管侧注册自定义 SQL 函数把业务计算下沉到查询层。一个典型案例是哈希值比对数据表里存了文件哈希要按条件筛选出与目标值近似的记录在 SQL 里没法直接写就可以注册一个函数。SQLiteFunction.RegisterFunction(typeof(MyUpperFunction)); [SQLiteFunction(Name myupper, Arguments 1, FuncType FunctionType.Scalar)] public class MyUpperFunction : SQLiteFunction { public override object Invoke(object[] args) { return args[0]?.ToString().ToUpperInvariant(); } }逻辑说明RegisterFunction在程序启动时调用一次即可注册后 SQL 里就能直接SELECT myupper(device_name) FROM device_log。这个机制对纯查询逻辑非常友好但注意函数体里的代码会在每次命中行时执行性能敏感场景下别放重逻辑否则一个十万行的查询能把单线程跑满几十秒。注册函数要想生效必须在任何连接打开之前完成注册属于进程级声明别放在某个页面的事件里重复注册。连接池调优经常被忽略。System.Data.SQLite 连接池默认是开启的它按连接字符串原文做池标识——也就是说Data Sourceapp.db和Data Sourceapp.db;PoolingTrue是两个池。规范的接法是连接字符串统一入口由SQLiteConnectionStringBuilder生成并缓存在静态属性里再用一个工厂方法统一创建连接。池大小不需要刻意调大桌面场景默认足够真正要调的是Max Pool Size在极端并发查询时的表现通常从 100 起测。最后是验证清单每次改完连接字符串或部署环境后按这个顺序跑一遍基本能放心交付第一PRAGMA integrity_check确认库文件结构完整第二用内置的sqlite3命令行预演核心读写 SQL注意版本一致第三在目标机器上跑一个连接与查询的冒烟测试确认互操作 DLL 能加载第四开 WAL 模式并验证进程重启后模式是否保持第五备份并恢复一次确认备份接口与数据一致性。这套清单能挡住九成部署期的低级事故。我现在的习惯是把冒烟测试直接做成程序启动时的一个后台任务失败就写日志但不阻断主流程——毕竟本地库偶尔打不开等几秒重试通常就恢复了。希望这些经验帮到你少走几趟我当年踩过的弯路。本文还有配套的精品资源点击获取