ContextQMD
Back to Dapper

Dapper - a simple object mapper for .NET

docs/index.md

2.1.7214.4 KB
Original Source

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

or

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"