.NET 开源 ORM FreeSql 使用教程

什么是 FreeSql？

FreeSql 是一个高性能、灵活且易用的 .NET 开源 ORM（对象关系映射工具），提供数据库操作的强大功能，包括实体类映射、链式查询、表达式树支持、数据库迁移等。它可以帮助开发者快速、高效地操作数据库，支持多种数据库系统。

FreeSql 的目标是简化开发流程，减少重复代码，提升开发效率。相比于传统 ORM（如 EF Core 和 Dapper），FreeSql 提供了更丰富的功能，尤其是在 查询链式调用 和 支持多数据库类型 方面。

FreeSql GitHub地址：https://github.com/dotnetcore/FreeSql

FreeSql 主要特性

多数据库支持：

FreeSql 支持多种主流数据库，包括：

丰富的功能：

高性能：

直接生成高效 SQL，减少性能损耗。

在复杂查询场景下的表现优于一些传统 ORM。

代码生成器：

支持通过工具快速生成数据库对应的实体类，减少手动映射的工作量。

FreeSql 的安装

通过 NuGet 安装 FreeSql 的基础包和数据库适配包。例如：

dotnet add package FreeSql
dotnet add package FreeSql.Provider.SqlServer

如果需要使用依赖注入功能，可以安装FreeSql.DependencyInjection包：

dotnet add package FreeSql.DependencyInjection

FreeSql 使用示例

1. 初始化 FreeSql

在项目中使用 FreeSql 时，通常需要先创建 FreeSql 的实例。以下是通过代码方式初始化的例子：

using FreeSql;

var freeSql = new FreeSqlBuilder()
    .UseConnectionString(DataType.SqlServer, "Server=localhost;Database=testdb;User Id=sa;Password=your_password;")
    .UseAutoSyncStructure(true) // 自动迁移数据库表结构
    .Build();

2. 定义实体类

定义一个与数据库表对应的实体类：

public class User
{
    [Column(IsIdentity = true, IsPrimary = true)] // 主键、自增
    public int Id { get; set; }
    
    public string Name { get; set; }
    
    public int Age { get; set; }
    
    public DateTime CreatedTime { get; set; }
}

3. 插入数据

var user = new User { Name = "张三", Age = 25, CreatedTime = DateTime.Now };
var id = freeSql.Insert(user).ExecuteIdentity(); // 返回自增主键的值
Console.WriteLine($"插入成功，生成的 ID 为：{id}");

4. 查询数据

链式查询 是 FreeSql 的亮点，以下是常见的查询用法：

// 查询单条数据
var user = freeSql.Select<User>()
    .Where(u => u.Id == 1)
    .First();

// 查询多条数据
var users = freeSql.Select<User>()
    .Where(u => u.Age > 18)
    .OrderBy(u => u.CreatedTime)
    .ToList();

Console.WriteLine($"共找到 {users.Count} 条数据");

5. 更新数据

freeSql.Update<User>()
    .Set(u => u.Name, "李四")
    .Where(u => u.Id == 1)
    .ExecuteAffrows(); // 返回受影响的行数

6. 删除数据

freeSql.Delete<User>()
    .Where(u => u.Id == 1)
    .ExecuteAffrows();

7. 自动同步数据库表结构

通过 UseAutoSyncStructure(true) 配置，FreeSql 会根据实体类自动同步数据库的表结构。你也可以手动调用：

freeSql.CodeFirst.SyncStructure<User>();

8. 使用依赖注入

如果项目基于 ASP.NET Core，可以通过依赖注入的方式使用 FreeSql。

在 Startup.cs 中配置：

public void ConfigureServices(IServiceCollection services)
{
    services.AddFreeSql(builder => builder
        .UseConnectionString(DataType.SqlServer, "Server=localhost;Database=testdb;User Id=sa;Password=your_password;")
        .UseAutoSyncStructure(true)
    );
}

在控制器中使用：

public class UserController : ControllerBase
{
    private readonly IFreeSql _freeSql;

    public UserController(IFreeSql freeSql)
    {
        _freeSql = freeSql;
    }

    [HttpGet("users")]
    public IActionResult GetUsers()
    {
        var users = _freeSql.Select<User>().ToList();
        return Ok(users);
    }
}

FreeSql 的优势

链式查询简洁，功能丰富，语法易于理解。

多数据库支持，可以轻松切换数据库适配器。

支持企业级功能，如多租户、软删除、分表分库。

社区活跃，文档完善。

适用场景

适合中小型项目，尤其是需要操作多个数据库的应用。

对性能有较高要求的场景（如复杂查询或批量操作）。

喜欢链式查询语法的开发者。

FreeSql 是一个优秀的 .NET ORM 工具，其灵活性和高效性能让它成为开发者的一个强大选择。