Dapper怎么处理DateTimeOffset类型 Dapper时区相关日期映射

Dapper 默认不支持 DateTimeOffset 自动映射，因其依赖的数据库 provider 对该类型支持有限，易导致偏移量丢失或异常；推荐统一使用 UTC DateTime 存储与处理，必要时通过 ITypeHandler 自定义实现。

Dapper 默认不支持 DateTimeOffset 类型的自动映射，这是它和 EF 等全功能 ORM 的关键区别之一。直接查询或参数传入 DateTimeOffset 会报错或返回 null，必须通过自定义方式处理。

为什么 Dapper 不原生支持 DateTimeOffset

Dapper 的底层读取依赖数据库 provider 的 IDataReader 索引器（如 SqliteDataReader 或 SqlDataReader），而多数 provider 对 DateTimeOffset 的支持有限——尤其当数据库字段是 DATETIME 而非 DATETIMEOFFSET 时，值可能被截断、丢失偏移量，甚至抛出 InvalidCastException。

官方明确说明：Dapper 不能处理 DateTimeOffset、Guid 和 TimeSpan 这三类类型，除非你提供 ITypeHandler。

推荐做法：统一用 UTC + DateTime 处理

绝大多数生产系统不需要存储偏移量本身，只需保证时间一致性。最佳实践是：

• 数据库字段使用 DATETIME2（SQL Server）或 TIMESTAMP WITHOUT TIME ZONE（PostgreSQL），只存 UTC 时间
• C# 层统一用 DateTime.UtcNow 写入，用 .ToUniversalTime() 或 .Kind == DateTimeKind.Utc 校验
• 读取后按需转换为本地时间或指定时区：TimeZoneInfo.ConvertTimeFromUtc(dt, tz)
• 避免在业务逻辑中混用 DateTime.Now，防止部署多时区服务器时出现时间漂移

必须用 DateTimeOffset？那就写 TypeHandler

如果你的场景强依赖偏移量（比如日志精确归属、跨时区调度），可以实现一个 ITypeHandle

r：

• 写入时：提取 value.DateTime 存为 DATETIME，同时把 value.Offset 单独存一列（如 offset_minutes INT）
• 读取时：从两列拼回 new DateTimeOffset(dateTime, TimeSpan.FromMinutes(offset))
• 或者数据库用 DATETIMEOFFSET 字段，handler 中调用 parameter.Value = value;（SQL Server provider 支持该类型直传）

注册方式：SqlMapper.AddTypeHandler(new DateTimeOffsetHandler());，建议在应用启动时全局注册一次。

动态参数和查询中的常见坑

用 DynamicParameters 传 DateTimeOffset 时，Dapper 会尝试隐式转成 DateTime，但丢掉偏移量：

• 错误写法：args.Add("@when", dto); → 可能变成本地时间或 UTC，不可控
• 安全写法：args.Add("@when", dto.UtcDateTime); args.Add("@offset", dto.Offset.TotalMinutes);
• 查询返回时，不要指望 Query() 自动工作；改用 Query() 后手动构造

基本上就这些。核心不是“怎么让 Dapper 支持 DateTimeOffset”，而是“要不要真需要它”——多数时候，用好 DateTime + UTC + 显式时区转换，更轻、更稳、更易维护。