Getting Started

Overall Structure

Dapper.Wrappers provides 3 different classes of objects:

• Query Formatters: The query formatters provide RDBMS-specific formatting functions. Currently, two RDBMSs are supported: SQL Server and PostgreSQL. By default, the SQL Server formatter is configured by the dependency injection helpers, but this can be overridden. See the Dependency Injection section for more details on how to configure this.
• Query Context: A QueryContext is used to add queries and variables to the current batch of SQL, and execute the queries using Dapper. Transactions are used when running the batch of queries, and are automatically committed when the batch is complete. The functions on the generators all require a context to be passed as the first argument.
• Query Generators: The query generators are designed to allow you to declare what operations are permitted in a query, along with the query pieces that will be added for each operation. To add a query to the context, the appropriate add method should be called. These take as arguments the QueryContext that will be updated with the query and relevant variables, along with which operations are needed (and the corresponding parameters). For more details on how this works, see the Building Generators page.

Setting up Dependency Injection

Dapper.Wrappers provides extension methods to easily integrate with .Net Core/.Net 5 dependency injection. If you choose to use a different dependency injection framework with your app, you can skip to the Custom Dependency Injection section.

.Net Core/.Net 5 Dependency Injection

In your Startup class, add the following using statement:

using Dapper.Wrappers.DependencyInjection;

This should make available some IServiceCollection extensions to allow you to register the types necessary for using Dapper.Wrappers. In your ConfigureServices method, you can add these lines:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddDapperWrappers();

    ...
}

This will configure by default the SqlServerQueryFormatter to be used by the Query Generators, and the default QueryContext. To override these settings, you can include an Action that changes these options:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddDapperWrappers(dwOptions =>
    {
        dwOptions.DatabaseEngine = SupportedDatabases.PostgreSQL;
        dwOptions.QueryContextType = typeof(MyCustomQueryContext);
        dwOptions.DbConnectionType = typeof(NpgsqlConnection);
    });

    ...
}

It is also possible to register these types outside of the AddDapperWrappers call if you want to override the defaults or if one of the types requires extra configuration:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddScoped<IDbConnection>(_ =>
        new NpgsqlConnection(Configuration.GetConnectionString("Default")));

    services.AddDapperWrappers(dwOptions =>
    {
        dwOptions.DatabaseEngine = SupportedDatabases.PostgreSQL;
        dwOptions.QueryContextType = typeof(MyCustomQueryContext);
    });

    ...
}

If the types are registered outside of the extension methods, in general you will want to register the connection and context as scoped (so that a unique one will be provided for each request), while the formatter and generators should be registered as singletons, since one of them can be reused for all the different calls to the server.

The IServiceCollection extensions do not register any generators. It is up to you to do so in your own code. In future releases, functionality to help with registering these types may be added to the library.

Custom Dependency Injection

When setting up dependency injection, the required types are:

• IQueryContext (registered so that a new one is created for each request)
• IDbConnection (registered so that a new one is created for each request)
• An IQueryFormatter (registered as a singleton)
• Any Query Generators that exist in your project (also declared as singletons)

If you would like to see examples for any specific DI frameworks, please create an issue in the GitHub repository requesting one (or even better, submit a pull request so that it can benefit others that may need the same).