Dapper - a simple object mapper for .Net

Release Notes

Located at https://github.com/DapperLib/Dapper/releases

Packages

MyGet Pre-release feed: https://www.myget.org/gallery/dapper

| Package | NuGet Stable | NuGet Pre-release | Downloads | MyGet | | ------- | ------------ | ----------------- | --------- | ----- | | Dapper | | | | | | Dapper.EntityFramework | | | | | | Dapper.EntityFramework.StrongName | | | | | | Dapper.Rainbow | | | | | | Dapper.SqlBuilder | | | | | | Dapper.StrongName | | | | |

Package Purposes:

• Dapper
  • The core library
• Dapper.EntityFramework
  • Extension handlers for EntityFramework
• Dapper.EntityFramework.StrongName
  • Extension handlers for EntityFramework
• Dapper.Rainbow
  • Micro-ORM implemented on Dapper, provides CRUD helpers (readme)
• Dapper.SqlBuilder
  • Component for building SQL queries dynamically and composably

Sponsors

Dapper was originally developed for and by Stack Overflow, but is F/OSS. Sponsorship is welcome and invited - see the sponsor link at the top of the page. A huge thanks to everyone (individuals or organisations) who have sponsored Dapper, but a massive thanks in particular to:

• Dapper Plus is a major sponsor and is proud to contribute to the development of Dapper (read more)
• AWS who sponsored Dapper from Oct 2023 via the .NET on AWS Open Source Software Fund

<a href="https://dapper-plus.net/"><img width="728" height="90" alt="Dapper Plus logo" src="https://raw.githubusercontent.com/DapperLib/Dapper/main/docs/dapper-sponsor.png" /></a>

Features

Dapper is a NuGet library that you can add in to your project that will enhance your ADO.NET connections via extension methods on your DbConnection instance. This provides a simple and efficient API for invoking SQL, with support for both synchronous and asynchronous data access, and allows both buffered and non-buffered queries.

It provides multiple helpers, but the key APIs are:

// insert/update/delete etc
var count  = connection.Execute(sql [, args]);

// multi-row query
IEnumerable<T> rows = connection.Query<T>(sql [, args]);

// single-row query ({Single|First}[OrDefault])
T row = connection.QuerySingle<T>(sql [, args]);

where args can be (among other things):

• a simple POCO (including anonyomous types) for named parameters
• a Dictionary<string,object>
• a DynamicParameters instance

Execute a query and map it to a list of typed objects

public class Dog
{
    public int? Age { get; set; }
    public Guid Id { get; set; }
    public string Name { get; set; }
    public float? Weight { get; set; }

    public int IgnoredProperty { get { return 1; } }
}

var guid = Guid.NewGuid();
var dog = connection.Query<Dog>("select Age = @Age, Id = @Id", new { Age = (int?)null, Id = guid });

Assert.Equal(1,dog.Count());
Assert.Null(dog.First().Age);
Assert.Equal(guid, dog.First().Id);

Execute a query and map it to a list of dynamic objects

This method will execute SQL and return a dynamic list.

Example usage:

var rows = connection.Query("select 1 A, 2 B union all select 3, 4").AsList();

Assert.Equal(1, (int)rows[0].A);
Assert.Equal(2, (int)rows[0].B);
Assert.Equal(3, (int)rows[1].A);
Assert.Equal(4, (int)rows[1].B);

Execute a Command that returns no results

Example usage:

var count = connection.Execute(@"
  set nocount on
  create table #t(i int)
  set nocount off
  insert #t
  select @a a union all select @b
  set nocount on
  drop table #t", new {a=1, b=2 });
Assert.Equal(2, count);

Execute a Command multiple times

The same signature also allows you to conveniently and efficiently execute a command multiple times (for example to bulk-load data)

Example usage:

var count = connection.Execute(@"insert MyTable(colA, colB) values (@a, @b)",
    new[] { new { a=1, b=1 }, new { a=2, b=2 }, new { a=3, b=3 } }
  );
Assert.Equal(3, count); // 3 rows inserted: "1,1", "2,2" and "3,3"

Another example usage when you already have an existing collection:

var foos = new List<Foo>
{
    { new Foo { A = 1, B = 1 } }
    { new Foo { A = 2, B = 2 } }
    { new Foo { A = 3, B = 3 } }
};

var count = connection.Execute(@"insert MyTable(colA, colB) values (@a, @b)", foos);
Assert.Equal(foos.Count, count);

This works for any parameter that implements IEnumerable<T> for some T.

Performance

A key feature of Dapper is performance. The following metrics show how long it takes to execute a SELECT statement against a DB (in various config, each labeled) and map the data returned to objects.

The benchmarks can be found in Dapper.Tests.Performance (contributions welcome!) and can be run via:

dotnet run --project .\benchmarks\Dapper.Tests.Performance\ -c Release -f net8.0 -- -f * --join

Output from the latest run is:

BenchmarkDotNet v0.13.7, Windows 10 (10.0.19045.3693/22H2/2022Update)
Intel Core i7-3630QM CPU 2.40GHz (Ivy Bridge), 1 CPU, 8 logical and 4 physical cores
.NET SDK 8.0.100
  [Host]   : .NET 8.0.0 (8.0.23.53103), X64 RyuJIT AVX
  ShortRun : .NET 8.0.0 (8.0.23.53103), X64 RyuJIT AVX

| ORM | Method | Return | Mean | StdDev | Error | Gen0 | Gen1 | Gen2 | Allocated | |-------------------- |------------------------------- |------------- |----------:|----------:|----------:|--------:|-------:|-------:|----------:| | Dapper cache impact | ExecuteParameters_Cache | Void | 96.75 us | 0.668 us | 1.010 us | 0.6250 | - |