Convenções claras
Padrões compreensíveis e bons valores padrão para reduzir decisões repetidas entre APIs.
Ecossistema open source em evolução
Psalms
Clean conventions. Powerful defaults.
Uma coleção modular de bibliotecas para .NET que elimina código repetitivo, estabelece convenções seguras e acelera o desenvolvimento de APIs e microsserviços.
Visão do ecossistema
Menos repetição. Mais intenção no código.
O Psalms encapsula problemas recorrentes em pacotes independentes e extensíveis. Cada biblioteca pode ser adotada isoladamente, sem obrigar a aplicação a usar o restante do ecossistema.
Extensão sem mistério
Abstrações explícitas e pontos de substituição quando cache, persistência ou templates precisarem evoluir.
Componentes independentes
Email, autenticação e dados resolvem responsabilidades separadas e podem ser combinados apenas quando fizer sentido.
“Psalms exists to bring grace to your code. No magic, no unnecessary complexity — just best practices distilled into powerful libraries.”
Pacotes publicados
Três responsabilidades, uma mesma filosofia
Selecione um pacote para explorar o problema resolvido, as decisões arquiteturais e exemplos de integração.
Email workflows e confirmação de comandos
Psalms.AspNetCore.EmailSender
Uma biblioteca para operações que só devem ser executadas depois que o usuário confirma a ação por um link enviado por email.
Dor recorrente
O mesmo fluxo refeito em cada aplicação
Cadastro, reset de senha, alteração de email e aprovações exigem token, expiração, cache, template, envio, desserialização e invalidação após uso.
Decisão arquitetural
O comando vira a unidade do workflow
O IRequest original fica armazenado temporariamente e retorna ao pipeline do MediatR somente após a confirmação.
Arquitetura
Do pedido à execução confirmada
- 01
Usuário solicita uma operação sensível.
- 02
A API cria o comando original.
- 03
SendConfirmationEmailCommand
- 04
Um token único é gerado.
- 05
JSON +
IDistributedCache - 06
O template é resolvido pelo tipo concreto do comando.
- 07
MailKit e MimeKit enviam o link.
- 08
O usuário acessa o link.
- 09
O frontend envia o token à API.
- 10
ConfirmEmailCommand
- 11
O comando é recuperado e desserializado.
- 12
O MediatR executa o comando restaurado.
- 13
A chave é removida e não pode ser reutilizada.
Template resolver
Um template para cada tipo de comando
Cada comando pode implementar IEmailTemplate<TCommand>. O resolver identifica o tipo concreto e procura a implementação correspondente no container de Dependency Injection.
ASP.NET CoreMediatRIDistributedCacheMailKitMimeKitDIHTMLJSON
public class RegisterUserEmailTemplate
: IEmailTemplate<RegisterUserCommand>
{
public string TemplatePath => "Templates";
public string EmailType => "confirm-email";
public string Subject => "Confirm your account";
public string FrontEndPage => "confirm-email";
}services.AddScoped<
IEmailTemplate<RegisterUserCommand>,
RegisterUserEmailTemplate>();await mediator.Send(
new SendConfirmationEmailCommand(command, email)
);await mediator.Send(
new ConfirmEmailCommand(token)
);await mediator.Send(
new SendEmailCommand(
to: "user@email.com",
subject: "Welcome",
htmlPath: "Templates",
emailType: "welcome"
)
);Tokens
Temporários e de uso único
- GUID:
email-confirmation:{guid} - Armazenamento em
IDistributedCache - Expiração padrão de cinco minutos, configurável
- Remoção antes de executar o comando restaurado
Templates HTML
Templates/welcome.html
O gerador padrão lê arquivos do disco. IEmailHtmlGenerator pode ser substituído por banco de dados, cloud storage, embedded resources ou template engine; essas são extensões possíveis, não integrações incluídas.
Começar
Instalação e registro
dotnet add package Psalms.AspNetCore.EmailSenderbuilder.Services.AddPsalmsEmailSender();Onde faz sentido
Confirmação de cadastroRedefinição de senhaAlteração de emailAprovação de comandosOperações sensíveisConsentimento prévio
Autenticação, access tokens e refresh tokens
Psalms.AspNetCore.Auth.Jwt
Uma biblioteca leve para emissão de access tokens e gestão de refresh tokens com estratégias substituíveis de persistência.
Nota: o README usa Psalms.AspNetCore.Jwt como nome de apresentação; o ID publicado no NuGet inclui Auth.
Dor recorrente
JWT vai além de gerar uma string
Issuer, audience, assinatura, validade, geração segura, hash, persistência e rotação de refresh tokens precisam funcionar como um único fluxo.
Decisão arquitetural
Persistência atrás de um contrato
IPsalmsRefreshTokenRepository separa o fluxo central da tecnologia usada para guardar refresh tokens.
Componentes
Responsabilidades explícitas
PsalmsJwtTokenServiceGeração de tokens, validação e rotação.
IPsalmsRefreshTokenRepositoryContrato de persistência.
DistributedCacheRepositoryImplementação sobre IDistributedCache.
EFRefreshTokenRepositoryImplementação com Entity Framework Core.
Fluxo 01
Autenticação
- 1
Credenciais chegam à aplicação.
- 2
A identidade é validada.
- 3
Claims →
IPsalmsJwtTokenService - 4
O access token é assinado.
- 5
Um refresh token aleatório de 32 bytes é gerado.
- 6
O hash é persistido.
- 7
O cliente recebe o par.
Fluxo 02
Renovação e rotação
- 1
O cliente envia access e refresh tokens.
- 2
Token e expiração são validados.
- 3
O valor é comparado com o hash.
- 4
O fluxo solicita a exclusão do token anterior.
- 5
Um novo access token é criado.
- 6
Um novo refresh token é persistido.
- 7
O novo par retorna ao cliente.
Distributed cache
Redis · SQL Server cache
Estratégia para processos distribuídos que compartilham uma implementação de IDistributedCache.
Entity Framework
Persistência consultável
Usa IPsalmsRefreshTokenEFContext para salvar e remover tokens em banco.
Repositório próprio
Outro provedor, mesmo fluxo
A aplicação implementa IPsalmsRefreshTokenRepository sem modificar o núcleo.
Mecanismos de segurança
Camadas que reduzem risco quando bem configuradas
- Refresh token:
RandomNumberGenerator - Hash:
PasswordHasherdo ASP.NET Core Identity - Validação configurável de issuer, audience, assinatura e lifetime
- Rotação emite um novo par após validar o anterior
{
"JWT": {
"Key": "configure-via-secret-manager",
"Issuer": "your-app",
"Audience": "your-app-users",
"Expires": "1"
}
}Exemplo ilustrativo: segredos reais devem vir de secret managers, variáveis de ambiente ou mecanismo equivalente — nunca do repositório.
builder.Services.AddPsalmsJwtAuthentication(
builder.Configuration
);public class AuthService
{
private readonly IPsalmsJwtTokenService _jwt;
public AuthService(IPsalmsJwtTokenService jwt)
{
_jwt = jwt;
}
public async Task<AuthResponse> Authenticate(
IEnumerable<Claim> claims)
{
return await _jwt.GetAuthResponseAsync(claims);
}
}Começar
Instalação
dotnet add package Psalms.AspNetCore.Auth.JwtOnde faz sentido
APIs ASP.NET CoreFrontend separadoAccess + refresh tokensMicrosserviçosSistemas distribuídosPersistência substituível
Persistência, Repository e Unit of Work
Psalms.EFCore.DataManagement
A implementação Entity Framework Core do projeto Psalms.DataManagement, criada para aplicações que optam pelos padrões Repository e Unit of Work.
Dor recorrente
Acesso a dados inconsistente entre projetos
CRUD, predicados, coleções relacionadas, SaveChanges e registro no container costumam reaparecer com contratos diferentes.
Decisão arquitetural
Uma API comum sobre o DbContext
O repositório concentra operações recorrentes; a Unit of Work coordena o contexto e confirma as mudanças.
Arquitetura
Uma cadeia curta e explícita
Application Service↓IPsalmsUnitOfWork<TContext>↓IPsalmsEfCoreRepository↓Entity Framework DbContext↓Database
IPsalmsUnitOfWork<TContext>Expõe Repository, executa SaveChangesAsync e coordena o descarte do contexto.
IPsalmsEfCoreRepositoryCentraliza consultas e alterações genéricas para diferentes entidades.
DbContextMantém tracking e conversa com o provider configurado.
API confirmada
Operações públicas do pacote
CreateAsync<T>(T entity)DeleteAsync<T>(int id)GetByIdAsync<T>(int id)GetByAsync<T>(predicate)ExistsAsync<T>(predicate)GetAllAsync<T>()GetCollectionFromEntityAsync<...>(...)RepositorySaveChangesAsync()DisposeAsync()A classe concreta PsalmsEfCoreRepository também contém UpdateAsync<T>, mas a versão 1.0.0 não expõe esse método em IPsalmsEfCoreRepository; por isso ele não aparece como parte do contrato principal acima.
services.AddDbContext<AppDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("Default")));
services.AddScoped<
IPsalmsUnitOfWork<AppDbContext>,
PsalmsUnitOfWork<AppDbContext>>();public class ProductService
{
private readonly IPsalmsUnitOfWork<AppDbContext> _uow;
public ProductService(
IPsalmsUnitOfWork<AppDbContext> uow)
{
_uow = uow;
}
public async Task AddProductAsync(Product product)
{
await _uow.Repository.CreateAsync(product);
await _uow.SaveChangesAsync();
}
public async Task<Product?> GetProductAsync(int id)
{
return await _uow.Repository
.GetByIdAsync<Product>(id);
}
}services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("TestDb"));Útil para testes sem banco externo, considerando as diferenças comportamentais do provider InMemory em relação a um banco relacional real.
Começar
Instalação
dotnet add package Psalms.EFCore.DataManagementOnde faz sentido
APIs com EF CoreRepository + Unit of WorkCRUD padronizadoServiços sobre o mesmo contextoRedução de boilerplateEF Core InMemory
Arquitetura integrada
Como os pacotes podem trabalhar juntos
Um cenário possível para uma API ASP.NET Core. A integração é opcional: cada pacote continua independente e pode ser adotado sozinho.
Client↓ASP.NET Core API↓Psalms.AspNetCore.Auth.Jwt↓Psalms.AspNetCore.EmailSender↓MediatR Command Handler↓Psalms.EFCore.DataManagement↓Entity Framework Core↓Database
- JWT
Autentica o usuário e gerencia access e refresh tokens.
- EmailSender
Armazena o comando sensível e envia a confirmação.
- MediatR
Encaminha o comando restaurado ao handler.
- DataManagement
Repository e Unit of Work persistem a alteração.
Stack
Tecnologias confirmadas no ecossistema
C#.NETASP.NET CoreEntity Framework CoreMediatRJWT BearerASP.NET Core IdentityIDistributedCacheMailKitMimeKitDependency InjectionNuGetHTML templatesTestes automatizados
Evolução contínua
Bibliotecas reais, com espaço para crescer
O Psalms já possui pacotes públicos e código aberto. Novas melhorias podem entrar sem transformar cada biblioteca em uma dependência obrigatória das demais.