undrivendev/template-webapi-aspnet

Template for ASP.NET WebApi based applications/microservices using CQRS, Mediator pattern, Clean Architecture

ASP.NET Core WebApi template

This template can be used to bootstrap a working full-fledged ASP.NET Web Api project with a single CLI command (see below).

It contains what I consider to be best practices/patterns, such as CQRS, Mediator, Clean Architecture.

⭐ Like it? Give a star

If you like this project, you learned something from it or you are using it in your applications, please press the star button. Thanks!

Motivation

I found implementations of similar samples/templates to often be overly complicated and over-engineered (IMO). This is an effort to create a more approachable, more maintainable solution that can be used as a starting point for the majority of real-world projects while, at the same time, striving to reach a sensible balance between flexibility and complexity.

Features

• Based on .NET 8 to have access to the latest features
• Simplified Startup.cs hosting model
• CQRS with full separation between Read and Write repositories
• Simple Mediator abstraction for CQRS and implementation relying on the chosen Dependency Injection container (see HumbleMediator)
• Project structure following Clean Architecture principles
• Read repositories based on Dapper (Raw SQL) for fastest query execution times
• Write repositories based on Entity Framework Core to take advantage on the built-in change tracking mechanism
• PostgreSQL open source database as data store (easily replaceable with any Entity Framework-supported data stores)
• Database configured to use snake_case naming convention via EFCore.NamingConventions
• Migrations handled by Entity Framework and automatically applied during startup (in dev environment)
• SimpleInjector open-source DI container integration for advanced service registration scenarios
• Aspect-oriented programming using Decorators on the above-mentioned mediator
  • Logging: QueryHandlerLoggingDecorator and CommandHandlerLoggingDecorator
  • Caching: QueryHandlerCachingDecorator
  • Validation: CommandHandlerValidationDecorator and QueryHandlerValidationDecorator
• Structured logging using the standard MEL interface with the open-source Serilog logging library implementation
• Cache-friendly Dockerfile
• Expressive testing using xUnit and FluentAssertions
• Integration testing using real database implementation with Testcontainers
• Central Package Management

Usage

1. Bootstrap your project

Here are a couple of ways to bootstrap a new project starting from this template.

Cookiecutter template

Probably the best way to bootstrap this project, with just one command, but some dependencies are needed.

1. Make sure Python is installed
2. Install cookiecutter.
3. Bootstrap initial project with the following command: cookiecutter gh:undrivendev/template-webapi-aspnet --checkout cookiecutter

GitHub template

You could use this project as a GitHub template and clone it in your personal account by using the Use this template green button on the top of the page.

Then you'd have to rename classes and namespaces.

2. Apply initial migration

When you have the project ready, it's time to create the initial migration using dotnet-ef (or if you use Rider, like me, you can try this plugin).

Here's an example command using the default solution name, if you changed it you would have to adapt it accordingly:

dotnet ef migrations add --project ./src/Infrastructure/Infrastructure.csproj --context AppDbContext --startup-project ./src/Api/Api.csproj InitialMigration

The above migration is applied automatically during startup in the dev environment.

3. Start the application

The default API endpoints should be testable from the Swagger UI.

Enjoy!