CgdataBase.FreeSql 1.9.34

CgdataBase.FreeSql

对 FreeSql 的初始化与常用 CRUD 进行轻量封装，提供一套面向应用层的统一访问入口（IDataHelper / DataHelper），并内置 SQLite 离线库初始化、连接字符串辅助、SQL 日志输出等能力。

包含内容

核心类型

• IBaseInfo：数据表实体的基础约定，仅要求包含 long Id 主键字段。
• IDataHelper：面向应用层的数据访问接口（初始化、增删改查、存在性判断、以及暴露 IFreeSql）。
• DataHelper：默认实现，提供单例访问入口 DataHelper.Instance，并支持替换实现（可注入自定义 IDataHelper）。

主要能力

• 统一初始化入口：封装 FreeSqlBuilder，支持选择数据库类型、连接字符串、是否自动同步结构。
• 常用 CRUD：基于 IBaseInfo 约束提供泛型增删改查方法（单条/批量）。
• 查询增强：支持表达式筛选、排序、取首条、任意存在性判断；并保留 GetFreeSql() 以支持复杂查询/事务等高级用法。
• 离线数据库：提供 InitializeOfflineDatabase(...)，默认在应用目录创建/使用 database.db（SQLite）并开启结构同步。
• 连接字符串辅助：提供 MySQL / SQLite 的连接字符串构造方法。
• SQL 日志输出：通过 NLog 在 Trace 等级下输出执行的 SQL（UseMonitorCommand）。
• JSON 映射：默认启用 UseJsonMap()，便于实体属性与 JSON 字段映射。

快速开始

0) 引用方式

• 通过源码：在项目中添加对 CgdataBase.FreeSql 的项目引用（ProjectReference）。
• 通过包：如果已将该项目打包并发布到 NuGet 源，则直接引用对应包即可。

1) 定义实体

using CgdataBase;

public class UserInfo : IBaseInfo
{
 public long Id { get; set; }
 public string? Name { get; set; }
}

2) 初始化并使用

using CgdataBase;

DataHelper.Instance.Initialize(
 FreeSql.DataType.Sqlite,
 DataHelper.GetSqliteConnectionString("database.db"),
 autoSyncStructure: true);

await DataHelper.Instance.AddDataInfo(new UserInfo { Name = "Alice" });
var all = await DataHelper.Instance.SelectAll<UserInfo>();

说明与约定

• DataHelper.Instance 首次访问时会默认初始化一个 SQLite 离线库（应用目录下的 database.db），便于开箱即用；如果你的应用需要连接到其它数据库，请在启动阶段显式调用 Initialize(...) 或 InitializeDatabase(...) 覆盖默认行为。
• IDataHelper.GetFreeSql() 会直接返回 IFreeSql 实例，建议在需要事务、复杂查询、联表等场景下使用原生 FreeSql 能力完成。

与应用配置集成

如果你的应用已经实现了 CgdataBase.Core 中的 IAppSettingsBase，可以直接使用：

using CgdataBase;

IAppSettingsBase settings = ...;
DataHelper.InitializeDatabase(settings, DataHelper.Instance);

当 settings.OfflineMode == true 时，会自动走离线库初始化逻辑；否则根据 settings.DatabaseType / settings.DatabaseConnectionString / settings.AutoSyncStructure 初始化对应数据库。

依赖项

• FreeSql.Extensions.JsonMap
• FreeSql.Provider.MySqlConnector
• FreeSql.Provider.Sqlite
• NLog

目标框架

• net8.0
• net10.0