Crping.EFCore.Common 9.0.0

Crping.EFCore.Common

Crping.EFCore的接口与类型定义

版本更新说明

---

9.0.0

2026年8月14日 星期五

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 9.0.0

破坏性变更 — 删除过时接口与扩展方法（v9.0.0 未发布，无兼容负担）

• 删除旧接口 IMyConfiguration（→ IAppConfiguration）、IToVo（→ IViewObject）、IEnabled（→ IIsEnabled）、IDisabled（→ IIsDisabled）
• 删除公共扩展方法 NotDisabled<TModel>（旧 IDisabled 版）与 OnlyEnabled<TModel>（旧 IEnabled 版），统一使用 NotIsDisabled / OnlyIsEnabled
• 其余 BLL 去 MVC 分层解耦 / 写后读绑定 Options 化均为 Core 层与 Controller 层变更

---

8.11.0

2026年8月13日 星期四

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.11.0

• 无功能性变更，仅同步版本号（依赖升级 / 写后读绑定中间件 / 修复均为 Core 层与 Controller 层变更，Common 契约未变）

---

8.10.0

2026年8月13日 星期四

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.10.0

破坏性变更 — Keyset 游标格式定稿（Common 层 KeysetCursor）

• 枚举游标值仅存底层数值：EncodeValue 枚举分支移除内嵌 AssemblyQualifiedName 类型名（游标更短、解码不再有 Type.GetType 类型加载路径，AOT/裁剪友好）
• Decode 移除双参数重载，expectedTypes 参数必填：按排序键期望类型还原值（含枚举），键值数量/类型强校验，无 legacy 纯格式解码路径（旧"退化为纯格式解码"行为移除）
• 其余 Keyset / Offset 性能优化与列表 API 三态对齐（ListQuery / GetListPageAsync / 删旧列表 API）为 Core 层变更，Common 契约（ListPage / OffsetPage / KeysetPage 等）未变

---

8.9.0

2026年8月12日 星期三

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.9.0

• 无功能性变更，仅同步版本号（ResolveSort 排序键解析虚方法为 Core 层 WebApiBaseBLL 变更，Common 契约未变）

---

8.8.0

2026年8月11日 星期二

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.8.0

• 无功能性变更，仅同步版本号（点分路径排序键提取 / bool 排序键修复 / OrderBy 全能化重构均为 Core 层 KeysetQuery / KeysetPredicateBuilder 变更，Common 契约未变）

---

8.7.0

2026年8月11日 星期二

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.7.0

破坏性变更 — 分页结果契约属性顺序调整与 required 强化

• KeysetPage<T> / OffsetPage<T> 的 PageInfo / Pagination 属性移至 Items 之前
• 两个属性均改为 required init（移除默认值），调用方构造时必须显式提供所有属性
• 迁移指南：JSON 反序列化顺序可能变化，手动构造对象时需调整属性顺序或使用命名参数

---

8.6.0

2026年8月10日 星期一

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.6.0

新类型 — ListPage<T> 分页契约

• ListPage<T>（sealed、init-only）：{ required Pagination Pagination, required List<T> Items }，作为旧分页 API（GetListAsync / 分页版 GetRawListAsync）的两段式返回契约（破坏性：返回类型变更，需重编译）

其余无功能性变更：OrderByExpr 任意表达式排序为 Core 层 KeysetQuery / OffsetQuery 构建器变更，KeysetCursor 编解码未变。

---

8.5.0

2026年8月9日 星期日

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.5.0

新增类型（端点级缓存开关）

• CacheEnable：按端点控制读操作缓存的开关集合（9 个开关，默认全关）：GetDetailsAsync / GetAsync / GetDetailsForAdminAsync / GetForEditorAsync / GetForAdminEditorAsync / GetSimpleAsync / GetListItemAsync / GetKvpsAsync / GetTotalAsync；GetSwitch(name) 反射缓存解析，未知开关名抛出带有效列表的 InvalidOperationException；仅门面方法（对应 HTTP 端点）查询，共享方法只响应调用方显式传入的 useCache 三态参数（互不干扰）

接口变更（破坏性 — 二进制不兼容，需重编译）

• ICacheManager.GetAsync<T> 新增可选参数 CachePolicy? policy = null：提供滑动过期策略时命中会续期（与 GetOrAddAsync<T> 行为一致）；现有调用源码兼容（bool 隐式转 bool? 同理适用于三态化后的各 BLL 读方法签名）

---

8.4.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.4.0

• 无功能性变更，仅同步版本号（TimeProvider 注入为 Core 层 BLL/DAL 变更，Common 接口未变）

---

8.3.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.3.0

• 无功能性变更，仅同步版本号（Controller 层健壮性/开关机制完善与 Core 层 DatabaseExtensions 迁入，Common 接口未变）

---

8.1.0

2026年8月8日 星期六

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.1.0

破坏性变更 — 分页结果契约两段式

• OffsetPage<T> → { items, pagination }：删除顶层 8 个分页属性（Page / PageSize / PageCount / RecordCount / HasNext / HasPrev / OrderBy / Ascending）与 ToPagination()，新增不可变 PaginationInfo Pagination
• KeysetPage<T> → { items, pageInfo }：删除顶层 5 个属性（NextCursor / PrevCursor / HasNext / HasPrev / PageSize），新增不可变 KeysetPageInfo PageInfo
• 新增 PaginationInfo / KeysetPageInfo（全部 init-only，结果契约不可被调用方事后修改）
• 调用方迁移：page.Page → page.Pagination.Page、page.HasNext → page.PageInfo.HasNext 等

---

8.0.0

2026年8月7日 星期五

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 8.0.0

• 无功能性变更，仅同步版本号（useCache 缓存开关、ConnectionName 只读化均为 Core / BLL 层变更，Common 接口未变）

---

7.7.0

2026年8月7日 星期五

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.7.0

新增类型（统一缓存管理，无 EF 依赖）

• ICacheManager：统一缓存门面接口（泛型 GetOrAdd / Get / Set / Remove / Invalidate + Stats 命中统计），键由 modelKey + 版本号 + keySuffix 组成
• CachePolicy：缓存策略（滑动/绝对过期、CacheNull 空值防护、ExpirationJitter 过期抖动防雪崩）
• ICacheVersionStore：模型版本号存储抽象（Get / Increment），支撑模型级原子失效
• CacheKeys：表达式缓存键生成器（结构签名 + 闭包捕获值，防闭包键冲突）
• CacheHitStats：命中统计（Hits / Misses / HitRate）

---

7.6.0

2026年8月6日 星期四

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.6.0

新增类型（Offset 偏移分页契约）

• OffsetPage<T>：偏移分页结果契约（Items + Page + PageSize + RecordCount + PageCount + HasNext + HasPrev + OrderBy + Ascending），与 KeysetPage<T> 对称；含 ToPagination() 供旧响应形状包装

---

7.5.0

2026年8月6日 星期四

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.5.0

新增类型（Keyset 游标分页契约，无 EF 依赖）

• KeysetPage<T>：分页结果契约（Items + NextCursor / PrevCursor + HasNext / HasPrev）
• KeysetCursor：游标编解码器，不透明 Base64Url 令牌，支持 HMAC 签名（KeysetCursor.SigningKey）
• KeysetDirection：Next / Prev 查询方向枚举

修复与增强（2026-08-06）

• KeysetCursor 载荷 JSON 改用源生成器（AOT 友好），签名校验 / JSON / 值解析全流程异常统一包装为 ArgumentException
• KeysetPage 属性收紧为 init

---

7.4.0

2026年8月3日 星期一

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.4.0

• 无功能性变更，仅同步版本号

---

7.3.0

2026年7月30日 星期三

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.3.0

破坏性变更 — 时间类型从 DateTime 改为 DateTimeOffset

• IModel<TKey>.CreatedAt：DateTime → DateTimeOffset
• IUpdatedAt.UpdatedAt：DateTime? → DateTimeOffset?
• IDeletedAt.DeletedAt：DateTime? → DateTimeOffset?
• IDelete<T>.DeletedAt：DateTime? → DateTimeOffset?
• IAuditor<T,U>.AuditedAt：DateTime? → DateTimeOffset?
• ICreatedDate.CreatedDate：DateTime → DateTimeOffset
• ICreatedTime.CreatedTime：DateTime → DateTimeOffset
• IStartTime.StartTime：DateTime? → DateTimeOffset?
• IStartDate.StartDate：DateTime? → DateTimeOffset?
• IEndDate.EndDate：DateTime? → DateTimeOffset?
• IEndTime.EndTime：DateTime? → DateTimeOffset?

其他变更

• IParent<T>：支持可空类型参数（如 IParent<int?>），根节点可使用 null

迁移指南

• 将实体中的 DateTime 属性改为 DateTimeOffset
• DateTime.Now 改为 DateTimeOffset.Now
• 数据库列类型从 datetime2 改为 datetimeoffset

---

7.2.0

2026年7月28日 星期一

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.2.0

新增接口

• IAppConfiguration：应用配置引用接口，提供 IConfiguration 实例，语义比 IDbConfiguration 更准确

重命名（向后兼容）

• IMyConfiguration → IAppConfiguration：旧接口标记 [Obsolete] 并继承新接口
• IDbConfiguration：已删除（上一版本新增，因命名不当移除）

---

7.1.0

2026年7月28日 星期一

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.1.0

新增接口

• IViewObject：视图对象输出接口，替代 IToVo
• IDbConfiguration：数据库配置接口，替代 IMyConfiguration

重命名（向后兼容 — 旧接口标记 [Obsolete]）

• IToVo → IViewObject：旧接口保留并继承新接口，编译时产生 CS0618 警告
• IMyConfiguration → IDbConfiguration：旧接口保留并继承新接口
• IEnabled → IIsEnabled：旧接口标记 [Obsolete]（属性名 Enabled vs IsEnabled 不同，无法继承）
• IDisabled → IIsDisabled：旧接口标记 [Obsolete]

---

7.0.0

2026年7月26日 星期日

与 Crping.EFCore / Crping.EFCore.Controller 同步升至 7.0.0

• 修复：ModelWithName.Name setter 增加 null 防护 — 之前 value.Trim() 在 value 为 null 时会抛 NullReferenceException，现改为 value?.Trim() ?? string.Empty
• 清理：删除 3 个全注释死代码文件（破坏性变更 — 下游若手动引用这些类型会编译失败）
  • Models/GenericConverter.cs
  • Models/UserKey.cs
  • Enums/TaskState.cs
• 内部：DateTime.Now → DateTime.UtcNow 改造（ModelBase.CreatedAt / EFCoreExt.UpdateTo）曾被提交后又完整回退，净状态未变

---

6.4.0

2026年7月16日 星期四

• 优化所有命名空间
• 调整项目目录结构：Crping.EFCore.* 项目统一嵌套到 Crping.EFCore/ 下

---

6.0.0

2025年11月27日 星期四

• 升级为 .net10.0

---

5.5.0

2025年10月21日 星期二

• 新增扩展方法NotDisabled(...), NotIsDisabled(...), OnlyEnabled(...), OnlyIsEnabled(...)

---

5.4.0

2025年9月25日 星期四

• 新增接口IDeletedAt, IAuditor, IAudit

---

5.3.0

2025年7月8日 星期二

• 新增过滤软删除扩展方法NotSoftDeleted

---

5.2.1

2025年6月29日 星期日

• 新增接口IAddress<T>

---

5.2.0

2025年5月22日 星期四

• 新增接口ISoftDelete

---

5.1.0

2025年4月19日 星期六

• 新增接口：IContents<T>，ITitle<T>

---

5.0.0

2024年11月17日 星期日

• 升级为 .net9.0
• 更新引用组件

---

4.5.0

2024年10月19日 星期六

• 接口 IKey<TId>，IModel<TKey> 默认类型改为 string

---

4.3.0

2024年4月12日 星期五

• 新增接口ISortIndex<T>，IIsEnabled

---

4.2.0

2024年4月9日 星期二

• 新增接口IToolkit

---

4.1.0

2024年3月28日 星期四

• 修改：Cascader<TKey>为Cascade<TKey>
• 新增接口：IAccount，IAvatar，IEmail，IIsDisabled，IPhoneNumber

---

4.0.1

2024年3月21日 星期四

• 移除ICreate中TKey的notnull约束

---

4.0.0

2024年1月27日 星期六

• 升级目标框架为.net8.0
• 升级Microsoft.Extensions.Configuration.Abstractions为8.0
• 与系列相关组件对齐版本号

---

3.20.1

2023-08-22

• 接口ICreatedDate，ICreatedTime的日期改为不为空

---

3.20.0

2023-07-24

• 新增接口IUpdatedAt
• 修改接口IUpdate<TUserKey>

---

3.19.0

2023-06-29

• 为所有泛型参数TKey添加约束notnull
• 重命名部分泛型参数
• 新增接口IUpdate<TKey>，IDelete<TKey

---

3.18.0

2023-06-11

• 新增接口IKeysetPagination，以及实现类KeysetPagination
• 新增扩展方法GetValue(...)

---

3.17.0

2023-06-07

• 新增升序扩展方法Ascending(...)
• 新增降序扩展方法Descending(...)

---

3.16.0

2023-05-21

• 新增接口ICreator<TUser, TKey>

---

3.15.0

2023-05-11

• 新增接口IToVo

---

3.14.0

2023-05-10

• IIntro修改为可空
• 修改日期时间相关接口的数据类型为DateTime?
• 新增接口INickname
• 修改接口IUserName为IUsername

---

3.13.0

2023-05-10

• 新增接口：IUpdater<T>，IDeleter<T>，IAddress

---

3.12.0

2023-04-26

• 新增接口：IParent<T>
• 新增实体：Cascader<TKey>

---

3.11.0

2023-04-20

• 新增接口ICreate<T>

---

3.10.0

2023-04-15

• 项目启用可空类型
• 修复启用可空类型后产生警告的代码
• 新增接口ICreator
• 修改接口IConnectionString，IMyConfiguration

---

3.8.0

2023-03-28

• 从Crping.EFCore移入接口IConnectionString,IMyConfiguration

---

3.7.0

2023-02-18

• 新增接口IKeysetPagination与类KeysetPagination

---

3.6.0

2023-02-03

• 将运行时修改为net7.0

---

3.5.1

2023-01-03

• 新增接口：IKey:IKey<int>

---

3.5.0

2023-01-03

• 新增接口IKey<>，并添加到IModel<>
• 新增全局引用Global，并优化所有代码

---

3.4.0

2022-05-18

• 修改 IPagination 和 Pagination 的排序方式字段

---

历史版本

• 3.4.0：修改 IPagination 和 Pagination 的排序方式字段
• 3.3.0：添加IGender，IIntro等一系列常用接口
• 3.2.1：重命名接口ICreatedDate,ICreatedTime，并修改其属性类型
• 3.2.0：添加枚举ProcessingStatus，接口IProcessingStatus
• 3.1.4：优化JsonPropertyOrder值
• 3.1.3：为属性添加JsonPropertyOrder
• 3.1.2：为Name属性添加字段长度限制
• 3.1.1：为属性添加[Column(Order = 0)]等
• 3.1.0：添加ModelBase，IName，ModelWithName等
• 3.0.2：Utils类改为EFCoreEx
• 3.0.1：修改PaginationData，以适应Dapr反序列化
• 3.0.0：目标框架改为.net6.0
• 1.1.3：还原Pagination的部分修改
• 1.1.2：修复Pagination的Bug
• 1.1.1：优化Pagination的CountPages()方法
• 1.1.0：Pagination 添加 QueryString 属性
• 1.0.0：提供 Crping.EFCore 组件所需基础类接口等

2022-04-01

1. 重命名接口ICreatedDate,ICreatedTime，并修改其属性类型
2. 添加一系列常用接口

2022-03-14

1. 添加枚举：ProcessingStatus
2. 添加接口：IProcessingStatus

2022-02-28

1. 添加ModelBase<T>，ModelBase
2. 添加IName, ModelWithName<T>，ModelWithName
3. 为属性添加[Column(Order = 0)]等
4. 为Name属性添加字段长度限制
5. 为属性添加：JsonPropertyOrder
6. 优化Column(Order = 0)，JsonPropertyOrder