Create

Método Create: Implementação e Organização dos Repositórios

Estrutura do Diretório de Repositórios

Um diretório denominado Repositories será criado, contendo uma classe chamada ProductRepository. Esta implementação inicial é considerada básica, não representando a versão final da arquitetura.

Convenção de Nomenclatura

O sufixo Repository passa a ser utilizado para cada modelo existente no sistema, estabelecendo um padrão consistente de nomenclatura. Para o modelo Product, a classe correspondente será ProductRepository.

Implementação do Método Create

No núcleo do ProductRepository, são implementados métodos de forma assíncrona, visando otimização de performance e responsividade do sistema. Como exemplo, será implementado o método CREATE.

Assinatura do Método

public async Task<Product> CreateAsync
    (Product product, CancellationToken cancellationToken = default)

Características da assinatura:

1. Sufixo Async: Métodos assíncronos utilizam o sufixo Async para clareza semântica

2. Tipo de Retorno: Task<Product> permite retornar o produto após persistência

3. Parâmetros:

• Product product: entidade a ser cirada

• CancellationToken cancellationToken = default: Token para cancelamento de operações assíncronas

Considerações sobre o Tipo de Retorno

O tipo de retorno pode variar conforme a necessidade:

• Task<void> ou Task: quando nenhum retorno é necessário

• Task<Product>: quando se deseja retornar a entidade persistida

No cenário atual, opta-se por retornar Task<Product> pois o Entity Framework, ao persistir a entidade, gera automaticamente o valor do campo Id (quando configurado como identity no banco de dados), permitindo que este valor seja imediatamente disponibilizado.

Injeção de Dependência e Primary Constructor

O AppDbContext é injetado utilizando o recurso de Primary Constructor introduzido em versões recentes do C#:

public class ProductRepository(AppDbContext context)
{
    // O campo 'context' está automaticamente disponível
}

Esta abordagem elimina a necessidade de declaração explícita de campos e construtores, simplificando a implementação.

Implementação do Método CreateAsync

public async Task<Product> CreateAsync
    (Product product, CancellationToken cancellationToken = default)
{
    await context.Products.AddAsync(product, cancellationToken);
    await context.SaveChangesAsync(cancellationToken);
    return product;
}

Explicação ponto a ponto

Assinatura do método

• public O método é exposto publicamente e pode ser utilizado por outras camadas da aplicação, como serviços de aplicação ou controladores.

• async Indica que o método é assíncrono, permitindo o uso de await para operações de I/O sem bloquear a thread.

• Task<Product> Retorna uma operação assíncrona que, ao ser concluída, fornece a instância de Product persistida no banco de dados.

• CreateAsync Nome que expressa claramente a intenção do método: criar e persistir uma nova entidade Product de forma assíncrona.

• Parâmetros:

  • Product product Instância da entidade Product que será adicionada ao banco de dados.

  • CancellationToken cancellationToken = default Token opcional utilizado para cancelar a operação assíncrona, caso necessário.

---

Corpo do método

await context.Products.AddAsync(product, cancellationToken)

• Adiciona a entidade product ao DbContext de forma assíncrona.

• O Entity Framework Core:

  • Anexa a entidade ao contexto.

  • Define seu estado como Added.

• A entidade será inserida no banco de dados somente quando SaveChangesAsync for executado.

• O método assíncrono é especialmente útil quando o provedor de banco realiza operações adicionais durante a adição (como geração de chaves).

---

await context.SaveChangesAsync(cancellationToken)

• Persiste no banco de dados todas as alterações pendentes no DbContext.

• Executa o INSERT correspondente à entidade marcada como Added.

• O cancellationToken permite interromper a operação antes de sua conclusão.

---

return product

• Retorna a instância de Product após a persistência.

• Caso o banco gere valores automaticamente (por exemplo, chave primária, colunas calculadas ou valores default), esses valores já estarão preenchidos no objeto retornado.

---

Considerações e boas práticas

• Validação de dados: recomenda-se validar a entidade antes da persistência (ex.: regras de domínio, invariantes e constraints).

• Transações: SaveChangesAsync é executado em transação implícita; para cenários mais complexos, podem ser utilizadas transações explícitas.

• Exceções: trate exceções relacionadas a violações de integridade (ex.: chaves únicas) em camadas superiores.

• Cancelamento: a propagação do CancellationToken contribui para previsibilidade e controle em fluxos assíncronos.

• Retorno da entidade: retornar a entidade criada facilita confirmações, logging e respostas em APIs REST.

Comportamento do Entity Framework

Quando o campo Id é definido como int (e configurado como identity no banco), o valor é gerado pelo SGBD durante a inserção. O Entity Framework recupera automaticamente este valor após a execução do SaveChangesAsync(), preenchendo a propriedade Id da entidade.

Fluxos

Versão Simplificada do Fluxo Principal

Fluxo com Transições Detalhadas

Fluxo de Estados da Entidade (EntityState)

Fluxo com Transações do Entity State Enum

Fluxo com Tratamento de Erros

Considerações sobre Unit of Work

Posteriormente será abordado o padrão Unit of Work, que o Entity Framework já implementa internamente através do DbContext. Cada instância do contexto representa uma unidade de trabalho, gerenciando transações e consistência de dados.

Token de Cancelamento (CancellationToken)

A utilização de CancellationToke em métodos assíncronos é recomendada por várias razões:

1. Cancelamento de Operações Longas: Permite interromper operações demoradas

2. Execução em Batch: Especialmente útil em processamentos em lote

3. Responsividade: Permite que a aplicação responda a solicitações de cancelamento do usuário

4. Gerenciamento de Recursos: Libera recursos quando operações são canceladas

O parâmetro default utiliza o token padrão quando nenhum é especificado explicitamente.

Com esta implementação, o método CreateAsync está finalizado e pronto para ser utilizado pelos endpoints da API, mantendo a separação de responsabilidades e preparando o sistema para futuras evoluções arquiteturais.