Dapper - a simple object mapper for .NET

Overview

A brief guide is available on github

Questions on Stack Overflow should be tagged dapper

Installation

From NuGet:

Install-Package Dapper

Install-Package Dapper.StrongName

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

Release Notes

RELEASE NOTE TRACKING HAS MOVED TO GITHUB

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

Archive only (no new entries):

2.1.11

(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

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

2.1.1

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

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

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

(#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

Parameters can now be re-used on subsequent commands (#952 via jamescrowley)
Array query support (.Query<int[]>) 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

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

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

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

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

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 <PackageReference> 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

improve performance of descriptor API

1.60.5

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

1.60.1

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

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

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

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

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

1.50.1

Change to how string_split is used for InListStringSplitCount

1.50.0

No changes; stable release

1.50.0-rc3

Updated for .Net Core RTM package dependencies

1.50.0-rc2b

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

Packaging for .NET Core rc2

1.50-beta9

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

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

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

1.50-beta6

Fix for issue #424 - defensive SqlDataRecord handling

1.50-beta5

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

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

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

1.50-beta2

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

1.50-beta1

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

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

1.41-beta5

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

1.41-beta4

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

1.41-beta

Core-clr packaging build

1.41-alpha

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

1.40

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

1.39

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

1.38

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

1.37

Reuse StringBuilder instances when possible (list parameters in particular)

1.36

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

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

Support for SqlHierarchyId (core)

1.33

Support for SqlGeometry (core) and DbGeometry (EF)

1.32

Support for SqlGeography in core library

1.31

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

1.30

Better async cancellation

1.29

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

1.28

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

1.27

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

1.26

New type handler API for extension support

1.25

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