Open Source Solution Template For .NET9 Microservice
Read the Documentation »
Report Bug
·
Request Feature
.
Request Documentation
Genocs .NET Web API Microservice Template is a starting point for your next .NET9 Clean Architecture Project that incorporates the most essential packages and features your projects will ever need including out of the box Multi-Tenancy support.
As the name suggests, this is an API / Server Template. You can find other Client Template that consume this API under
@genocshandle.
- Find
Blazor Wasm Templatehere - Blazor Wasm Template
The template can be used with the genocs cli, dotnet new command or with the Visual Studio 2022, Visual Studio Code IDEs.
- ✨ Features
- Prerequisites
- Quick Start
- Template Options
- Architecture Overview
- Development Workflow
- Examples
- Troubleshooting
- Community & Support
- Contributing
- License
- Clean architecture template spanning Domain, Application, Infrastructure, and WebApi projects.
- Built-in multi-tenant foundation (Finbuckle) with per-tenant and shared database strategies.
- Production-ready infrastructure: background jobs, caching, localization, auditing, and real-time notifications.
- Developer tooling out of the box: Makefile automation, Terraform modules, Docker Compose, Postman and Thunder collections.
- .NET 9 SDK (latest version)
- IDE (choose one):
- Visual Studio 2022 (recommended)
- Visual Studio Code with C# extension
- JetBrains Rider
- Optional for development:
- Docker Desktop for containerization
- MongoDB, SQL Server
- NodeJS (16+)
# Install the latest version
dotnet new install Genocs.Microservice.Template
# Or install a specific version
dotnet new install Genocs.Microservice.Template::3.1.1
# View all available options
dotnet new gnx-microservice --help
# Example with custom options
dotnet new gnx-microservice\
--name "CompanyName.ServiceName" \The template generates a solution with the following structure:
src/
├── Application/ # CQRS commands, queries, validations, business workflows
├── Contracts/ # Shared DTOs, integration events, notifications, permissions
├── Domain/ # Entities, aggregates, domain events, value objects
├── Infrastructure/ # EF Core persistence, caching, jobs, external integrations
├── Infrastructure.Tests/ # Automated tests for persistence, validation, caching
├── Migrators.MSSQL/ # SQL Server migrations and tooling
├── Migrators.MySQL/ # MySQL migrations and tooling
├── Migrators.Oracle/ # Oracle migrations and tooling
├── Migrators.PostgreSQL/ # PostgreSQL migrations and tooling
├── Migrators.SqLite/ # SQLite migrations and tooling
└── WebApi/ # Host application, configuration, controllers, SignalR hub- ✅ Built on .NET 9 with Clean Architecture layering (Domain, Application, Infrastructure, WebApi).
- ✅ Domain-driven design with CQRS (MediatR), Mapster mappings, FluentValidation, and specification support.
- ✅ Multi-tenancy powered by Finbuckle with tenant management APIs, shared/per-tenant databases, and subscription upgrades.
- ✅ Database providers for PostgreSQL, SQL Server, MySQL, Oracle, and SQLite via Entity Framework Core 9.
- ✅ Optimized read path with integrated Dapper repository alongside EF Core.
- ✅ Background job processing through Hangfire with dashboard support and multi-provider storage.
- ✅ Observability with Serilog (console, file, Seq, Elasticsearch, AWS), structured logging, and auditing pipeline.
- ✅ Distributed caching abstractions with StackExchange Redis and per-tenant cache segregation.
- ✅ Authentication via JWT bearer tokens and Azure AD, plus fine-grained permission-based authorization.
- ✅ Localization using OrchardCore PO files, configurable cultures, and UI-ready resource catalogs.
- ✅ OpenAPI/NSwag integration for client generation, versioned APIs, and security schemas.
- ✅ Excel export (ClosedXML), file storage abstractions, Razor-based email templates, and MailKit delivery.
- ✅ Real-time notifications with SignalR and Redis backplane support.
- ✅ Tooling for real-world deployments: Makefile automation, Docker Compose samples, Terraform modules, Postman & Thunder collections.
- ✅ Code analysis & StyleCop configuration, plus Infrastructure-focused automated tests.
- ✅ Comprehensive documentation hosted on genocs netlify and an active community.
Check nuget is installed on your machine. To download nuget, visit nuget.org
- Download the nuget latest version. At the time of writing this, the latest version is nuget.exe v6.7.0
- Add the nuget.exe to your PATH environment variable.
- run the following commands
To build the package run the following commands:
# To clone the repository
git clone https://github.com/Genocs/microservice-template
cd microservice-template
# To pack and build the template
dotnet pack ./src/Package.Template.csproj -p:PackageVersion=3.1.1 --configuration Release --output ./out
# To install the template
dotnet new install ./out/Genocs.Microservice.Template.3.1.1.nupkg
# To get the list of available templates
dotnet new gnx-microservice --help
# To uninstall the template
dotnet new uninstall Genocs.Microservice.Template
# Example of creating a new project with full functionality
dotnet new gnx-microservice --name {CompanyName.ServiceName} -gc fullUseful commands:
# How to get the list of installed templates
dotnet new -u
# How to get the list of templates
dotnet new listRead Documentation related to this template here - Template Documentation
Feel free to contribute to the Documentation Repository - Contribute Documentation
To get started with this Template, here are the available options:
- Install using the
genocs clitool. Use this for latest release versions of the Template only. - Install using the
dotnet new installtool. Use this for any versions of the Template. - Fork the Repository. Use this if you want to always keep your version of the Template up-to date with the latest changes.
Make sure that your DEV enviroment is setup, Read the Development Environment Guide
After you have installed .NET, you will need to install the cli console tool.
dotnet tool install -g genocs.cli
genocs installThis install the CLI tools and the associated Templates. You are now ready to create your first project!
Here's how you would create a Solution using the Genocs .NET WebAPI Template.
Simply navigate to a new directory (wherever you want to place your new solution), and open up bash prompt at the opened directory.
Run the following command. Note that, in this demonstration, I am naming my new solution as CompanyName.ProjectName.ServiceName.
genocs micro-webapi [n|new] CompanyName.ProjectName.ServiceNameThis will create a new .NET9 Web API solution for you using the template. For further steps and details, Read the Getting Started Guide
To update the tool & templates, run the following commands
dotnet tool update genocs.cli --global
genocs updateYou would probably need to take this approach if you want to keep your source code up to date with the latest changes. To get started based on this repository, you need to get a copy locally. You have three options: fork, clone, or download.
- Make a fork of this repository in your GitHub account.
- Create your new
microservice-templatepersonal project by cloning the forked repository on your personal GitHub. - Setup an upstream remote on your personal project pointing to your forked repository using command
git remote add upstream https://github.com/{githubuseraccount}/microservice-templateandgit remote set-url --push upstream DISABLE
For step by step instructions, follow: this and this.
So, for a better developer experience, I have added Makefile into the solution. Now that our solution is generated, let's navigate to the root folder of the solution and open up a command terminal.
To build the solution:
make buildBy default, the solution is configured to work with postgresql database (mainly because of the OS licensing). So, you will have to make sure that postgresql database instance is up and running on your machine. You can modify the connection string to include your username and password. Connections strings can be found at src/WebApi/Configurations/database.json and src/WebApi/Configurations/hangfire.json. Once that's done, let's start up the API server.
make startThat's it, the application would connect to the defined postgresql database and start creating tables, and seed required data.
For testing this API, we have 3 options:
- Swagger @
localhost:5001/swagger - Postman collections are available
./postman - ThunderClient for VSCode. You will have to install the Thunderclient extension for VSCode.
The default credentials to this API is:
{
"email": "admin@root.com",
"password": "123Pa$$word!"
}Open up Postman, Thunderclient or Swagger.
identity -> get-token
This is a POST Request. Here the body of the request will be the JSON (credentials) I specified earlier. And also, remember to pass the tenant id in the header of the request. The default tenant id is root.
Here is a sample CURL command for getting the tokens.
curl -X POST \
'https://localhost:5001/api/tokens' \
--header 'Accept: */*' \
--header 'tenant: root' \
--header 'Accept-Language: en-US' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "admin@root.com",
"password": "123Pa$$word!"
}'
And here is the response.
{
"token": "<your token>",
"refreshToken": "<your refresh token>",
"refreshTokenExpiryTime": "2025-01-01T00:00:00.0000000Z"
}You will need to pass the token in the request headers to authenticate calls to the Genocs API!
For further steps and details, Read the Getting Started Guide
The project, being .NET9, it is configured to have built-in support for containerization. That means, you really don't need a dockerfile to containerize the webapi.
To build a docker image, all you have to do is, ensure that docker-desktop or docker instance is running. And run the following command at the root of the solution.
make publishYou can also push the docker image directly to dockerhub or any supported registry by using the following command.
make publish-to-hubYou will have to update your docker registry/repo url in the Makefile though!
This project also comes with examples of docker compose files, where you can spin up the webapi and database instance in your local containers with the following commands.
#docker compose up - Boots up the webapi & postgresql container
make dcu
#docker compose down - Shuts down the webapi & postgresql containers
make dcdThere are also examples for MySQL & MSSQL variations. You can find the compose files under the ./infrastructure folder. Read more about the compose scenarios in infrastructure/docker/README.md.
We do support cloud deployment to AWS using terraform. The terraform files are available at the ./terraform folder.
- Install Terraform
- Install & Configure AWS CLI profiles to allow terraform to provision resources for you. Please see this video about AWS Credentials Management.
In brief, the terraform folder has 2 sub-folders:
- backend
- environments/staging
The Backend folder is internally used by Terraform for state management and locking. There is a one-time setup you have to do against this folder. Navigate to the backend folder and run the command.
terraform init
terraform apply -auto-approveThis would create the required S3 Buckets and DDB table for you.
Next is the environments/staging folder. Here too, run the following command.
terraform initOnce done, you can go the terraform.tfvars file to change the variables like:
- project tags
- docker image name
- ecs cluster name and so on.
After that, simply go back to the root of the solution and run the following command.
make taThis will evaluate your terraform files and create a provision plan for you. Once you are ok, type in yes and the tool will start to deploy your .NET Microservice project as containers along with a RDS PostgreSQL instance. You will be receiving the hosted api url once the provisioning is completed!
To destroy the deployed resources, run the following
make tdParticipate in QNA & General Discussions
View Complete Changelogs.
This project is licensed with the MIT license.
Has this Project helped you learn something New? or Helped you at work?
Here are a few ways by which you can support.
- ⭐ Leave a star!
- 🥇 Recommend this project to your colleagues.
- 🦸 Do consider endorsing me on LinkedIn for ASP.NET Core - Connect via LinkedIn
- ☕ If you want to support this project in the long run, consider buying me a coffee!
This project exists thanks to all the people who contribute. Submit your PR and join the team!
Become a financial contributor and help me sustain the project.
Support the Project on Opencollective
