Dapper Documentation

File: Readme.md Copy Chapter

Dapper - a simple object mapper for .Net

Release Notes Copy Chapter

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

Packages Copy Chapter

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

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 Copy Chapter

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

Features Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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

Feel free to submit patches that include other ORMs - when running benchmarks, be sure to compile in Release and not attach a debugger (Ctrl+F5).

Alternatively, you might prefer Frans Bouma's RawDataAccessBencher test suite or OrmBenchmark.

Parameterized queries Copy Chapter

Parameters are usually passed in as anonymous classes. This allows you to name your parameters easily and gives you the ability to simply cut-and-paste SQL snippets and run them in your db platform's Query analyzer.

new {A = 1, B = "b"} // A will be mapped to the param @A, B to the param @B

Parameters can also be built up dynamically using the DynamicParameters class. This allows for building a dynamic SQL statement while still using parameters for safety and performance.

var sqlPredicates = new List<string>();
    var queryParams = new DynamicParameters();
    if (boolExpression)
    {
        sqlPredicates.Add("column1 = @param1");
        queryParams.Add("param1", dynamicValue1, System.Data.DbType.Guid);
    } else {
        sqlPredicates.Add("column2 = @param2");
        queryParams.Add("param2", dynamicValue2, System.Data.DbType.String);
    }

DynamicParameters also supports copying multiple parameters from existing objects of different types.

var queryParams = new DynamicParameters(objectOfType1);
    queryParams.AddDynamicParams(objectOfType2);

When an object that implements the IDynamicParameters interface passed into Execute or Query functions, parameter values will be extracted via this interface. Obviously, the most likely object class to use for this purpose would be the built-in DynamicParameters class.

List Support Copy Chapter

Dapper allows you to pass in IEnumerable and will automatically parameterize your query.

For example:

connection.Query("select * from (select 1 as Id union all select 2 union all select 3) as X where Id in @Ids", new { Ids = new int[] { 1, 2, 3 } });

Will be translated to:

select * from (select 1 as Id union all select 2 union all select 3) as X where Id in (@Ids1, @Ids2, @Ids3)" // @Ids1 = 1 , @Ids2 = 2 , @Ids2 = 3

Literal replacements Copy Chapter

Dapper supports literal replacements for bool and numeric types.

connection.Query("select * from User where UserTypeId = {=Admin}", new { UserTypeId.Admin });

The literal replacement is not sent as a parameter; this allows better plans and filtered index usage but should usually be used sparingly and after testing. This feature is particularly useful when the value being injected
is actually a fixed value (for example, a fixed "category id", "status code" or "region" that is specific to the query). For live data where you are considering literals, you might also want to consider and test provider-specific query hints like OPTIMIZE FOR UNKNOWN with regular parameters.

Buffered vs Unbuffered readers Copy Chapter

Dapper's default behavior is to execute your SQL and buffer the entire reader on return. This is ideal in most cases as it minimizes shared locks in the db and cuts down on db network time.

However when executing huge queries you may need to minimize memory footprint and only load objects as needed. To do so pass, buffered: false into the Query method.

Multi Mapping Copy Chapter

Dapper allows you to map a single row to multiple objects. This is a key feature if you want to avoid extraneous querying and eager load associations.

Example:

Consider 2 classes: Post and User

class Post
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public User Owner { get; set; }
}

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

Now let us say that we want to map a query that joins both the posts and the users table. Until now if we needed to combine the result of 2 queries, we'd need a new object to express it but it makes more sense in this case to put the User object inside the Post object.

This is the use case for multi mapping. You tell dapper that the query returns a Post and a User object and then give it a function describing what you want to do with each of the rows containing both a Post and a User object. In our case, we want to take the user object and put it inside the post object. So we write the function:

(post, user) => { post.Owner = user; return post; }

The 3 type arguments to the Query method specify what objects dapper should use to deserialize the row and what is going to be returned. We're going to interpret both rows as a combination of Post and User and we're returning back a Post object. Hence the type declaration becomes

Everything put together, looks like this:

var sql =
@"select * from #Posts p
left join #Users u on u.Id = p.OwnerId
Order by p.Id";

var data = connection.Query(sql, (post, user) => { post.Owner = user; return post;});
var post = data.First();

Assert.Equal("Sams Post1", post.Content);
Assert.Equal(1, post.Id);
Assert.Equal("Sam", post.Owner.Name);
Assert.Equal(99, post.Owner.Id);

Dapper is able to split the returned row by making an assumption that your Id columns are named Id or id. If your primary key is different or you would like to split the row at a point other than Id, use the optional splitOn parameter.

Multiple Results Copy Chapter

Dapper allows you to process multiple result grids in a single query.

Example:

var sql =
@"
select * from Customers where CustomerId = @id
select * from Orders where CustomerId = @id
select * from Returns where CustomerId = @id";

using (var multi = connection.QueryMultiple(sql, new {id=selectedId}))
{
   var customer = multi.Read<Customer>().Single();
   var orders = multi.Read<Order>().ToList();
   var returns = multi.Read<Return>().ToList();
   ...
}

Stored Procedures Copy Chapter

Dapper fully supports stored procs:

var user = cnn.Query("spGetUser", new {Id = 1},
        commandType: CommandType.StoredProcedure).SingleOrDefault();

If you want something more fancy, you can do:

var p = new DynamicParameters();
p.Add("@a", 11);
p.Add("@b", dbType: DbType.Int32, direction: ParameterDirection.Output);
p.Add("@c", dbType: DbType.Int32, direction: ParameterDirection.ReturnValue);

cnn.Execute("spMagicProc", p, commandType: CommandType.StoredProcedure);

int b = p.Get("@b");
int c = p.Get("@c");

Ansi Strings and varchar Copy Chapter

Dapper supports varchar params, if you are executing a where clause on a varchar column using a param be sure to pass it in this way:

Query("select * from Thing where Name = @Name", new {Name = new DbString { Value = "abcde", IsFixedLength = true, Length = 10, IsAnsi = true }});

On SQL Server it is crucial to use the unicode when querying unicode and ANSI when querying non unicode.

Type Switching Per Row Copy Chapter

Usually you'll want to treat all rows from a given table as the same data type. However, there are some circumstances where it's useful to be able to parse different rows as different data types. This is where IDataReader.GetRowParser comes in handy.

Imagine you have a database table named "Shapes" with the columns: Id, Type, and Data, and you want to parse its rows into Circle, Square, or Triangle objects based on the value of the Type column.

var shapes = new List();
using (var reader = connection.ExecuteReader("select * from Shapes"))
{
    // Generate a row parser for each type you expect.
    // The generic type  is what the parser will return.
    // The argument (typeof(*)) is the concrete type to parse.
    var circleParser = reader.GetRowParser(typeof(Circle));
    var squareParser = reader.GetRowParser(typeof(Square));
    var triangleParser = reader.GetRowParser(typeof(Triangle));

    var typeColumnIndex = reader.GetOrdinal("Type");

    while (reader.Read())
    {
        IShape shape;
        var type = (ShapeType)reader.GetInt32(typeColumnIndex);
        switch (type)
        {
            case ShapeType.Circle:
            	shape = circleParser(reader);
            	break;
            case ShapeType.Square:
            	shape = squareParser(reader);
            	break;
            case ShapeType.Triangle:
            	shape = triangleParser(reader);
            	break;
            default:
            	throw new NotImplementedException();
        }

      	shapes.Add(shape);
    }
}

User Defined Variables in MySQL/MariaDB Copy Chapter

In order to use Non-parameter SQL variables with MySql Connector, you have to add the following option to your connection string:

Allow User Variables=True

Make sure you don't provide Dapper with a property to map.

Limitations and caveats Copy Chapter

Dapper caches information about every query it runs, this allows it to materialize objects quickly and process parameters quickly. The current implementation caches this information in a ConcurrentDictionary object. Statements that are only used once are routinely flushed from this cache. Still, if you are generating SQL strings on the fly without using parameters it is possible you may hit memory issues.

Dapper's simplicity means that many features that ORMs ship with are stripped out. It worries about the 95% scenario, and gives you the tools you need most of the time. It doesn't attempt to solve every problem.

Will Dapper work with my DB provider? Copy Chapter

Dapper has no DB specific implementation details, it works across all .NET ADO providers including SQLite, SQL CE, Firebird, Oracle, MariaDB, MySQL, PostgreSQL and SQL Server.

Do you have a comprehensive list of examples? Copy Chapter

Dapper has a comprehensive test suite in the test project.

Who is using this? Copy Chapter

Dapper is in production use at Stack Overflow.

File: Dapper.Rainbow/readme.md Copy Chapter

Using Dapper.Rainbow in C# for CRUD Operations

This guide outlines how to use Dapper.Rainbow in C# for CRUD operations.

1. Setting Up Copy Chapter

Add Dapper and Dapper.Rainbow to your project via NuGet:

Install-Package Dapper -Version x.x.x
Install-Package Dapper.Rainbow -Version x.x.x

Replace x.x.x with the latest version numbers.

2. Database Setup and Requirements Copy Chapter

For Dapper.Rainbow to function correctly, ensure each table has a primary key column named Id.

Example Users table schema:

CREATE TABLE Users (
    Id INT IDENTITY(1,1) PRIMARY KEY,
    Name VARCHAR(100),
    Email VARCHAR(100)
);

3. Establishing Database Connection Copy Chapter

Open a connection to your database:

using System.Data.SqlClient;

var connectionString = "your_connection_string_here";
using var connection = new SqlConnection(connectionString);
connection.Open(); // Open the connection

4. Defining Your Database Context Copy Chapter

Define a class for your database context:

using Dapper;
using System.Data;

public class MyDatabase : Database<MyDatabase>
{
    public Table Users { get; set; }
}

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

5. Performing CRUD Operations Copy Chapter

Insert Copy Section

var db = new MyDatabase { Connection = connection };
var newUser = new User { Name = "John Doe", Email = "[email protected]" };
var insertedUser = db.Users.Insert(newUser);

Select Copy Section

Fetch users by ID or all users:

var user = db.Users.Get(id); // Single user by ID
var users = connection.Query("SELECT * FROM Users"); // All users

Update Copy Section

var userToUpdate = db.Users.Get(id);
userToUpdate.Email = "[email protected]";
db.Users.Update(userToUpdate);

Delete Copy Section

db.Users.Delete(id);

6. Working with Foreign Keys Copy Chapter

Example schema for a Posts table with a foreign key to Users:

CREATE TABLE Posts (
    Id INT IDENTITY(1,1) PRIMARY KEY,
    UserId INT,
    Content VARCHAR(255),
    FOREIGN KEY (UserId) REFERENCES Users(Id)
);

Inserting a parent (User) and a child (Post) row:

var newUser = new User { Name = "Jane Doe", Email = "[email protected]" };
var userId = db.Users.Insert(newUser);

var newPost = new Post { UserId = userId, Content = "Hello, World!" };
db.Connection.Insert(newPost); // Using Dapper for the child table

File: Dapper.SqlBuilder/Readme.md Copy Chapter

Dapper.SqlBuilder - a simple sql formatter for .Net

Packages Copy Chapter

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

Features Copy Chapter

Dapper.SqlBuilder contains a number of helper methods for generating sql.

The list of extension methods in Dapper.SqlBuilder right now are:

SqlBuilder AddParameters(dynamic parameters);
SqlBuilder Select(string sql, dynamic parameters = null);
SqlBuilder Where(string sql, dynamic parameters = null);
SqlBuilder OrWhere(string sql, dynamic parameters = null);
SqlBuilder OrderBy(string sql, dynamic parameters = null);
SqlBuilder GroupBy(string sql, dynamic parameters = null);
SqlBuilder Having(string sql, dynamic parameters = null);
SqlBuilder Set(string sql, dynamic parameters = null);
SqlBuilder Join(string sql, dynamic parameters = null);
SqlBuilder InnerJoin(string sql, dynamic parameters = null);
SqlBuilder LeftJoin(string sql, dynamic parameters = null);
SqlBuilder RightJoin(string sql, dynamic parameters = null);
SqlBuilder Intersect(string sql, dynamic parameters = null);

Template Copy Chapter

SqlBuilder allows you to generate N SQL templates from a composed query, it can easily format sql when you are attaching parameters and how, e.g:

var builder = new SqlBuilder()
    .Where("a = @a", new { a = 1 })
    .Where("b = @b", new { b = 2 })
    .OrderBy("a")
    .OrderBy("b");
var counter = builder.AddTemplate("select count(*) from table /**where**/");
var selector = builder.AddTemplate("select * from table /**where**/ /**orderby**/");
var count = cnn.Query(counter.RawSql, counter.Parameters).Single();
var rows = cnn.Query(selector.RawSql, selector.Parameters);

it's same as

var count = cnn.Query("select count(*) from table where a = @a and b = @b", new { a = 1, b = 1 });
var rows = cnn.Query("select * from table where a = @a and b = @b order by a, b", new { a = 1, b = 1 });

Dynamic Filter Paging Example Copy Chapter

var builder = new SqlBuilder();
var selectTemplate = builder.AddTemplate(@"select X.* from (
        select us.*, ROW_NUMBER() OVER (/**orderby**/) AS RowNumber 
        from Users us 
        /**where**/
    ) as X 
    where RowNumber between @start and @finish", new { start, finish });
var countTemplate = builder.AddTemplate(@"select count(*) from Users /**where**/");

if (userId.HasValue())
    builder.Where($"t.userId = @{nameof(userId)}", new { userId });
if (isCancel)
    builder.Where($"t.isCancel = @{nameof(isCancel)}", new { isCancel });

builder.OrderBy(string.Format("t.id {0}", orderDesc ? "desc" : "asc"));

var users = conn.Query(selectTemplate.RawSql, selectTemplate.Parameters);
var count = conn.ExecuteScalar(countTemplate.RawSql, countTemplate.Parameters);
//..etc..

Limitations and caveats Copy Chapter

Combining the Where and OrWhere methods Copy Section

The OrWhere method currently groups all and and or clauses by type,
then join the groups with and or or depending on the first call.
This may result in possibly unexpected outcomes.
See also issue 647.

Example Where first

When providing the following clauses

sql.Where("a = @a1");
sql.OrWhere("b = @b1");
sql.Where("a = @a2");
sql.OrWhere("b = @b2");

SqlBuilder will generate sql

a = @a1 AND a = @a2 AND ( b = @b1 OR b = @b2 )

and not say

a = @a1 OR b = @b1 AND a = @a2 OR b = @b2

Example OrWhere first

When providing the following clauses

sql.OrWhere("b = @b1");
sql.Where("a = @a1");
sql.OrWhere("b = @b2");
sql.Where("a = @a2");

SqlBuilder will generate sql

a = @a1 OR a = @a2 OR ( b = @b1 OR b = @b2 )

File: docs/dapperplus.md Copy Chapter

Dapper and Dapper Plus

Dapper is the micro-ORM developed initially by Stack Overflow and now maintained independently, that offers simple, high performance
access to the ADO.NET API.

Dapper Plus is a separate tool by ZZZ Projects, which builds on the path set by Dapper, offering features like bulk operations,
and a range of documentation for Dapper.

From 2024, Dapper Plus is now a major sponsor of Dapper, helping to secure ongoing quality development and support of the Dapper platform.
This sponsorship does not impact the ownership, license, or any other particulars of how Dapper operates. The core Dapper libraries continue
to be freely available and fully open source.

File: docs/index.md Copy Chapter

Dapper - a simple object mapper for .NET

Overview Copy Chapter

A brief guide is available on github

Questions on Stack Overflow should be tagged dapper

Installation Copy Chapter

From NuGet:

Install-Package Dapper

or

Install-Package Dapper.StrongName

Note: to get the latest pre-release build, add -Pre to the end of the command.

Release Notes Copy Chapter

RELEASE NOTE TRACKING HAS MOVED TO GITHUB

See: https://github.com/DapperLib/Dapper/releases

Archive only (no new entries):

2.1.11 Copy Section

(note: new PRs will not be merged until they add release note wording here)

• infer command text without any whitespace as stored-procedure (#1975 via @mgravell)
• add global SupportLegacyParameterTokens setting to enable or disable single-character parameter tokens (#1974 via @Giorgi)
• revert $ addition for legacy parameter tokens (#1979 via @mgravell)
• change NRT annotation on GetConstructorParameter (#1980 via @mgravell, fixes #1969)

2.1.4 Copy Section

• add untyped GridReader.ReadUnbufferedAsync API (#1958 via @mgravell)
• tweak NRT annotations on type-handler API (#1960 via @mgravell, fixes #1959)

2.1.1 Copy Section

• add NRT annotations (#1928 via @mgravell)
• extend GridReader API to allow it to be subclassed by external consumers (#1928 via @mgravell)
• support $ as a parameter prefix (#1952 via @Giorgi)
• add public API tracking (#1948 via @mgravell)

2.0.151 Copy Section

• add global FetchSize setting for use with Oracle (#1946 via mgravell, fixes #1945) (also add some missing logic in Settings.Reset())
• add underscore handling with constructors (#1786 via @jo-goro, fixes #818; also #1947 via mgravell)

2.0.143 Copy Section

• add missing non-generic AsyncEnumerable<dynamic> QueryUnbufferedAsync(...) API (#1925 via mgravell, fixes #1922)
• formally mark all struct types as readonly (#1925 via mgravell)
• reinstate fallback support for IDataReader, and implement missing DbDataReader async APIs (#1913 via mgravell)

2.0.138 Copy Section

• (#1910 via mgravell, fix #1907, #1263)
  • add support for SqlDecimal and other types that need to be accessed via DbDataReader.GetFieldValue<T>
  • add an overload of AddTypeMap that supports DbDataReader.GetFieldValue<T> for additional types
  • acknowledge that in reality we only support DbDataReader; this has been true (via DbConnection) for async forever
• (#1912 via mgravell)
  • add missing AsyncEnumerable<T> QueryUnbufferedAsync<T>(...) and GridReader.ReadUnbufferedAsync<T>(...) APIs (.NET 5 and later)
  • implement IAsyncDisposable on GridReader (.NET 5 and later)

2.0.123 Copy Section

• Parameters can now be re-used on subsequent commands (#952 via jamescrowley)
• Array query support (.Query) on supported platforms (e.g. Postgres) (#1598 via DarkWanderer)
• SqlMapper.HasTypeHandler is made public for consumers (#1405 via brendangooden)
• Improves multi-mapping error message when a specified column in splitOn can't be found (#1664 via NickCraver)
• Improves DbString.ToString() (#1665 via NickCraver)
• DbType for date/time types is no longer explicitly specified (resolves Npgsql v6 issue)
• add Settings.UseIncrementalPseudoPositionalParameterNames, to support "snowflake" parameter naming conventions

2.0.90 Copy Section

• logo added; license updated to mention logo usage (via mgravell)
• moved to DapperLib org; links updated (#1656)
• RepoDb benchmark added (#1626 via stevedesmond-ca)
• excise unrelated Soma tests (#1642 via kant2002)
• SqlMarshl benchmark added (#1646 via kant2002)
• documentation fixes (#1615 via Rollerss, #1604 via GitHubPang)

2.0.78 Copy Section

• fix DynamicParameters loop bug - wrong index (#1443 via DamirAinullin)
• fix nullable tuple handling (#1400 via JulianRooze)
• support update set in SqlBuilder (#1404 via Wei)
• initialize collections with counts when possible (#1449 via DamirAinullin)
• general code cleanup (#1452, #1457, #1458, #1459 all via DamirAinullin)
• C# 9 and .NET 5 preparation/cleanup (#1572 via mgravell)
• GitHub action, Docker, AppVeyor work (build/test) work (#1563 via Tyrrrz, #1559 via craver, #1450 via craver)
• Test project rationalization (#1556 via craver)
• ClickHouse detection (#1462 via DarkWanderer)
• Switched to "main" branch (via craver)
• documentation fixed (#1596 via royal, #1560 via wswind, #1558 via paul42, #1507 via imba-tjd, #1508 via dogac00, 899c9feb via BlackjacketMack, 0b17133 via BlackjacketMack, 9b6c8c7d via bryancrosby, #1202 via craver)
• MightyOrm benchmark added (455b3f3b via cdonnellytx)
• EF6 performance test updates (#1361 via AlexBagnolini)

2.0.35 Copy Section

• build tooling: enable "deterministic builds" and enable SDK roll-foward
• fix culture related formatting/parsing issue with Sqlite (#1363 via sebastienros)
• documentation fixes (#1357 via jawn)
• add tests for SqlBuilder (#1369 via shps951023)

2.0.30 Copy Section

• upstream library updates; project (build) cleanup
• reinstated net461 build target
• add Dapper.ProviderTools library (to help with System vs Microsoft SqlClient migration, etc)
• fix double dictionary lookup (#1339 via DamirAinullin)
• fix bug with dynamic parameters accessing the wrong member (#1334 via DamirAinullin)
• fix explicit-key issue with DeleteAsync (#1309 via james-hester-ah)
• fix for char on Postgres (#1326 via jjonescz)
• documentation fixes (#1340 via jawn)
• test and benchmark fixes (#1337 via DamirAinullin, #1206 via yesmey, #1331 via andresrsanchez, #1335 via DamirAinullin)

2.0.4 Copy Section

Primary changes:

• remove the System.Data.SqlClient dependency, allowing consumers to use System.Data.SqlClient or Microsoft.Data.SqlClient (or neither, or both) as they choose
• this means that some users may need to re-add one of the above as a `` for their project to build, if they were previously relying on Dapper to provide System.Data.SqlClient
• the AsTableValuedParameter(this IEnumerable<SqlDataRecord>) extension method is now AsTableValuedParameter<T>(this IEnumerable<T>) where T : IDataRecord; this is a breaking change but should be code-compatible and just requires a rebuild
• unify the target platform at NetStandard2.0 (and .NET Framework 4.6.2 for the EF DB geometry/geography types)
• fix bug with Identity not enforcing type identity of multi-mapped types

Other changes merged:

• fix #1242, #1280, #1282 - fix value-tuple mapping
• fix #1295 - add ExecuteReaderAsync overload to expose DbDataReader
• fix #569 - handing of IN and similar clauses in some scenarios
• fix #1256 - make Dispose() polymorphic in "rainbow"
• fix #1257 - make the .Connection available in "rainbow"

1.60.6 Copy Section

• improve performance of descriptor API

1.60.5 Copy Section

• add descriptor API to DapperRow (enables UI binding with non-generic Query() API)

1.60.1 Copy Section

• Fix #1196 - versioning fix only (#1198) - assembly version is now locked at 1.60.0 to resolve some mismatch issues with .NET Core assembly loading/binding.

1.50.7 Copy Section

• Fix #1190 - incorrect unmanaged pointer when processing parameters that are a boxed struct (rare error relating to GC)
• Fix #1111 - make SqlMapper.Parse consistent with QueryImpl
• Fix #111- - improve error message for invalid literal types
• Fix #1149 - improve error messages in "contrib"
• Improved detection of empty table-valued-parameters

1.50.5 Copy Section

• Fixes empty result set hanging with QueryAsync
• DapperRow now implements IReadOnlyDictionary<string, object>
• Improved error messages for Async when the provided IDbConnection is not a DbConnection
• Contrib: GetAll now handles nullable types

1.50.4 Copy Section

• Added back missing .NET Standard functionality (restored in netstandard2.0)
• Bumped SqlClient dependency to 4.4.0 (to help propagate the newer client)

1.50.2 Copy Section

• Fix issue #569 (in expansions using ODBC pseudo-positional arguments)

1.50.1 Copy Section

• Change to how string_split is used for InListStringSplitCount

1.50.0 Copy Section

• No changes; stable release

1.50.0-rc3 Copy Section

• Updated for .Net Core RTM package dependencies

1.50.0-rc2b Copy Section

• New InListStringSplitCount global setting; if set (non-negative), in @foo expansions (of at least the specified size) of primitive types (int, tinyint, smallint, bigint) are implemented via the SQL Server 2016 (compat level 130) STRING_SPLIT function
• Fix for incorrect conversions in GridReader (#254)

1.50.0-rc2 / 1.50.0-rc2a Copy Section

• Packaging for .NET Core rc2

1.50-beta9 Copy Section

• Fix for PadListExpansions to work correctly with not in scenarios; now uses last non-null value instead of null; if none available, don't pad
• Fix problems with single-result/single-row not being supported by all providers (basically: sqlite, #466)
• Fix problems with enums - nulls (#467) and primitive values (#468)
• Add support for C# 6 get-only properties (#473)
• Add support for various xml types (#427)

1.50-beta8 Copy Section

• Addition of GetRowParser<T> extension method on IDataReader API - allows manual construction of discriminated unions, etc
• Addition of Settings.PadListExpansions - reduces query-plan saturation by padding list expansions with null values (opt-in, because on some DB configurations this could change the meaning) (note: bad choice of null revised in 1.50-beta9)
• Addition of Settings.ApplyNullValues - assigns (rather than ignores) null values when possible
• Fix for #461 - ensure type-handlers work for constructor-based initialization
• Fix for #455 - make the LookupDbType method available again

1.50-beta7 Copy Section

• Addition of GetRowParser(Type) (and refactor the backing store for readers to suit)
• Column hash should consider type, not just name

1.50-beta6 Copy Section

• Fix for issue #424 - defensive SqlDataRecord handling

1.50-beta5 Copy Section

• Add "single", "first", "single or default" to complement the "first or default" options from 1.50-beta4
• Use single-row/single-result when possible
• Fix for proxy-generator (issue #361)

1.50-beta4 Copy Section

• Add QueryFirstOrDefault / ReadFirstOrDefault methods that optimize the single-row scenario
• Remove some legacy dynamic usage from the async API
• Make DynamicTypeMap public again (error during core-clr migration)
• Use Hashtable again on core-clr

1.50-beta3 Copy Section

• Core CLR support: add explicit dnx451 support in addition to dotnet5.4 (aka netstandard1.4)

1.50-beta2 Copy Section

• Core CLR now targets rc1 / 23516
• Various Core CLR fixes
• Code cleanup and C# 6 usage (assorted)

1.50-beta1 Copy Section

• Split SqlMapper.cs as it was becoming too unmaintainable; NuGet is now the only supported deployment channel
• Remove down-level C# requirements, as "drop in the file" is no longer the expected usage
• SqlMapper.Settings added; provides high-level global configuration; initially CommandTimeout (@Irrational86)
• improve error message if an array is used as a parameter in an invalid context
• Add Type[] support for GridReader.Read scenarios (@NikolayGlynchak)
• Support for custom type-maps in collection parameters (@gjsduarte)
• Fix incorrect cast in QueryAsync<T> (@phnx47, #346)
• Fix incorrect null handling re UdtTypeName (@perliedman)
• Support for SqlDataRecord (@sqmgh)
• Allow DbString default for IsAnsi to be specified (@kppullin)
• provide TypeMapProvider with lazy func-based initialization (@garyhuntddn)
• Core-clr updated to beta-8 and various cleanups/fixes
• Built using core-clr build tools

1.42 Copy Section

• Fix bug with dynamic parameters where .Get<T> is called before the command is executed

1.41-beta5 Copy Section

• Core-clr packaging build and workarounds
• Fix bug with literal {=val} boolean replacements

1.41-beta4 Copy Section

• Core-clr packaging build
• Improve mapping to enum members (@BrianJolly)

1.41-beta Copy Section

• Core-clr packaging build

1.41-alpha Copy Section

• Introduces dnx (core-clr) experimental changes
• Adds SqlBuilder project
• Improve error message when incorrectly accessing parameter values

1.40 Copy Section

• Workaround for broken GetValues() on Mono; add AsList()

1.39 Copy Section

• Fix case on SQL CLR types; grid-reader should respect no-cache flags; make parameter inclusion case-insensitive

1.38 Copy Section

• Specify constructor explicitly; allow value-type parameters (albeit: boxed)

1.37 Copy Section

• Reuse StringBuilder instances when possible (list parameters in particular)

1.36 Copy Section

• Fix Issue #192 (expanded parameter naming glitch) and Issue #178 (execute reader now wraps the command/reader pair, to extend the command lifetime; note that the underlying command/reader are available by casting to IWrappedDataReader)

1.35 Copy Section

• Fix Issue #151 (Execute should work with ExpandoObject etc); Fix Issue #182 (better support for db-type when using object values);
• Output expressions / callbacks in dynamic args (via Derek); arbitrary number of types in multi-mapping (via James Holwell);
• Fix DbString/Oracle bug (via Mauro Cerutti); new support for named positional arguments

1.34 Copy Section

• Support for SqlHierarchyId (core)

1.33 Copy Section

• Support for SqlGeometry (core) and DbGeometry (EF)

1.32 Copy Section

• Support for SqlGeography in core library

1.31 Copy Section

• Fix issue with error message when there is a column/type mismatch

1.30 Copy Section

• Better async cancellation

1.29 Copy Section

• Make underscore name matching optional (opt-in) - this can be a breaking change for some people

1.28 Copy Section

• Much better numeric type conversion; fix for large oracle strings; map Foo_Bar to FooBar (etc); ExecuteScalar added; stability fixes

1.27 Copy Section

• Fixes for type-handler parse; ensure type-handlers get last dibs on configuring parameters

1.26 Copy Section

• New type handler API for extension support

1.25 Copy Section

• Command recycling and disposing during pipelined async multi-exec; enable pipeline (via sync-over-async) for sync API"

File: docs/readme.md Copy Chapter

Dapper

Dapper is a simple micro-ORM used to simplify working with ADO.NET; if you like SQL but dislike the boilerplate of ADO.NET: Dapper is for you!

As a simple example:

string region = ...
var customers = connection.Query<Customer>(
    "select * from Customers where Region = @region", // SQL
    new { region } // parameters
    ).AsList();

But all the execute/single-row/scalar/async/etc functionality you would expect: is there as extension methods on your DbConnection.

See GitHub for more information and examples.

Sponsors Copy Chapter

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

File: docs/README.md Copy Chapter

Dapper

Dapper is a simple micro-ORM used to simplify working with ADO.NET; if you like SQL but dislike the boilerplate of ADO.NET: Dapper is for you!

As a simple example:

string region = ...
var customers = connection.Query<Customer>(
    "select * from Customers where Region = @region", // SQL
    new { region } // parameters
    ).AsList();

But all the execute/single-row/scalar/async/etc functionality you would expect: is there as extension methods on your DbConnection.

See GitHub for more information and examples.

Sponsors Copy Chapter

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

File: docs/Readme.md Copy Chapter

Dapper

Dapper is a simple micro-ORM used to simplify working with ADO.NET; if you like SQL but dislike the boilerplate of ADO.NET: Dapper is for you!

As a simple example:

string region = ...
var customers = connection.Query<Customer>(
    "select * from Customers where Region = @region", // SQL
    new { region } // parameters
    ).AsList();

But all the execute/single-row/scalar/async/etc functionality you would expect: is there as extension methods on your DbConnection.

See GitHub for more information and examples.

Sponsors Copy Chapter

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