Euonia.Repository
2026.5.0
dotnet add package Euonia.Repository --version 2026.5.0
NuGet\Install-Package Euonia.Repository -Version 2026.5.0
<PackageReference Include="Euonia.Repository" Version="2026.5.0" />
<PackageVersion Include="Euonia.Repository" Version="2026.5.0" />
<PackageReference Include="Euonia.Repository" />
paket add Euonia.Repository --version 2026.5.0
#r "nuget: Euonia.Repository, 2026.5.0"
#:package Euonia.Repository@2026.5.0
#addin nuget:?package=Euonia.Repository&version=2026.5.0
#tool nuget:?package=Euonia.Repository&version=2026.5.0
Euonia.Repository
Euonia 的持久化无关仓储抽象:定义实体契约、IRepository<TEntity> 系列接口、上下文提供者(IContextProvider / IContextFactory)与分页排序扩展;具体实现由 EF Core 或 MongoDB 包提供。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.Repository - NuGet 包:
Euonia.Repository
安装
dotnet add package Euonia.Repository
选择并添加一个实现:
dotnet add package Euonia.Repository.EfCore
# 或
dotnet add package Euonia.Repository.Mongo
主要功能
- 分层仓储接口:
IRepository<TEntity>、IRepository<TEntity, TKey>、IRepository<TContext, TEntity, TKey>。 - 统一 CRUD:
InsertAsync、UpdateAsync、DeleteAsync支持autoSave;SaveChangesAsync显式保存挂起变更。 - 查询能力:
GetAsync、FindAsync、CountAsync、LongCountAsync、AnyAsync、AllAsync、BuildQuery。 - 附加句柄:所有查询可传入
Func<IQueryable<TEntity>, IQueryable<TEntity>>追加过滤/排序/预加载。 - 上下文管理:
IContextProvider、IContextFactory、IRepositoryContext与AddContextProvider()。 - 实体契约:
IEntity/IEntity<TKey>、IAuditable<TUser>、IHasCreateTime、IHasUpdateTime、IHasDeleteTime、IHasSnowflakeId、ITombstone、IConcurrentEntity<T>。 - 分页排序:
Paginate、Sort、GetPagedCollectionAsync。 - 连接串契约:
ConnectionStringAttribute、IConnectionStringResolver<TContext>。 - 遥测:
RepositoryTelemetry提供euonia.repository.execute活动与耗时指标。
快速开始
声明实体并注入仓储:
using Nerosoft.Euonia.Repository;
public sealed class Order : IEntity<long>, IHasCreateTime
{
public long Id { get; set; }
public string Number { get; set; } = null!;
public DateTime CreatedAt { get; set; }
public object[] GetKeys() => [Id];
}
public sealed class OrderService(IRepository<Order, long> repository)
{
public Task<Order?> GetAsync(long id, CancellationToken cancellationToken)
=> repository.GetAsync(id, cancellationToken);
public Task<List<Order>> FindRecentAsync(CancellationToken cancellationToken)
=> repository.FindAsync(
order => order.CreatedAt > DateTime.UtcNow.AddDays(-7),
query => query.OrderByDescending(order => order.CreatedAt),
cancellationToken);
public async Task<Order> CreateAsync(Order order, CancellationToken cancellationToken)
=> await repository.InsertAsync(order, autoSave: true, cancellationToken);
}
注册上下文提供者:
using Microsoft.Extensions.DependencyInjection;
using Nerosoft.Euonia.Repository;
services.AddContextProvider();
分页查询:
using Nerosoft.Euonia.Repository;
var page = await db.Orders
.Where(order => order.Number.StartsWith("SO"))
.Paginate(page: 1, size: 20, sorts: "-CreatedAt")
.ToListAsync(cancellationToken);
使用示例
自定义 IContextFactory 可以接入非 EF Core / Mongo 的上下文;工厂按 Order 升序尝试:
using Microsoft.Extensions.DependencyInjection;
using Nerosoft.Euonia.Repository;
public sealed class OrderContextFactory(IServiceProvider provider) : IContextFactory
{
public int Order => 0;
public TContext? GetContext<TContext>() where TContext : class, IRepositoryContext
=> provider.GetService<TContext>();
}
services.AddContextProvider();
services.AddTransient<IContextFactory, OrderContextFactory>();
也可以直接在提供者上注册工厂(OrderContext 为自定义 IRepositoryContext 实现):
using Nerosoft.Euonia.Repository;
public sealed class ContextBootstrapper(IContextProvider provider)
{
public void Configure() => provider.SetFactory(() => new OrderContext());
}
配置项
本包只定义连接串契约,实际读取发生在 Euonia.Repository.EfCore 的 AddDataContextFactory<TContext>() 与 EF Core / Mongo 的 IContextFactory 实现中。解析顺序(第一个非空白值获胜):
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 显式 connectionStringFactory |
仅 AddDataContextFactory<TContext>(Func<IServiceProvider, string?>) |
| 2 | ConnectionStrings:<ConnectionStringAttribute.Name> |
特性上的名称,如 [ConnectionString(Name = "Orders")] |
| 3 | ConnectionStrings:<数据上下文类型名> |
如 ConnectionStrings:OrderDbContext |
| 4 | ConnectionStrings:Default |
通用回退 |
| 5 | IConnectionStringResolver<TContext> |
异步解析器(仅 EF Core 的 AddDataContextFactory) |
| 6 | ConnectionStringAttribute.Value |
代码默认值,优先级最低 |
{
"ConnectionStrings": {
"Default": "sqlite://Data Source=app.db"
}
}
ConnectionStrings__Default="sqlite://Data Source=app.db" # .NET 原生:双下划线表示层级
CONNECTION_STRING_DEFAULT="sqlite://Data Source=app.db" # 仓库 alias:大写单下划线
{provider}://{connection}前缀由 EF Core 的AddDataContextFactory解析;Mongo 与直接传DbContextOptionsBuilder的注册方式不经过该前缀。
核心类型
| 类型 | 作用 |
|---|---|
IRepository<TEntity> |
基础仓储(查询、CRUD、分页) |
IRepository<TEntity, TKey> |
增加按键查询 |
IRepository<TContext, TEntity, TKey> |
绑定上下文的仓储 |
IRepositoryContext |
数据上下文契约(连接、事务、保存) |
IContextProvider / IContextFactory |
解析或创建上下文 |
ConnectionStringAttribute |
声明上下文使用的连接串名称与代码默认值 |
IConnectionStringResolver<TContext> |
按上下文类型异步解析连接串 |
RepositoryExtensions |
Paginate、Sort、GetPagedCollectionAsync |
RepositoryModule |
注册 AddContextProvider() 的模块 |
RepositoryTelemetry |
仓储 ActivitySource 与耗时指标 |
注意事项 / 限制
autoSave默认是true;工作单元内应传autoSave: false,由IUnitOfWork.CompleteAsync()统一保存,否则每次 CRUD 都会立即提交。IRepository<TEntity>继承IDisposable,实现通常是 Scoped;不要把它捕获到单例或跨请求复用。GetAsync(TKey key)通过nameof(IEntity<TKey>.Id)构造谓词,实体必须实现IEntity<TKey>并公开Id。FindAsync(IEnumerable<TKey> keys)在键集合为空时直接返回空列表,不会访问数据库。Sort只识别公共实例属性,未知属性名会被静默忽略;Paginate会把小于 1 的页码按 1、小于 0 的页大小按 0 处理。IRepositoryContext.BeginTransactionAsync的默认实现只是调用GetConnection().BeginTransaction()并丢弃返回值;自定义上下文应重写它,否则事务不会挂到上下文上。RepositoryTelemetry只记录操作名与实体名,不记录 SQL、连接串或参数;没有监听者时开销接近零。
相关包
Euonia.Repository.EfCore—— EF Core 实现Euonia.Repository.Mongo—— MongoDB 实现Euonia.Uow—— 工作单元Euonia.Domain—— 实体与聚合Euonia.Linq—— 查询与规约Euonia.Modularity——RepositoryModule所在框架
常见问题与故障排查
配置了连接串,但仓储没有使用它
AddEfCoreRepository<TContext>(options => ...) 直接接收 DbContextOptionsBuilder,不会读取 ConnectionStrings。要使用名称回退、环境变量与 {provider}:// 前缀,改用 AddDataContextFactory<TContext>();同时确认 [ConnectionString(Name = "...")] 的名称与配置键一致,且为该 provider 注册了键控 ConnectionConfigurator。
工作单元回滚了,数据却已经写入
仓储的 autoSave 默认是 true,每次 InsertAsync/UpdateAsync/DeleteAsync 都会立即保存,工作单元之后无法回滚已提交的数据。工作单元内统一传 autoSave: false,由 IUnitOfWork.CompleteAsync() 统一保存。
排序参数不生效
Sort 只接受 [+|-]属性名 格式,例如 -CreatedAt;写成 "CreateTime desc" 或带空格的字符串会被正则忽略,查询保持原顺序。Paginate 也会把小于 1 的页码按 1、小于 0 的页大小按 0 处理。
GetAsync(key) 总是返回 null
IRepository<TEntity, TKey> 按键查询依赖 IEntity<TKey>.Id 属性;实体没有实现该接口、Id 名称不匹配,或 Mongo 的键不是可解析的 ObjectId 字符串时都会查不到;Mongo 的键格式错误会抛 FormatException。检查实体契约与键类型,Mongo 场景不要用 long/Guid 作为 TKey。
自定义上下文的 BeginTransactionAsync 没有开启事务
IRepositoryContext.BeginTransactionAsync 的默认实现只是调用 GetConnection().BeginTransaction() 并丢弃返回值;自定义上下文必须重写它并保存事务句柄,否则后续 CommitAsync/RollbackAsync 无法作用于真实事务。
最佳实践
- 用稳定的
[ConnectionString(Name = "Orders")]命名连接串,环境差异用ConnectionStrings__Orders或CONNECTION_STRING_ORDERS覆盖;需要解析链时统一走AddDataContextFactory。 - 工作单元内
autoSave: false,仓储按 Scoped 解析,不要把IRepository捕获到单例或跨请求复用。 - 分页排序使用
Paginate(page, size, "-CreatedAt")这类格式;对外部传入的页码/页大小先做边界校验。 - 连接串与凭据放环境变量或密钥库,不要写进源码;用
RepositoryTelemetry观察操作耗时,不记录 SQL 与参数。
版本与兼容
- 目标框架:
net10.0、net11.0(Source/common.props)。 - 关键依赖:
Euonia.Linq、Euonia.Modularity、Euonia.Uow;具体包版本由仓库构建属性决定。 - 已知边界:连接串解析由 EF Core 适配包与
IContextFactory实现,本包只定义契约;默认BeginTransactionAsync不保存事务;Mongo 的键与事务语义由 Mongo 适配包决定。
许可证
本项目依据仓库根目录的 GNU General Public License v3.0 发布。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Euonia.Linq (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
- Euonia.Uow (>= 2026.5.0)
- Microsoft.Extensions.DependencyInjection (>= 11.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 11.0.0)
- Microsoft.Extensions.Options (>= 11.0.0)
-
net11.0
- Euonia.Linq (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
- Euonia.Uow (>= 2026.5.0)
- Microsoft.Extensions.DependencyInjection (>= 11.0.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Euonia.Repository:
| Package | Downloads |
|---|---|
|
Euonia.Repository.EfCore
Euonia Repository 的 Entity Framework Core 实现:自动应用配置与墓碑查询过滤的 DbContext 基类、仓储实现、ID 值生成器与值转换器。 / Entity Framework Core implementation for Euonia Repository: DbContext base with auto-applied configurations and tombstone query filters, repository implementations, ID value generators and value converters. |
|
|
Euonia.Repository.Mongo
Euonia Repository 的 MongoDB 实现:客户端会话管理、类型化集合访问、仓储与流式类映射配置。 / MongoDB implementation for Euonia Repository: context with client session management, typed collection access, repositories and fluent class-map configuration. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.5.0 | 222 | 11/13/2026 |
| 2026.4.7 | 158 | 11/3/2026 |
| 2026.4.6 | 156 | 10/28/2026 |
| 2026.4.5 | 173 | 10/19/2026 |
| 2026.4.4 | 137 | 10/19/2026 |
| 2026.4.3 | 151 | 10/1/2026 |
| 2026.4.1 | 146 | 9/24/2026 |
| 2026.4.0 | 147 | 9/22/2026 |
| 2026.3.16 | 178 | 9/8/2026 |
| 2026.3.15 | 163 | 9/2/2026 |
| 2026.3.14 | 173 | 8/30/2026 |
| 2026.3.13 | 170 | 8/29/2026 |
| 2026.3.12 | 161 | 8/28/2026 |
| 2026.3.11 | 169 | 8/27/2026 |
| 2026.3.10 | 160 | 8/26/2026 |
| 2026.3.9 | 169 | 8/25/2026 |
| 2026.3.8 | 161 | 8/24/2026 |
| 2026.3.7 | 183 | 8/20/2026 |
| 2026.3.6 | 169 | 8/20/2026 |
| 2026.3.5 | 175 | 8/19/2026 |