Nanorm.Npgsql 0.1.2

Nanorm

一个用于 ADO.NET 的微型数据访问辅助库。适用于剪裁和原生 AOT。

它支持

• PostgreSQL 通过 Npgsql
• SQLite 通过 Microsoft.Data.SQLite
• 任何 ADO.NET 数据提供程序通过 System.Data.Common

如何使用

Nanorm 支持 .NET 6+，并针对 .NET 7+ 提供特殊支持，这得益于接口上的静态虚拟成员 和源生成器。

入门

1. 安装适合您所使用的 ADO.NET 提供程序（即数据库）的 Nanorm 包。使用项目目录中的 dotnet 命令行

   • PostgreSQL

     dotnet add package Nanorm.Npgsql --prerelease
     

   • SQLite

     dotnet add package Nanorm.Sqlite --prerelease
     

   • 所有其他 ADO.NET 提供程序

     dotnet add package Nanorm --prerelease
     

2. 创建一个用于将数据库查询结果映射的 class、record 或 struct。如果你正在使用 .NET 7 或 .NET 8，你可以将其定义为 partial 并使用 [DataRecordMapper] 属性对其进行装饰来启用源生成器，该生成器会自动为你实现 IDataRecordMapper<T> 接口。

   [DataRecordMapper]
   public partial class Todo
   {
       public int Id { get; set; }
   
       public required string Title { get; set; }
   
       public bool IsComplete { get; set; }
   }
   
   // Generated for you if .NET 7+, otherwise you'll need to write it yourself
   partial class Todo : IDataRecordMapper<Todo>
   {
       public static Todo Map(System.Data.IDataRecord dataRecord) =>
           new()
           {
               Id = dataRecord.GetInt32("Id"),
               Title = dataRecord.GetString("Title"),
               IsComplete = dataRecord.GetBoolean("IsComplete"),
           };
   }
   

3. 创建一个适当的 IDbConnection 类型的实例，并使用 Nanorm 的一些扩展方法来执行查询。`QueryAsync` 方法返回 IAsyncEnumerable，因此你可以使用 await foreach 来迭代结果，或者简单调用 ToListAsync() 来异步获取 List<T> 结果。

   // Using Npgsql to query a local PostgreSQL instance
   var connectionString = "Server=localhost;Port=5432;Username=postgres;Database=postgres";
   await using var db = new NpgsqlDataSourceBuilder(connectionString).Build();
   
   var todos = db.QueryAsync<Todo>("SELECT * FROM Todos");
   var todosList = await todos.ToListAsync();
   
   if (todosList.Count == 0)
   {
       Console.WriteLine("There are currently no todos!");
   }
   else
   {
       Console.WriteLine($"Found {todosList.Count} todo(s):");
       foreach (var todo in todosList)
       {
           Console.WriteLine($"({todo.Id}) {todo.Title}");
       }
   }
   

使用参数

Nanorm 支持多种方式传递参数到查询中。

• 传递一个由 Nanorm 的自定义字符串插值处理程序处理的插值字符串。这是首选方法。查询会自动以最佳方式参数化，即没有字符串连接，使用池分配等。

  var title = "Do the dishes";
  var result = db.QueryAsync<Todo>($"SELECT * FROM Todos WHERE Title = {title}")
  

• 传递 ADO.NET 提供商的 DbParameter 实现的实例作为参数，例如：

  var title = "Do the dishes";
  var sql = "SELECT * FROM Todos WHERE Title = $1";
  var result = db.QueryAsync<Todo>(sql, new NpgsqlParameter { Value =  title }))
  

• 传递一个回调来修改 ADO.NET 提供商的参数集合实现，例如：

  var title = "Do the dishes";
  var sql = "SELECT * FROM Todos WHERE Title = $1";
  var result = db.QueryAsync<Todo>(sql, parameters => parameters.Add(title))
  

扩展方法

以下扩展方法使与数据库交互变得更加容易。

基准测试

Nanorm 旨在作为一种非常薄的 ADO.NET 层次，支持修剪和本地 AOT。以下是它与原始 ADO.NET 和 Dapper 在简单的插入 & return 操作中的性能比较，包括执行时间和内存分配。