mirror of
https://github.com/nsnail/FreeSql.git
synced 2025-06-18 20:08:15 +08:00
update readme
This commit is contained in:
28810
@ -1,284 +1,216 @@
|
||||
这是 [FreeSql](https://github.com/2881099/FreeSql) 衍生出来的扩展包，包含 DbContext & DbSet、Repository & UnitOfWork 实现面向对象的特性（QQ群：4336577）。
|
||||
FreeSql.DbContext 实现类似 EFCore 使用习惯，跟踪对象状态，最终通过 SaveChanges 方法提交事务。
|
||||
|
||||
## 安装
|
||||
|
||||
> dotnet add package FreeSql.DbContext
|
||||
|
||||
## 更新日志
|
||||
## 如何使用
|
||||
|
||||
### v0.6.5
|
||||
|
||||
- 修复 Repository 级联保存的 bug；
|
||||
- 添加工作单元开启方法；
|
||||
- 适配 .net framework 4.5、netstandard 2.0；
|
||||
|
||||
### v0.6.1
|
||||
|
||||
- 拆分 FreeSql 小包引用，各数据库单独包、延时加载包；
|
||||
- FreeSql.Extensions.LazyLoading
|
||||
- FreeSql.Provider.MySql
|
||||
- FreeSql.Provider.PostgreSQL
|
||||
- FreeSql.Provider.SqlServer
|
||||
- FreeSql.Provider.Sqlite
|
||||
- FreeSql.Provider.Oracle
|
||||
- 移除 IFreeSql.Cache，以及 ISelect.Caching 方法；
|
||||
- 移除 IFreeSql.Log，包括内部原有的日志输出，改为 Trace.WriteLine；
|
||||
- IAdo.Query\<dynamic\> 读取返回变为 List\<Dictionary\<string, object\>\>；
|
||||
- 定义 IFreeSql 和以前一样，移除了 UseCache、UseLogger 方法；
|
||||
|
||||
## DbContext & DbSet
|
||||
|
||||
```csharp
|
||||
using (var ctx = new SongContext()) {
|
||||
var song = new Song { BigNumber = "1000000000000000000" };
|
||||
ctx.Songs.Add(song);
|
||||
|
||||
song.BigNumber = (BigInteger.Parse(song.BigNumber) + 1).ToString();
|
||||
ctx.Songs.Update(song);
|
||||
|
||||
var tag = new Tag {
|
||||
Name = "testaddsublist",
|
||||
Tags = new[] {
|
||||
new Tag { Name = "sub1" },
|
||||
new Tag { Name = "sub2" },
|
||||
new Tag {
|
||||
Name = "sub3",
|
||||
Tags = new[] {
|
||||
new Tag { Name = "sub3_01" }
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
ctx.Tags.Add(tag);
|
||||
0、通用方法，为啥是0？？？
|
||||
```
|
||||
using (var ctx = fsql.CreateDbContext()) {
|
||||
//var db1 = ctx.Set<Song>();
|
||||
//var db2 = ctx.Set<Tag>();
|
||||
|
||||
var item = new Song { };
|
||||
ctx.Add(item);
|
||||
ctx.SaveChanges();
|
||||
}
|
||||
```
|
||||
|
||||
## Repository & UnitOfWork
|
||||
> 注意：DbContext 对象多线程不安全
|
||||
|
||||
仓储与工作单元一起使用，工作单元具有事务特点。
|
||||
1、在 OnConfiguring 方法上配置与 IFreeSql 关联
|
||||
|
||||
```csharp
|
||||
using (var unitOfWork = fsql.CreateUnitOfWork()) {
|
||||
var songRepository = unitOfWork.GetRepository<Song, int>();
|
||||
var tagRepository = unitOfWork.GetRepository<Tag, int>();
|
||||
public class SongContext : DbContext {
|
||||
|
||||
var song = new Song { BigNumber = "1000000000000000000" };
|
||||
songRepository.Insert(song);
|
||||
public DbSet<Song> Songs { get; set; }
|
||||
public DbSet<Song> Tags { get; set; }
|
||||
|
||||
songRepository.Update(song);
|
||||
|
||||
song.BigNumber = (BigInteger.Parse(song.BigNumber) + 1).ToString();
|
||||
songRepository.Update(song);
|
||||
|
||||
var tag = new Tag {
|
||||
Name = "testaddsublist",
|
||||
Tags = new[] {
|
||||
new Tag { Name = "sub1" },
|
||||
new Tag { Name = "sub2" },
|
||||
new Tag {
|
||||
Name = "sub3",
|
||||
Tags = new[] {
|
||||
new Tag { Name = "sub3_01" }
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
tagRepository.Insert(tag);
|
||||
|
||||
ctx.Commit();
|
||||
protected override void OnConfiguring(DbContextOptionsBuilder builder) {
|
||||
builder.UseFreeSql(dbcontext_01.Startup.Fsql);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Repository
|
||||
|
||||
简单使用仓储，有状态跟踪，它不包含事务的特点。
|
||||
|
||||
```csharp
|
||||
var songRepository = fsql.GetRepository<Song, int>();
|
||||
var song = new Song { BigNumber = "1000000000000000000" };
|
||||
songRepository.Insert(song);
|
||||
```
|
||||
|
||||
## IFreeSql 核心定义
|
||||
|
||||
```csharp
|
||||
var fsql = new FreeSql.FreeSqlBuilder()
|
||||
.UseConnectionString(FreeSql.DataType.Sqlite, @"Data Source=|DataDirectory|\dd2.db;Pooling=true;Max Pool Size=10")
|
||||
.UseAutoSyncStructure(true)
|
||||
.UseNoneCommandParameter(true)
|
||||
|
||||
.UseMonitorCommand(cmd => Trace.WriteLine(cmd.CommandText))
|
||||
.Build();
|
||||
|
||||
public class Song {
|
||||
[Column(IsIdentity = true)]
|
||||
public int Id { get; set; }
|
||||
public string BigNumber { get; set; }
|
||||
|
||||
[Column(IsVersion = true)] //乐观锁
|
||||
public long versionRow { get; set; }
|
||||
}
|
||||
public class Tag {
|
||||
[Column(IsIdentity = true)]
|
||||
public int Id { get; set; }
|
||||
|
||||
public int? Parent_id { get; set; }
|
||||
public virtual Tag Parent { get; set; }
|
||||
|
||||
public string Name { get; set; }
|
||||
public DateTime? Create_time { get; set; }
|
||||
public bool? Is_deleted { get; set; }
|
||||
public string Title { get; set; }
|
||||
public string Url { get; set; }
|
||||
|
||||
public virtual ICollection<Tag> Tags { get; set; }
|
||||
}
|
||||
public class Song_tag {
|
||||
public int Song_id { get; set; }
|
||||
public virtual Song Song { get; set; }
|
||||
|
||||
public class SongContext : DbContext {
|
||||
public DbSet<Song> Songs { get; set; }
|
||||
public DbSet<Tag> Tags { get; set; }
|
||||
public int Tag_id { get; set; }
|
||||
public virtual Tag Tag { get; set; }
|
||||
}
|
||||
|
||||
protected override void OnConfiguring(DbContextOptionsBuilder builder) {
|
||||
builder.UseFreeSql(fsql);
|
||||
}
|
||||
public class Tag {
|
||||
[Column(IsIdentity = true)]
|
||||
public int Id { get; set; }
|
||||
public int? Parent_id { get; set; }
|
||||
public virtual Tag Parent { get; set; }
|
||||
|
||||
public decimal? Ddd { get; set; }
|
||||
public string Name { get; set; }
|
||||
|
||||
public virtual ICollection<Song> Songs { get; set; }
|
||||
public virtual ICollection<Tag> Tags { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
# 过滤器与验证
|
||||
|
||||
假设我们有User(用户)、Topic(主题)两个实体，在领域类中定义了两个仓储：
|
||||
使用的时候与 EFCore 类似：
|
||||
|
||||
```csharp
|
||||
var userRepository = fsql.GetGuidRepository<User>();
|
||||
var topicRepository = fsql.GetGuidRepository<Topic>();
|
||||
long id = 0;
|
||||
|
||||
using (var ctx = new SongContext()) {
|
||||
|
||||
var song = new Song { };
|
||||
await ctx.Songs.AddAsync(song);
|
||||
id = song.Id;
|
||||
|
||||
var adds = Enumerable.Range(0, 100)
|
||||
.Select(a => new Song { Create_time = DateTime.Now, Is_deleted = false, Title = "xxxx" + a, Url = "url222" })
|
||||
.ToList();
|
||||
await ctx.Songs.AddRangeAsync(adds);
|
||||
|
||||
for (var a = 0; a < adds.Count; a++)
|
||||
adds[a].Title = "dkdkdkdk" + a;
|
||||
|
||||
ctx.Songs.UpdateRange(adds);
|
||||
|
||||
ctx.Songs.RemoveRange(adds.Skip(10).Take(20).ToList());
|
||||
|
||||
//ctx.Songs.Update(adds.First());
|
||||
|
||||
adds.Last().Url = "skldfjlksdjglkjjcccc";
|
||||
ctx.Songs.Update(adds.Last());
|
||||
|
||||
//throw new Exception("回滚");
|
||||
|
||||
await ctx.SaveChangesAsync();
|
||||
}
|
||||
```
|
||||
|
||||
在开发过程中，总是担心 topicRepository 的数据安全问题，即有可能查询或操作到其他用户的主题。因此我们在v0.0.7版本进行了改进，增加了 filter lambad 表达式参数。
|
||||
2、注入方式使用
|
||||
|
||||
```csharp
|
||||
var userRepository = fsql.GetGuidRepository<User>(a => a.Id == 1);
|
||||
var topicRepository = fsql.GetGuidRepository<Topic>(a => a.UserId == 1);
|
||||
public void ConfigureServices(IServiceCollection services)
|
||||
{
|
||||
services.AddSingleton<IFreeSql>(Fsql);
|
||||
services.AddFreeDbContext<SongContext>(options => options.UseFreeSql(Fsql));
|
||||
}
|
||||
```
|
||||
|
||||
* 在查询/修改/删除时附加此条件，从而达到不会修改其他用户的数据；
|
||||
* 在添加时，使用表达式验证数据的合法性，若不合法则抛出异常；
|
||||
|
||||
# 分表与分库
|
||||
|
||||
FreeSql 提供 AsTable 分表的基础方法，GuidRepository 作为分存式仓储将实现了分表与分库（不支持跨服务器分库）的封装。
|
||||
在 mvc 中获取：
|
||||
|
||||
```csharp
|
||||
var logRepository = fsql.GetGuidRepository<Log>(null, oldname => $"{oldname}_{DateTime.Now.ToString("YYYYMM")}");
|
||||
IFreeSql _orm;
|
||||
public ValuesController(SongContext songContext) {
|
||||
}
|
||||
```
|
||||
|
||||
上面我们得到一个日志仓储按年月分表，使用它 CURD 最终会操作 Log_201903 表。
|
||||
## 优先级
|
||||
|
||||
合并两个仓储，实现分表下的联表查询：
|
||||
OnConfiguring > AddFreeDbContext
|
||||
|
||||
## 乐观锁
|
||||
|
||||
更新实体数据，在并发情况下极容易造成旧数据将新的记录更新。FreeSql 核心部分已经支持乐观锁。
|
||||
|
||||
乐观锁的原理，是利用实体某字段，如：long version，更新前先查询数据，此时 version 为 1，更新时产生的 SQL 会附加 where version = 1，当修改失败时（即 Affrows == 0）抛出异常。
|
||||
|
||||
每个实体只支持一个乐观锁，在属性前标记特性：[Column(IsVersion = true)] 即可。
|
||||
|
||||
> 无论是使用 FreeSql/FreeSql.Repository/FreeSql.DbContext，每次更新 version 的值都会增加 1
|
||||
|
||||
## 说明
|
||||
|
||||
- DbContext 操作的数据在最后 SaveChanges 时才批量保存；
|
||||
- DbContext 内所有操作，使用同一个事务；
|
||||
- 当实体存在自增时，或者 Add/AddRange 的时候主键值为空，会提前开启事务；
|
||||
- 支持同步/异步方法；
|
||||
|
||||
## 合并机制
|
||||
|
||||
db.Add(new Xxx());
|
||||
db.Add(new Xxx());
|
||||
db.Add(new Xxx());
|
||||
|
||||
这三步，会合并成一个批量插入的语句执行，前提是它们没有自增属性。
|
||||
|
||||
适用 Guid 主键，Guid 主键的值不用设置，交给 FreeSql 处理即可，空着的 Guid 主键会在插入时获取有序不重值的 Guid 值。
|
||||
|
||||
又比如：
|
||||
|
||||
db.Add(new Xxx());
|
||||
db.Add(new Xxx());
|
||||
db.Update(xxx);
|
||||
db.Add(new Xxx());
|
||||
|
||||
Guid Id 的情况下，执行三次命令：前两次插入合并执行，update 为一次，后面的 add 为一次。
|
||||
|
||||
## 联级保存
|
||||
|
||||
请移步文档[《联级保存》](https://github.com/2881099/FreeSql/wiki/%e8%81%94%e7%ba%a7%e4%bf%9d%e5%ad%98)
|
||||
|
||||
## 实体变化事件
|
||||
|
||||
全局设置：
|
||||
|
||||
```csharp
|
||||
fsql.GetGuidRepository<User>().Select.FromRepository(logRepository)
|
||||
.LeftJoin<Log>(b => b.UserId == a.Id)
|
||||
.ToList();
|
||||
fsql.SetDbContextOptions(opt => {
|
||||
opt.OnEntityChange = report => {
|
||||
Console.WriteLine(report);
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
注意事项：
|
||||
单独设置 DbContext 或者 UnitOfWork：
|
||||
|
||||
* 不能使用 CodeFirst 迁移分表，开发环境时仍然可以迁移 Log 表；
|
||||
* 不可在分表分库的实体类型中使用《延时加载》；
|
||||
```csharp
|
||||
var ctx = fsql.CreateDbContext();
|
||||
ctx.Options.OnEntityChange = report => {
|
||||
Console.WriteLine(report);
|
||||
};
|
||||
|
||||
# 历史版本
|
||||
var uow = fsql.CreateUnitOfWork();
|
||||
uow.OnEntityChange = report => {
|
||||
Console.WriteLine(report);
|
||||
};
|
||||
```
|
||||
|
||||
### v0.5.23
|
||||
参数 report 是一个 List 集合，集合元素的类型定义如下：
|
||||
|
||||
- 增加 DbSet/Repository FlushState 手工清除状态管理数据；
|
||||
```csharp
|
||||
public class EntityChangeInfo
|
||||
{
|
||||
public object Object { get; set; }
|
||||
public EntityChangeType Type { get; set; }
|
||||
}
|
||||
public enum EntityChangeType { Insert, Update, Delete, SqlRaw }
|
||||
```
|
||||
|
||||
### v0.5.21
|
||||
| 变化类型 | 说明 |
|
||||
| -- | -- |
|
||||
| Insert | 实体对象被插入 |
|
||||
| Update | 实体对象被更新 |
|
||||
| Delete | 实体对象被删除 |
|
||||
| SqlRaw | 执行了SQL语句 |
|
||||
|
||||
- 修复 AddOrUpdate/InsertOrUpdate 当主键无值时，仍然查询了一次数据库；
|
||||
- 增加 查询数据时 TrackToList 对导航集合的状态跟踪；
|
||||
- 完善 AddOrUpdateNavigateList 级联保存，忽略标记 IsIgnore 的集合属性；
|
||||
- 完成 IFreeSql.Include、IncludeMany 功能；
|
||||
SqlRaw 目前有两处地方比较特殊：
|
||||
- 多对多联级更新导航属性的时候，对中间表的全部删除操作；
|
||||
- 通用仓储类 BaseRepository 有一个 Delete 方法，参数为表达式，而并非实体；
|
||||
```csharp
|
||||
int Delete(Expression<Func<TEntity, bool>> predicate);
|
||||
```
|
||||
|
||||
### v0.5.12
|
||||
|
||||
- 增加 工作单元开关，可在任意 Insert/Update/Delete 之前调用，以关闭工作单元使其失效；[PR #1](https://github.com/2881099/FreeSql.DbContext/pull/1)
|
||||
|
||||
### v0.5.9
|
||||
|
||||
- 增加 linq to sql 的查询语法，以及单元测试，[wiki](https://github.com/2881099/FreeSql/wiki/LinqToSql)；
|
||||
- 修复 EnableAddOrUpdateNavigateList 设置对异步方法无效的 bug；
|
||||
|
||||
### v0.5.8
|
||||
|
||||
- 增加 IFreeSql.SetDbContextOptions 设置 DbContext 的功能：开启或禁用连级一对多导航集合属性保存的功能，EnableAddOrUpdateNavigateList（默认开启）；
|
||||
- 增加 IUnitOfWork.IsolationLevel 设置事务级别；
|
||||
|
||||
### v0.5.7
|
||||
|
||||
- 修复 UnitOfWork.GetRepository() 事务 bug，原因：仓储的每步操作都提交了事务；
|
||||
|
||||
### v0.5.5
|
||||
|
||||
- 修复 MapEntityValue 对 IsIgnore 未处理的 bug；
|
||||
|
||||
### v0.5.4
|
||||
|
||||
- 修复 Repository 追加导航集合的保存 bug；
|
||||
- 公开 IRepository.Orm 对象；
|
||||
|
||||
### v0.5.3
|
||||
|
||||
- 修复 实体跟踪的 bug，当查询到的实体自增值为 0 时重现；
|
||||
- 优化 状态管理字典为 ConcurrentDictionary；
|
||||
|
||||
### v0.5.2
|
||||
|
||||
- 优化 SqlServer UnitOfWork 使用bug，在 FreeSql 内部解决的；
|
||||
- 补充 测试与支持联合主键的自增；
|
||||
|
||||
### v0.5.1
|
||||
|
||||
- 补充 开放 DbContext.UnitOfWork 对象，方便扩展并保持在同一个事务执行；
|
||||
- 补充 增加 DbSet\<object\>、Repository\<object\> 使用方法，配合 AsType(实体类型)，实现弱类型操作；
|
||||
- 修复 DbContext.AddOrUpdate 传入 null 时，任然会查询一次数据库的 bug；
|
||||
- 优化 DbContext.AddOrUpdate 未添加实体主键的错误提醒；
|
||||
- 修复 DbContext.Set\<object\> 缓存的 bug，使用多种弱类型时发生；
|
||||
- 修复 IsIgnore 过滤字段后，查询的错误；
|
||||
- 修复 全局过滤器功能迁移的遗留 bug；
|
||||
|
||||
### v0.4.14
|
||||
|
||||
- 优化 Add 时未设置主键的错误提醒；
|
||||
|
||||
### v0.4.13
|
||||
|
||||
- 补充 Repository 增加 Attach 方法；
|
||||
- 优化 Update/AddOrUpdate 实体的时候，若状态管理不存在，尝试查询一次数据库，以便跟踪对象；
|
||||
|
||||
### v0.4.12
|
||||
|
||||
- 修复 非自增情况下，Add 后再 Update 该实体时，错误（需要先 Attach 或查询）的 bug；
|
||||
|
||||
### v0.4.10
|
||||
|
||||
- 补充 开放 DbContext.Orm 对象；
|
||||
- 修复 OnConfiguring 未配置时注入获取失败的 bug；
|
||||
|
||||
### v0.4.6
|
||||
|
||||
- 修复 DbSet AddRange/UpdateRange/RemoveRange 参数为空列表时报错，现在不用判断 data.Any() == true 再执行；
|
||||
- 增加 DbContext 对 DbSet 的快速代理方法(Add/Update/Remove/Attach)；
|
||||
- 增加 DbContext 通用类，命名为：FreeContext，也可以通过 IFreeSql 扩展方法 CreateDbContext 创建；
|
||||
- 增加 ISelect NoTracking 扩展方法，查询数据时不追踪（从而提升查询性能）；
|
||||
|
||||
### v0.4.5
|
||||
|
||||
- 增加 DbSet Attach 方法附加实体，可用于不查询就更新或删除；
|
||||
|
||||
### v0.4.2
|
||||
|
||||
- 增加 DbSet UpdateAsync/UpdateRangeAsync 方法，当一个实体被更新两次时，会先执行前面的队列；
|
||||
- 增加 GetRepository 获取联合主键的适用仓储类；
|
||||
- 增加 DbSet 在 Add/Update 时对导航属性(OneToMany) 的处理（AddOrUpdate）；
|
||||
|
||||
### v0.4.1
|
||||
- 独立 FreeSql.DbContext 项目；
|
||||
- 实现 Repository + DbSet 统一的状态跟踪与工作单元；
|
||||
- 增加 DbSet AddOrUpdate 方法；
|
||||
- 增加 Repository InsertOrUpdate 方法；
|
||||
DbContext.SaveChanges，或者 Repository 对实体的 Insert/Update/Delete，或者 UnitOfWork.Commit 操作都会最多触发一次该事件。
|
||||
Reference in New Issue
Block a user