Dapper is a [single file](https://github.com/SamSaffron/dapper-dot-net/blob/master/Dapper/SqlMapper.cs) you can drop in to your project that will extend your IDbConnection interface.
Dapper is a [single file](https://github.com/SamSaffron/dapper-dot-net/blob/master/Dapper/SqlMapper.cs) you can drop in to your project that will extend your IDbConnection interface.
It provides 3 helpers:
It provides 3 helpers:
Execute a query and map the results to a strongly typed List
Execute a query and map the results to a strongly typed List
).IsEqualTo(3);// 3 rows inserted: "1,1", "2,2" and "3,3"
).IsEqualTo(3);// 3 rows inserted: "1,1", "2,2" and "3,3"
```
```
This works for any parameter that implements IEnumerable<T> for some T.
This works for any parameter that implements IEnumerable<T> for some T.
Performance
Performance
-----------
-----------
A key feature of Dapper is performance. The following metrics show how long it takes to execute 500 SELECT statements against a DB and map the data returned to objects.
A key feature of Dapper is performance. The following metrics show how long it takes to execute 500 SELECT statements against a DB and map the data returned to objects.
The performance tests are broken in to 3 lists:
The performance tests are broken in to 3 lists:
- POCO serialization for frameworks that support pulling static typed objects from the DB. Using raw SQL.
- POCO serialization for frameworks that support pulling static typed objects from the DB. Using raw SQL.
- Dynamic serialization for frameworks that support returning dynamic lists of objects.
- Dynamic serialization for frameworks that support returning dynamic lists of objects.
- Typical framework usage. Often typical framework usage differs from the optimal usage performance wise. Often it will not involve writing SQL.
- Typical framework usage. Often typical framework usage differs from the optimal usage performance wise. Often it will not involve writing SQL.
### Performance of SELECT mapping over 500 iterations - POCO serialization
### Performance of SELECT mapping over 500 iterations - POCO serialization
<table>
<table>
<tr>
<tr>
<th>Method</th>
<th>Method</th>
<th>Duration</th>
<th>Duration</th>
<th>Remarks</th>
<th>Remarks</th>
</tr>
</tr>
<tr>
<tr>
<td>Hand coded (using a <code>SqlDataReader</code>)</td>
<td>Hand coded (using a <code>SqlDataReader</code>)</td>
<td>47ms</td>
<td>47ms</td>
<tdrowspan="9"><ahref="http://www.toptensoftware.com/Articles/94/PetaPoco-More-Speed">Can be faster</a></td>
<tdrowspan="9"><ahref="http://www.toptensoftware.com/Articles/94/PetaPoco-More-Speed">Can be faster</a></td>
### Performance of SELECT mapping over 500 iterations - typical usage
### Performance of SELECT mapping over 500 iterations - typical usage
<table>
<table>
<tr>
<tr>
<th>Method</th>
<th>Method</th>
<th>Duration</th>
<th>Duration</th>
<th>Remarks</th>
<th>Remarks</th>
</tr>
</tr>
<tr>
<tr>
<td>Linq 2 SQL CompiledQuery</td>
<td>Linq 2 SQL CompiledQuery</td>
<td>81ms</td>
<td>81ms</td>
<td>Not super typical involves complex code</td>
<td>Not super typical involves complex code</td>
</tr>
</tr>
<tr>
<tr>
<td>NHibernate HQL</td>
<td>NHibernate HQL</td>
<td>118ms</td>
<td>118ms</td>
<td> </td>
<td> </td>
</tr>
</tr>
<tr>
<tr>
<td>Linq 2 SQL</td>
<td>Linq 2 SQL</td>
<td>559ms</td>
<td>559ms</td>
<td> </td>
<td> </td>
</tr>
</tr>
<tr>
<tr>
<td>Entity framework</td>
<td>Entity framework</td>
<td>859ms</td>
<td>859ms</td>
<td> </td>
<td> </td>
</tr>
</tr>
<tr>
<tr>
<td>SubSonic ActiveRecord.SingleOrDefault</td>
<td>SubSonic ActiveRecord.SingleOrDefault</td>
<td>3619ms</td>
<td>3619ms</td>
<td> </td>
<td> </td>
</tr>
</tr>
</table>
</table>
Performance benchmarks are available [here](https://github.com/SamSaffron/dapper-dot-net/blob/master/Tests/PerformanceTests.cs)
Performance benchmarks are available [here](https://github.com/SamSaffron/dapper-dot-net/blob/master/Tests/PerformanceTests.cs)
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)
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)
Parameterized queries
Parameterized queries
---------------------
---------------------
Parameters are passed in as anonymous classes. This allow you to name your parameters easily and gives you the ability to simply cut-and-paste SQL snippets and run them in Query analyzer.
Parameters are passed in as anonymous classes. This allow you to name your parameters easily and gives you the ability to simply cut-and-paste SQL snippets and run them in Query analyzer.
```csharp
```csharp
new{A=1,B="b"}// A will be mapped to the param @A, B to the param @B
new{A=1,B="b"}// A will be mapped to the param @A, B to the param @B
```
```
List Support
List Support
------------
------------
Dapper allow you to pass in IEnumerable<int> and will automatically parameterize your query.
Dapper allow you to pass in IEnumerable<int> and will automatically parameterize your query.
For example:
For example:
```csharp
```csharp
connection.Query<int>("select * from (select 1 as Id union all select 2 union all select 3) as X where Id in @Ids",new{Ids=newint[]{1,2,3});
connection.Query<int>("select * from (select 1 as Id union all select 2 union all select 3) as X where Id in @Ids",new{Ids=newint[]{1,2,3});
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.
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.
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
Multi Mapping
---------------------
---------------------
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.
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.
**important note** Dapper assumes your Id columns are named "Id" or "id", if your primary key is different or you would like to split the wide row at point other than "Id", use the optional 'splitOn' parameter.
**important note** Dapper assumes your Id columns are named "Id" or "id", if your primary key is different or you would like to split the wide row at point other than "Id", use the optional 'splitOn' parameter.
Multiple Results
Multiple Results
---------------------
---------------------
Dapper allows you to process multiple result grids in a single query.
Dapper allows you to process multiple result grids in a single query.
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:
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:
```csharp
```csharp
Query<Thing>("select * from Thing where Name = @Name",new{Name=newDbString{Value="abcde",IsFixedLength=true,Length=10,IsAnsi=true});
Query<Thing>("select * from Thing where Name = @Name",new{Name=newDbString{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.
On Sql Server it is crucial to use the unicode when querying unicode and ansi when querying non unicode.
Limitations and caveats
Limitations and caveats
---------------------
---------------------
Dapper caches information about every query it runs, this allow it to materialize objects quickly and process parameters quickly. The current implementation caches this information in a ConcurrentDictionary object. The objects it stores are never flushed. If you are generating SQL strings on the fly without using parameters it is possible you will hit memory issues. We may convert the dictionaries to an LRU Cache.
Dapper caches information about every query it runs, this allow it to materialize objects quickly and process parameters quickly. The current implementation caches this information in a ConcurrentDictionary object. The objects it stores are never flushed. If you are generating SQL strings on the fly without using parameters it is possible you will hit memory issues. We may convert the dictionaries to an LRU Cache.
Dapper's simplicity means that many feature that ORMs ship with are stripped out, there is no identity map, there are no helpers for update / select and so on.
Dapper's simplicity means that many feature that ORMs ship with are stripped out, there is no identity map, there are no helpers for update / select and so on.
Dapper does not manage your connection's lifecycle, it assumes the connection it gets is open AND has no existing datareaders enumerating (unless MARS is enabled)
Dapper does not manage your connection's lifecycle, it assumes the connection it gets is open AND has no existing datareaders enumerating (unless MARS is enabled)
Will dapper work with my db provider?
Will dapper work with my db provider?
---------------------
---------------------
Dapper has no DB specific implementation details, it works across all .net ado providers including sqlite, sqlce, firebird, oracle, MySQL and SQL Server
Dapper has no DB specific implementation details, it works across all .net ado providers including sqlite, sqlce, firebird, oracle, MySQL and SQL Server
Do you have a comprehensive list of examples?
Do you have a comprehensive list of examples?
---------------------
---------------------
Dapper has a comprehensive test suite in the [test project](https://github.com/SamSaffron/dapper-dot-net/blob/master/Tests/Tests.cs)
Dapper has a comprehensive test suite in the [test project](https://github.com/SamSaffron/dapper-dot-net/blob/master/Tests/Tests.cs)
