Rochas.DapperRepository 1.6.6

README - DapperRepository

Repositório genérico para acesso a dados usando Dapper, com foco em simplicidade, performance e baixo acoplamento.
Segue o padrão de Repositório e Unidade de Trabalho descritos por Martin Fowler, sem impor novas linguagens, controle de estado ou proxies dinâmicos.

Este componente foi desenhado para uso direto com POCOs decorados com metadados que orientam a consulta, persistência e relacionamento entre entidades.

📌 Instalação

dotnet add package Rochas.DapperRepository

📌 Nome da Interface

IGenericRepository<T>

📌 Exemplo de uso típico — Instância manual:

var connString = "Data Source=sample.db;Cache=Shared";

using var repo = new GenericRepository<SampleEntity>(DatabaseEngine.SQLite, connString);

var result = repo.Search('Celulares');

📌 Exemplo de Registro no DI

services.AddScoped<IGenericRepository<SampleEntity>>(provider =>
    new GenericRepository<SampleEntity>(
        DatabaseEngine.SQLite,
        configuration.GetConnectionString("Default")));

Implementação em serviço de domínio:

private readonly IGenericRepository<SampleEntity> _repo;

    public SampleService(IGenericRepository<SampleEntity> repo)
    {
        _repo = repo;
    }

📌 Exemplo de Entidade (Anotações de Metadados)

Usando PascalCase (convencional)

[Table] e [Column] são opcionais. Quando omitidos, o componente usa o nome da classe para a tabela e o nome da propriedade para a coluna (PascalCase):

[Cacheable]
public class SampleEntity
{
    [Key]
    [AutoGenerated]
    public int Id { get; set; }

    [RangeFilter(LinkedRangeProperty = "CreationDateEnd")] 
    public DateTime CreationDate { get; set; } 
    
    [NotMapped] 
    public DateTime CreationDateEnd { get; set; }

    [Filterable]
    public string Name { get; set; }

    public int Age { get; set; }

    public bool Active { get; set; }

    [RelatedEntity(Cardinality = RelationCardinality.OneToMany, 
                   ForeignKeyAttribute = "ParentId")]
    public IList<ChildEntity> Childs { get; set; }
}

public class ChildEntity
{
    [Key]
    public int Id { get; set; }

    public int ParentId { get; set; }

    public string Description { get; set; }
}

Usando nomes customizados

Quando necessário (ex.: banco com nomes snake_case ou colunas com nomes diferentes das propriedades), use [Table] e [Column]:

[Table("sample_entities")]
public class SampleEntity
{
    [Key]
    [AutoGenerated]
    public int Id { get; set; }

    [Column("creation_date")]
    public DateTime CreationDate { get; set; }

    [Column("name")]
    public string Name { get; set; }
}

Regra: Se [Table] não existir, usa o nome da classe. Se [Column] não existir, usa o nome da propriedade.

🔧 Métodos CRUD disponíveis no repositório

➕ Add (inclusão de entidade no repositório)

var entity = new SampleEntity
{
    Name = "Renato Rocha",
    Email = "rrocha@example.com"
};

repo.Add(entity);

➕ AddRange (inclusão de múltiplas entidades no repositório)

var list = new List<SampleEntity>() { 
                new SampleEntity() {
                    Name = "Renato Rocha",
                    Resume = "Software Architect"
                },
                new SampleEntity() {
                    Name = "Roberto Dias",
                    Resume = "Infra DevOps"
                },
            };

repo.AddRange(list);

✏️ Update (atualização de entidade do repositório)

var filter = new SampleEntity { DocNumber = 12345 };
var entityToUpdate = await repo.Get(filter);
entityToUpdate.Age = 40;

int affected = await repo.Update(entityToUpdate, filter);

❌ Remove (remoção de entidade do repositório)

var filterToRemove = new SampleEntity { DocNumber = 12345 };

int removed = await repo.Remove(filterToRemove);

🔍 Query (consultas por filtro tipado)

var all = await repo.Query(new SampleEntity()); //Listar todos

var filter = new SampleEntity { Name = "Roberto", Email = "gmail.com" };
var results = await repository.Query(filter, recordsLimit:10);

Utilize o parâmetro booleano filterConjunction para definir o comportamento dos atributos na consulta, conjunção lógica E (ligado), disjunção lógica OU (desligado).

Quando a conjunção é utilizada o critério aplicado é de igualdade, do contrário semelhança.

🔍 Query (consultas por intervalo [RangeFilter])

var filter = new SampleEntity
{
    CreatedAtStart = new DateTime(2024, 01, 01),
    CreatedAtEnd   = new DateTime(2024, 12, 31)
};

var results = await repository.Query(filter);

Somente atributos marcados com [RangeFilter] e referência ao atributo auxiliar.

🔎 Search (buscas usando [Filterable])

var results = await repository.Search("Rua Bruchelas");

Somente atributos marcados com [Filterable] entram automaticamente na busca.

📄 SearchPaginated (buscas paginadas com [Filterable])

Retorna PaginatedResult<T> com items, contagem total e metadados de paginação.

var result = await repository.SearchPaginated(
    criteria: "Paulo",
    page: 1,
    pageSize: 20,
    sortAttributes: "Name",
    orderDescending: false
);

Console.WriteLine($"Total: {result.TotalCount}");
Console.WriteLine($"Página {result.Page} de {result.PageCount}");

foreach (var item in result.Items)
{
    Console.WriteLine(item.Name);
}

PaginatedResult<T>

public class PaginatedResult<T>
{
    public IReadOnlyList<T> Items { get; set; }
    public int TotalCount { get; set; }
    public int Page { get; set; }
    public int PageSize { get; set; }
    public int PageCount => PageSize > 0 ? (int)Math.Ceiling((double)TotalCount / PageSize) : 0;
}

📄 QueryPaginated (consultas paginadas por filtro tipado)

var filter = new SampleEntity { Active = true };

var result = await repository.QueryPaginated(
    filter,
    page: 1,
    pageSize: 10,
    sortAttributes: "Name",
    orderDescending: true,
    filterConjunction: true
);

foreach (var item in result.Items)
{
    Console.WriteLine($"{item.Name} - Age: {item.Age}");
}

Sincrono

var result = repository.SearchPaginatedSync("termo", page: 1, pageSize: 10);
var result = repository.QueryPaginatedSync(filter, page: 1, pageSize: 10);

🔗 Leitura automática da composição usando [RelatedEntity]

repos.Query(filterEntity, loadComposition: true);

Configuração de relacionamentos ( 1-1 , 1->N , N<-1 , N<->N ):

[RelatedEntity(Cardinality = RelationCardinality.OneToOne, 
               ForeignKeyAttribute = "ParentId")] 
public <ChildEntity> Child { get; set; }

[RelatedEntity(Cardinality = RelationCardinality.OneToMany, 
               ForeignKeyAttribute = "ParentId")] 
public IList<ChildEntity> Childs { get; set; }

⚡ Cache Plugável (ICacheProvider)

O componente oferece provedores de cache intercambiáveis via ICacheProvider. O comportamento padrão permanece in-memory (InMemoryCacheProvider), mas é possível injetar Redis, Garnet ou canais de replicação sem alterar o código do repositório.

Ativando o cache na entidade

[Cacheable]
[Table("sample_entities")]
public class SampleEntity { ... }

É possível ligar/desligar o cache no construtor:

var repos = new GenericRepository<SampleEntity>(DatabaseEngine.SQLite, connString, useCache: true);

InMemoryCacheProvider (padrão)

DataCache.Initialize(memorySizeLimit: 100); // MB
DataCache.Initialize();                      // sem limite

DistributedCacheProvider (Redis / Garnet)

Placeholder para implementação com Microsoft.Extensions.Caching.StackExchangeRedis ou Microsoft.Garnet (Redis-compatible in-memory da Microsoft).

DataCache.Initialize(new DistributedCacheProvider("localhost:6379"));

CompositeCacheProvider (L1 InMemory + L2 Distribuído)

Para alta disponibilidade com múltiplas instâncias:

DataCache.Initialize(new CompositeCacheProvider(
    new InMemoryCacheProvider(),
    new DistributedCacheProvider("redis:6379")));

L1 local (microssegundos) → L2 compartilhado entre pods (milissegundos) → banco SQL.

PersistenceChannelCacheProvider (Replicação Master→Slave)

Canal de persistência assíncrona para clusters SQL master-slave. O master publica no canal; múltiplos consumidores (slaves) persistem nos seus bancos.

// Master
var localCache = new InMemoryCacheProvider();
var channel = new PersistenceChannelCacheProvider(localCache);
DataCache.Initialize(channel);

// Slave (consumer)
await foreach (var msg in channel.ConsumeAsync(ct))
{
    switch (msg.Action)
    {
        case ChannelAction.Put:
            slaveRepo.AddSync(msg.CacheItem);
            break;
        case ChannelAction.Del:
            slaveRepo.RemoveSync(msg.CacheKey);
            break;
    }
}

Backpressure: BoundedChannelFullMode.Wait — não perde mensagens se o canal lotar.