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.

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

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.

• Based on .NET 10 to have access to the latest features
• Minimal hosting model (top-level statements in Program.cs)
• 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 and write repositories based on Entity Framework Core, behind tech-agnostic IReadRepository/IWriteRepository interfaces — Application/Core never reference EF, so a repository can be backed by Dapper or raw ADO.NET without touching business logic
• Read repositories ship built-in pagination, sorting, and free-text search scaffolding (PagedResult<T>, ListAsync)
• 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 with a /health container HEALTHCHECK
• Expressive testing using xUnit and AwesomeAssertions
• Integration testing using real database implementation with Testcontainers
• Central Package Management
• Continuous integration via GitHub Actions: build, dependency vulnerability scan with grype, and Docker image build
• pre-commit hooks: C# formatting with CSharpier, secret scanning with gitleaks, and general file-hygiene checks

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

The easiest way to create a new project from this template:

dotnet new install .
dotnet new webapi-undrivendev -n YourProjectName -o ./YourProjectName

👉 See the complete guide: TEMPLATE-SETUP.md

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

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.

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/WebApi/WebApi.csproj InitialMigration

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

Enable tests in CI: the integration tests create their schema by migrating on startup, so they need at least one migration. Once you've added the migration above, uncomment the dotnet test step in .github/workflows/ci.yml to run the full suite on every pull request.

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

Enjoy!

This template ships a CI workflow at .github/workflows/ci.yml that runs on every pull request: it restores and builds the solution, scans dependencies with grype, and builds the Docker image. The dotnet test step is commented out until you add your first migration (see step 2).

It does not ship a release/deployment pipeline — deploy targets vary too much to template usefully. You need to create your own: typically, on push to main, build and push the image from src/WebApi/Dockerfile to your container registry, then trigger a deploy to your host.