Dapper v3 planning and discussion

[NickCraver]

It's time for a major release and we've just been busy with other libraries. In context though, Dapper is far less work to get there. netstandard is already supported and we don't have a long list of desired (breaking) changes to the APIs. Starting a list here to track:

API changes (breaking):

• Optional CancellationToken params on all Async methods (related: Async versions of QueryFirst/Single/FirstorDefault/SingleOrDefault with CommandDefinition are missing #484)
• Dapper.Contrib Insert<T> and Insert<T, TKey> changes for ISqlAdapter (discussion in Changed Insert methods and interface to return id as long. #640, related: #559, #587)
• Dapper.Contrib - Allow custom ISqlAdapter (#497) (note: this locks us down for any future interface additions)
• SqlBuilder needs a lot of tests and love (SqlBuilder OR clause #573, OrWhere() causing unexpected behavior in Where() #647)
• Overload reduction via CommandFlags (related: Dapper doesn't use prepared statements #474)

Package Changes (breaking):

• Re-title to "Dapper" & rename Repo (Isn't is possible to unify the project/package/etc. names?  #683)
• Strong-Name for Dapper (deprecating Dapper.StrongName)
• Strong-Name for Dapper.Contrib (Dapper.Contrib is not storng named #430, Dapper.Contrib strong name nuget package #685)

Missing APIs (non-breaking):

• QueryAsync<T> and related have a few missing from the single/first additions
• Dapper.Rainbow netstandard support (Is there a Dapper.Rainbow release for .NET Core? #676)

PRs to examine:

• Allow custom TypeHandlers for standard types #471 - Allow custom TypeHandlers for standard types (and .SetValue()) (related: TypeHandler<> can't override default typeMap for base types #206, Custom type handlers for enums are ignored #259, Dapper custom TypeHandler SetValue not being called? #303, Mapping of TimeSpan to DbType.Time is too restrictive #319, Use TypeHandler for all types #433, DateTime columns from database have Kind property Unspecified. #571, SetValue is not invoked in a Dapper custom TypeHandler #607)
• Custom type handlers for enums are ignored #458 - Custom type handlers for enums are ignored
• Fixed #497 by exposing SqlMapperExtensions.AdapterDictionary as public. #512 - Fixed #497 by exposing SqlMapperExtensions.AdapterDictionary as public
• Temporary fix for #555 #558 - Temporary fix (really want to fix the actual issue: Dapper cancelling only ExecuteReaderAsync not Reader.ReadAsync with MultiMap #555)
• Allow multi-map async queries to be unbuffered #597 - Allow multi-map async queries to be unbuffered (related: Unbuffered QueryAsnyc multi-mapping throws an InvalidOperationException  #596)
• Dapper.Contrib - Support for composite keys in Get method #636 - Dapper.Contrib - Support for composite keys in Get method

Cleanup

• Documentation cleanup everywhere
• Moving to VS 2017 RC and new .csproj system (off Preview 2 project.json tooling)
• Organize folders (after PRs!): src, tests, docs, etc. (and the same in the solution)
• Release notes/documentation: moving into /docs (GitHub feature post here, note: this allows PRs to update docs easily too)
• Global: Interpolated String usage (added firebird support #651)
• Firebird Async support (added firebird support #651 addition)
• Passing parameters object with static property causes dapper to fail with cryptic exception. #621 - Static property issues on params
• SimpleMemberMap became internal between 1.42 and 1.50.2 #613 - SimpleMemberMap became internal between 1.42 and 1.50.2
• Documentation: Add example for literal replacement to Readme.md #551 - Add example for literal replacement to Readme.md
• Documentation for Dapper.SqlBuilder #480 - Documentation for SqlBuilder
• clarification on "Limitations and caveats" #451 - Clarify memory documentation
• Audit where DbCommand.Cancel() is called #417 - Audit where DbCommand.Cancel() is called

Discussion - Should we add a [Column] or [Table] attributes and/or mapping methods?

Discussion in #722, please chime in!

Discussion - Should we add a DynamicParameters.Add() overload in for DB params?

See #659 for details, specifically:

DynamicParameters.Add(string name, DbType type, ...)

...okay that took a while, and it's a lot of info but I'm trying to relate all the issues I see with a common solution path. What did I forget? What's wrong? Thoughts on discussion items above (or pretty much anything of course)?

There will also be some background work I'll take on here. Like being able to more readily test Dapper & Dapper.Contrib against all providers. Luckily Docker has matured enough that having a rich test bed against most providers is finally a reality. I'm working with others in the container and cloud space to make this an option for all, but that's not a blocker by any means.

I haven't even shown this to @mgravell yet. So hopefully he doesn't kinda sorta give me a mild case of death at the next meetup. Due to how # links work...this is the best way to share it for review as well, so here it is.

[supersonicclay]

I don't think 8aa10a0 alone is a breaking change since it is additive. And from the testing I've done, it is a backward-compatible solution to #471.

Would it be possible to get a new version pushed to NuGet that is simply 1.50.2 + 8aa10a0 without including everything else from master that may cause breaking changes or waiting on v2?

[aluanhaddad]

Personally, I would expect to see all of the public APIs given much improved source level documentation. Specifically, all parameters should have full doc comments, consistent names, and usage examples. I frequently have to read the source code to verify that certain methods behave the way I think they might.

Even currently existing comments leave much to be desired. For example, splitOn has an awful doc comment that reads

/// <param name="splitOn">
/// The Field we should split and read the second object from (default: id)
/// </param>

Another example is the DynamicParameters constructor that takes an object parameter named template. This makes one uneasy about assuming it behaves the same way as void AddDynamicParams(object param) because... well... why is the name different?
I do not like to mutate objects after initialization and I thought passing a parameter object to the constructor might behave the same way as AddDynamicParams, but I had to read the source code to confirm this because there is not a clear naming pattern and so many methods already have arguments that are weakly typed and optional.

[paulmrozowski]

I would LOVE to have the ability to easily access the returned results metadata - things like the original field's width for strings, or scale/precision for numeric types, etc.

[unsafePtr]

I will leave here an idea. I think that will be very good to add support of ValueTuple<> (c# 7 feature) with named arguments:

public async Task<(int tickeTypeId, int ticketsSold, decimal price)> Test()
{
    return await context.QueryAsync<(int tickeTypeId, int ticketsSold, decimal price)>(SqlResources.GetCardSales);
}

I understood that there is some magic with ValueTuples run-time, but maybe you have an idea how to get it work.

[RobThree]

Maybe add some form of query-interception? If we want to do it now we have to implement a Dapper "wrapper" exposing all extension-methods Dapper provides and implement logging there before/after invoking the actual Dapper method.

Maybe a simple event(s) like BeforeExecute (and AfterExecute) can be raised with the actual CommandDefinition as (one of) the events BeforeExecuteEventArgs (and AfterExecuteEventArgs) argument properties.

So what I'm saying:

public class BeforeExecuteEventArgs : EventArgs {
    public CommandDefinition CommandDefinition { get; set; }
    // ... maybe more? Maybe context/IDbConnection etc.?
}

And then raise the event(s) in the Execute/Query/etc. extensionmethods.

This way logging of queries, for example, can be simplified/more easily be hooked.

[ricsmania]

About enum handlers, it would be extremely productive for us if there were a way to add a global handler. For example, most of our enums are declared like this:

enum DocumentStatus
{
    Normal = 'N',
    Canceled = 'C'        
}

And the corresponding tables are char(1) fields with the char value. The most productive way would be adding a global handler that converts the char value from the enum to the char value from the database.

[NickCraver]

@ricsmania Can you explain that one a little bit? The enum declaration you have is equivalent to:

enum DocumentStatus
{
	Normal = 78,
	Canceled = 67
}

...would you expect an implicit char translation understanding to integer positions for the enum? Inherently, that has some problems as it could easily be mis-used to trigger enum values that aren't there. For example (DocumentStatus)320 is perfectly legal, yet practically invalid.

[ricsmania]

@NickCraver Right now what we do is we actually use a database function to explicitly convert chars to the ascii value and vice versa. But we don't want to do that conversion using database functions anymore.

What I'm suggesting is actually creating a way to add a global enum handler, so that we could create a single handler that does that converts any enum using whatever rule we define. I'm not suggesting that Dapper should convert the values, but actually that it could provide the means for us to implement our own conversion. Right now it only converts from numeric types it seems.

Also, the current version doesn't work for enum handlers, but testing the suggested solutions it seems we would need to add a handler for each specific enum, which isn't very productive.