Dapper.FluentMap是什么 Dapper.FluentMap流畅映射配置教程

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Dapper.FluentMap是什么 Dapper.FluentMap流畅映射配置教程

2025-12-14

浏览次数：次

返回列表

Dapper.FluentMap 是一个为 Dapper 设计的轻量级编译期映射配置库，通过 Fluent API 在启动时注册列名映射规则，解决数据库下划线命名、字段前缀/后缀、审计字段忽略及统一约定等场景，需在首次查询前完成 Initialize 初始化。

dapper.fluentmap是什么 dapper.fluentmap流畅映射配置教程

Dapper.FluentMap 是什么

Dapper.FluentMap 是一个为 Dapper 设计的轻量级映射配置扩展库，用于解决“数据库列名与 C# 属性名不一致”时的手动映射问题。它不改变 Dapper 的核心行为，也不引入运行时反射开销，而是通过编译期友好的 Fluent API，在应用启动时一次性注册映射规则，让 Dapper 知道“哪个属性对应哪一列”或“哪些属性该忽略”。

它特别适合这些场景： - 数据库用下划线命名（user_name）而实体用 PascalCase（UserName） - 表字段含前缀（如 tbl_user_id）或后缀（如 created_dt） - 某些字段纯属审计列（updated_by, is_deleted），不想映射进实体 - 需要统一约定（比如所有 Id 属性都映射到 autID）而不逐个写 SQL 别名

基础映射配置步骤

以 User 实体为例，假设数据库表字段是 usr_id、usr_name、usr_email，而 C# 类是：

public class User { public int Id { get; set; } public string Name { get; set; } public string Email { get; set; } }

你需要：

创建映射类，继承 EntityMap<user></user>
在构造函数中用 Map() 显式指定列名，或用 Ignore() 跳过字段
在程序启动时（如 Program.cs 或 Startup.ConfigureServices）调用 FluentMapper.Initialize() 注册

示例代码：

public class UserMap : EntityMap
{
  public UserMap()
  {
    Map(x => x.Id).ToColumn("usr_id");
    Map(x => x.Name).ToColumn("usr_name");
    Map(x => x.Email).ToColumn("usr_email");
  }
}

FluentMapper.Initialize(config =>
{
config.AddMap(new UserMap());
});

忽略字段和约定式映射

如果实体里有不对应数据库列的属性（比如 FullName 计算属性），必须显式忽略，否则 Dapper 可能报错或静默跳过：

Map(x => x.FullName).Ignore();

若多个实体都有类似规则（例如所有 Id 属性都映射到带前缀的列），可用 约定（Convention） 统一处理：

新建类继承 Convention
用 Properties<t>().Where(...)</t> 定位目标属性
调用 Configure(c => c.HasColumnName(...)) 设置列名
在 Initialize 中用 AddConvention<yourconvention>()</yourconvention> 加载

这样比每个实体写一遍 Map 更干净，也更易维护。

注意事项和常见坑

配置生效的前提是：必须在任何 Dapper 查询执行前完成初始化。常见错误包括：

映射类没在 Initialize 中注册——查询时仍按默认规则（属性名=列名）匹配
忽略语句写错位置（比如放在 Map 外部）——Ignore() 必须链在 Map(x => ...) 后面
使用了 Dapper.Contrib 的 CRUD 方法（如 GetAsync）但没配 Key 或 Table 特性——FluentMap 不影响 Contrib 的特性解析，二者需配合使用
多线程环境下提前触发了 Dapper 查询——确保 FluentMapper.Initialize 在主线程或 DI 容器构建完成后再执行