TCIS.Persistence.Dapper 1.0.0-rc.9

TCIS.Persistence.Dapper

The library providing an abstraction layer to work with Dapper safely and optimally within the TCIS ecosystem. It supports automatic DbConnection management via the Factory pattern and provides IDapperContext with numerous utility methods.

📦 Installation

dotnet add package TCIS.Persistence.Dapper

⚙️ Configuration (appsettings.json)

Shares configuration with other Persistence modules via the ConfigurationStore section:

{
  "ConfigurationStore": {
    "ConnectionString": "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;",
    // ReadConnectionString will be prioritized for Query tasks if present
    "ReadConnectionString": "Server=myReadReplica;Database=myDataBase;User Id=myUsername;Password=myPassword;"
  }
}

🚀 Registration / Setup (Program.cs)

Note: If you are using the TCIS.Persistence.EntityFrameworkCore library, the AddTCorePersistence method automatically registers this library, so manual registration is not required.

If registering independently, you need to configure IDbConnectionFactory and IDapperContext:

using TCIS.Persistence.Data;
using TCIS.Persistence.Dapper;
using System.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

// 1. Configure Options
builder.Services.AddOptions<PersistenceOptions>()
    .Bind(builder.Configuration.GetSection("ConfigurationStore"));

// 2. Register the Connection Factory
builder.Services.AddScoped<IDbConnectionFactory>(sp => 
    new DefaultDbConnectionFactory(
        sp.GetRequiredService<IOptions<PersistenceOptions>>(), 
        connectionString => new SqlConnection(connectionString)));

// 3. Register the Dapper Context
builder.Services.AddScoped<IDapperContext, DapperContext>();

💡 Usage

Inject IDapperContext into your code (Repository, Service, CQS Handlers).

using TCIS.Persistence.Dapper;

public class ReportService
{
    private readonly IDapperContext _dapperContext;

    public ReportService(IDapperContext dapperContext)
    {
        _dapperContext = dapperContext;
    }

    public async Task<IEnumerable<ReportDto>> GetDailyReportAsync(DateTime date)
    {
        string sql = "SELECT * FROM Reports WHERE ReportDate = @Date";
        
        // The factory will automatically open the connection, execute the query, and safely dispose of the connection
        return await _dapperContext.QueryAsync<ReportDto>(sql, new { Date = date });
    }
    
    public async Task<PagedResult<UserDto>> GetUsersPagedAsync(int pageIndex, int pageSize)
    {
        string countSql = "SELECT COUNT(1) FROM Users";
        string dataSql = "SELECT * FROM Users ORDER BY Id OFFSET @Offset ROWS FETCH NEXT @PageSize ROWS ONLY";
        
        // Supports automatic paginated querying
        return await _dapperContext.QueryPageAsync<UserDto>(
            countSql, 
            dataSql, 
            pageIndex, 
            pageSize, 
            new { Offset = (pageIndex - 1) * pageSize, PageSize = pageSize });
    }
}

Key Features:

• DefaultDbConnectionFactory: Automatically provisions connections and provides automatic fallback/switching between ConnectionString and ReadConnectionString (for Queries).
• Automatic Pagination: Provides the QueryPageAsync<T> method that prepares a PagedResult<T> out-of-the-box.
• Query / Execute: Offers QueryAsync, ExecuteAsync, QuerySingleOrDefaultAsync, QueryFirstOrDefaultAsync similar to native Dapper but with safely managed connection lifecycles.