/
index.md
353 lines (227 loc) · 14.4 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
# Dapper - a simple object mapper for .NET
## Overview
A brief guide is available [on github](https://github.com/DapperLib/Dapper/blob/main/Readme.md)
Questions on Stack Overflow should be tagged [`dapper`](https://stackoverflow.com/questions/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](https://github.com/DapperLib/Dapper/issues/1196) - versioning fix only ([#1198](https://github.com/DapperLib/Dapper/pull/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](https://github.com/DapperLib/Dapper/issues/1190) - incorrect unmanaged pointer when processing parameters that are a boxed struct (rare error relating to GC)
- Fix [#1111](https://github.com/DapperLib/Dapper/issues/1111) - make `SqlMapper.Parse` consistent with `QueryImpl`
- Fix #111- - improve error message for invalid literal types
- Fix [#1149](https://github.com/DapperLib/Dapper/pull/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](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/466))
- Fix problems with enums - nulls ([#467](https://github.com/DapperLib/Dapper/issues/467)) and primitive values ([#468](https://github.com/DapperLib/Dapper/issues/468))
- Add support for C# 6 get-only properties ([#473](https://github.com/DapperLib/Dapper/issues/473))
- Add support for various xml types ([#427](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/461) - ensure type-handlers work for constructor-based initialization
- Fix for [#455](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/192) (expanded parameter naming glitch) and Issue [#178](https://github.com/DapperLib/Dapper/issues/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](https://github.com/DapperLib/Dapper/issues/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"