Dora.Dapper.SqlServer 1.0.1

Dora.Dapper

Dora.Dapper 是对 Dapper 的轻量二次封装。

它不替代 Dapper，也不隐藏 SQL。它只负责把工程项目里常见的连接管理、事务管理、多数据库适配、DI 注册和简单 CRUD 做薄薄一层封装。

设计定位

Dora.Dapper 适合做这些事：

• 统一管理多个数据库连接
• 按需引入 MySQL、SQL Server、Oracle 驱动
• 按连接 key 创建数据库连接
• 自动释放连接
• 简化同步、异步、事务代码
• 提供基于 Dapper.Contrib 的简单 Repository
• 保留 Dapper 原生 SQL 的灵活性

Dora.Dapper 不做这些事：

• 不隐藏 SQL
• 不做复杂 LINQ Provider
• 不生成复杂查询
• 不替代 EF Core

一句话：Dora.Dapper 是 Dapper 的工程化外壳，不是 Dapper 的替代品。

包结构

推荐按数据库类型按需引用包。

MySQL 项目：

<PackageReference Include="Dora.Dapper.Core" Version="1.0.6" />
<PackageReference Include="Dora.Dapper.MySql" Version="1.0.6" />

SQL Server 项目：

<PackageReference Include="Dora.Dapper.Core" Version="1.0.6" />
<PackageReference Include="Dora.Dapper.SqlServer" Version="1.0.6" />

Oracle 项目：

<PackageReference Include="Dora.Dapper.Core" Version="1.0.6" />
<PackageReference Include="Dora.Dapper.Oracle" Version="1.0.6" />

想一次性包含三种驱动时：

<PackageReference Include="Dora.Dapper" Version="1.0.6" />

ProviderName

ProviderName 只用于把连接配置绑定到具体数据库驱动。业务代码创建连接时使用的是连接 key，例如 db1、main、report。

实体特性

简单 CRUD 基于 Dapper.Contrib。

using Dapper.Contrib.Extensions;

[Table("Student")]
public class Student
{
    [Key]
    public int StudentId { get; set; }

    public int? ClassesId { get; set; }

    public string Name { get; set; }

    [Write(false)]
    public Classes MyClasses { get; set; }
}

常用特性：

直接创建 DoraDb

小项目或控制台程序可以直接创建 DoraDb。

默认读取配置文件

先在程序输出目录准备配置文件：

AppContext.BaseDirectory/config/db.json

示例配置：

{
  "DefaultConnection": "main",
  "Connections": {
    "main": {
      "ProviderName": "mysql",
      "ConnectionString": "Server=127.0.0.1;Database=test;Uid=root;Pwd=123456;",
      "CommandTimeout": 30
    }
  }
}

代码中注册对应 Provider，然后直接创建默认数据库访问对象：

using Dora.Dapper;

DoraDapperMySql.Register();

var db = DoraDb.CreateDefault();

指定配置文件路径：

var db = DoraDb.CreateFromFile("config/my-db.json");

代码创建配置

如果不想走配置文件，也可以直接传入 DoraDapperOptions。

using Dora.Dapper;

DoraDapperMySql.Register();

var db = new DoraDb(new DoraDapperOptions
{
    DefaultConnection = "main"
}.AddConnection(
    name: "main",
    providerName: "mysql",
    connectionString: "Server=127.0.0.1;Database=test;Uid=root;Pwd=123456;",
    commandTimeout: 30));

查询数据：

var student = await db.QueryFirstOrDefaultAsync<Student>(
    "select * from Student where StudentId = @id",
    new { id = 1 });

执行命令：

var rows = await db.ExecuteAsync(
    "update Student set Name = @name where StudentId = @id",
    new { id = 1, name = "张三" });

指定连接 key：

var reports = await db.QueryAsync<Report>(
    "select * from ReportDaily",
    connectionName: "report");

配置文件：SQL Server + MySQL

如果一个项目里需要同时访问两种数据库，可以把两个连接都写进默认配置文件：

AppContext.BaseDirectory/config/db.json

{
  "DefaultConnection": "mssql_main",
  "Connections": {
    "mssql_main": {
      "ProviderName": "mssql",
      "ConnectionString": "Server=.;Database=DemoDb;User Id=sa;Password=123456;TrustServerCertificate=True;",
      "CommandTimeout": 30
    },
    "mysql_main": {
      "ProviderName": "mysql",
      "ConnectionString": "Server=127.0.0.1;Port=3306;Database=demo_db;Uid=root;Pwd=123456;",
      "CommandTimeout": 30
    }
  }
}

直接创建 DoraDb 时，先注册需要用到的数据库 Provider，然后读取默认配置：

using Dora.Dapper;

DoraDapperSqlServer.Register();
DoraDapperMySql.Register();

var db = DoraDb.CreateDefault();

var sqlServerStudents = await db.QueryAsync<Student>(
    "select * from Student",
    connectionName: "mssql_main");

var mysqlStudents = await db.QueryAsync<Student>(
    "select * from student",
    connectionName: "mysql_main");

如果配置文件不在默认位置，也可以指定路径：

var db = DoraDb.CreateFromFile("config/my-db.json");

在 DI 项目里，AddDoraDapper() 默认也是读取 config/db.json：

services.AddDoraDapper()
    .AddSqlServer()
    .AddMySql();

DI 用法

正式项目推荐使用依赖注入。

默认读取配置文件

AddDoraDapper() 不传参数时，会默认读取程序输出目录下的 config/db.json：

AppContext.BaseDirectory/config/db.json

示例配置，包含 SQL Server 和 MySQL 两个连接：

{
  "DefaultConnection": "mssql_main",
  "Connections": {
    "mssql_main": {
      "ProviderName": "mssql",
      "ConnectionString": "Server=.;Database=DemoDb;User Id=sa;Password=123456;TrustServerCertificate=True;",
      "CommandTimeout": 30
    },
    "mysql_main": {
      "ProviderName": "mysql",
      "ConnectionString": "Server=127.0.0.1;Port=3306;Database=demo_db;Uid=root;Pwd=123456;",
      "CommandTimeout": 30
    }
  }
}

服务注册：

using Dora.Dapper;

services.AddDoraDapper()
    .AddSqlServer()
    .AddMySql();

使用指定配置文件路径：

services.AddDoraDapper("config/my-db.json")
    .AddSqlServer()
    .AddMySql();

代码配置

如果不想走配置文件，也可以直接用代码配置。

MySQL 示例：

services.AddDoraDapper(options =>
{
    options.DefaultConnection = "main";
    options.AddConnection("main", "mysql", "Server=127.0.0.1;Database=test;Uid=root;Pwd=123456;");
}).AddMySql();

SQL Server 示例：

services.AddDoraDapper(options =>
{
    options.DefaultConnection = "main";
    options.AddConnection("main", "mssql", "Server=.;Database=test;User Id=sa;Password=123456;TrustServerCertificate=True;");
}).AddSqlServer();

Oracle 示例：

services.AddDoraDapper(options =>
{
    options.DefaultConnection = "main";
    options.AddConnection("main", "oracle", "Data Source=127.0.0.1:1521/XE;User Id=test;Password=123456;");
}).AddOracle();

注入 IDoraDb

using Dora.Dapper;

public class StudentService
{
    private readonly IDoraDb _db;

    public StudentService(IDoraDb db)
    {
        _db = db;
    }

    public Task<Student?> GetFromDefaultAsync(int id)
    {
        return _db.QueryFirstOrDefaultAsync<Student>(
            "select * from Student where StudentId = @id",
            new { id });
    }

    public Task<IEnumerable<Student>> GetFromSqlServerAsync()
    {
        return _db.QueryAsync<Student>(
            "select * from Student",
            connectionName: "mssql_main");
    }

    public Task<IEnumerable<Student>> GetFromMySqlAsync()
    {
        return _db.QueryAsync<Student>(
            "select * from student",
            connectionName: "mysql_main");
    }
}

事务

同步事务：

var result = db.Transaction((conn, tran) =>
{
    conn.Execute("insert into Classes(Name) values(@Name)", new { Name = "一班" }, tran);
    conn.Execute("insert into Student(Name, ClassesId) values(@Name, @ClassesId)", new { Name = "张三", ClassesId = 1 }, tran);

    return true;
});

异步事务：

var result = await db.TransactionAsync(async (conn, tran) =>
{
    await conn.ExecuteAsync("insert into Classes(Name) values(@Name)", new { Name = "一班" }, tran);
    await conn.ExecuteAsync("insert into Student(Name, ClassesId) values(@Name, @ClassesId)", new { Name = "张三", ClassesId = 1 }, tran);

    return true;
});

事务方法会在成功时自动提交，异常时自动回滚。

Repository 用法

IRepository<T> 是基于 Dapper.Contrib 的简单 CRUD 封装，适合实体主键和表名映射比较标准的场景。

using Dora.Dapper;

public class StudentService
{
    private readonly IRepository<Student> _repository;

    public StudentService(IRepository<Student> repository)
    {
        _repository = repository;
    }

    public Task<Student> GetAsync(int id)
    {
        return _repository.GetAsync(id);
    }

    public Task<long> InsertAsync(Student student)
    {
        return _repository.InsertAsync(student);
    }

    public Task<bool> UpdateAsync(Student student)
    {
        return _repository.UpdateAsync(student);
    }

    public Task<bool> DeleteAsync(Student student)
    {
        return _repository.DeleteAsync(student);
    }
}

复杂查询建议直接使用 IDoraDb 写 SQL，不建议把 Repository 封装成复杂查询构造器。

配置结构

推荐配置结构：

{
  "DefaultConnection": "main",
  "Connections": {
    "main": {
      "ProviderName": "mysql",
      "ConnectionString": "Server=127.0.0.1;Database=test;Uid=root;Pwd=123456;",
      "CommandTimeout": 30
    },
    "report": {
      "ProviderName": "mssql",
      "ConnectionString": "Server=.;Database=report;User Id=sa;Password=123456;TrustServerCertificate=True;"
    }
  }
}

连接 key 是 main、report，业务代码通过 key 选择连接。ProviderName 只用于绑定数据库驱动。

不要把真实生产数据库密码提交到 Git 仓库。建议使用环境变量、用户密钥、配置中心或部署系统注入连接字符串。

原生 Dapper 能力

Dora.Dapper 不限制 Dapper 原生能力。

IN 查询：

var sql = "select * from Student where StudentId in @ids";

var students = await db.QueryAsync<Student>(sql, new { ids = new[] { 1, 2, 3 } });

多结果集：

var result = await db.ExecuteAsync(async conn =>
{
    using var multi = await conn.QueryMultipleAsync(@"
        select * from Classes;
        select * from Student;
    ");

    var classes = multi.Read<Classes>().ToList();
    var students = multi.Read<Student>().ToList();

    return new { classes, students };
});

批量执行：

var list = new[]
{
    new { StudentId = 1, Name = "张三" },
    new { StudentId = 2, Name = "李四" }
};

var rows = await db.ExecuteAsync(
    "update Student set Name = @Name where StudentId = @StudentId",
    list);

构建

dotnet build Dapper.sln

当前解决方案包含：

• Dora.Dapper.Core
• Dora.Dapper.MySql
• Dora.Dapper.SqlServer
• Dora.Dapper.Oracle
• Dora.Dapper 聚合包
• DapperTest 示例项目