{"id":22929924,"url":"https://github.com/genocs/microservice-template","last_synced_at":"2025-08-12T14:32:54.803Z","repository":{"id":196176862,"uuid":"694802726","full_name":"Genocs/microservice-template","owner":"Genocs","description":"The microservice template for clean architecture web api","archived":false,"fork":false,"pushed_at":"2024-11-30T16:16:11.000Z","size":3216,"stargazers_count":2,"open_issues_count":5,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-30T17:26:41.183Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Genocs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"genocs","custom":["https://www.buymeacoffee.com/genocs"]}},"created_at":"2023-09-21T18:13:31.000Z","updated_at":"2024-10-31T08:54:52.000Z","dependencies_parsed_at":"2023-09-22T08:30:28.152Z","dependency_job_id":"7356c518-ba50-4f6d-9774-2a931fa3a981","html_url":"https://github.com/Genocs/microservice-template","commit_stats":null,"previous_names":["genocs/microservice-template"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genocs%2Fmicroservice-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genocs%2Fmicroservice-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genocs%2Fmicroservice-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genocs%2Fmicroservice-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Genocs","download_url":"https://codeload.github.com/Genocs/microservice-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229690636,"owners_count":18108261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-14T10:19:43.656Z","updated_at":"2025-08-12T14:32:54.760Z","avatar_url":"https://github.com/Genocs.png","language":"C#","funding_links":["https://opencollective.com/genocs","https://www.buymeacoffee.com/genocs","https://www.buymeacoffee.com/genocs)!"],"categories":[],"sub_categories":[],"readme":"\u003c!-- PROJECT SHIELDS --\u003e\n[![License][license-shield]][license-url]\n[![Build][build-shield]][build-url]\n[![Packages][package-shield]][package-url]\n[![Downloads][downloads-shield]][downloads-url]\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![Discord][discord-shield]][discord-url]\n[![Gitter][gitter-shield]][gitter-url]\n[![Twitter][twitter-shield]][twitter-url]\n[![Twitterx][twitterx-shield]][twitterx-url]\n[![LinkedIn][linkedin-shield]][linkedin-url]\n\n[license-shield]: https://img.shields.io/github/license/Genocs/microservice-template?color=2da44e\u0026style=flat-square\n[license-url]: https://github.com/Genocs/microservice-template/blob/main/LICENSE\n[build-shield]: https://github.com/Genocs/microservice-template/actions/workflows/build_and_test.yml/badge.svg?branch=main\n[build-url]: https://github.com/Genocs/microservice-template/actions/workflows/build_and_test.yml\n[package-shield]: https://img.shields.io/badge/nuget-v.2.3.3-blue?\u0026label=latests\u0026logo=nuget\n[package-url]: https://github.com/Genocs/microservice-template/actions/workflows/build_and_test.yml\n[downloads-shield]: https://img.shields.io/nuget/dt/Genocs.Microservice.Template.svg?color=2da44e\u0026label=downloads\u0026logo=nuget\n[downloads-url]: https://www.nuget.org/packages/Genocs.Microservice.Template\n[contributors-shield]: https://img.shields.io/github/contributors/Genocs/microservice-template.svg?style=flat-square\n[contributors-url]: https://github.com/Genocs/microservice-template/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/Genocs/microservice-template?style=flat-square\n[forks-url]: https://github.com/Genocs/microservice-template/network/members\n[stars-shield]: https://img.shields.io/github/stars/Genocs/microservice-template.svg?style=flat-square\n[stars-url]: https://img.shields.io/github/stars/Genocs/microservice-template?style=flat-square\n[issues-shield]: https://img.shields.io/github/issues/Genocs/microservice-template?style=flat-square\n[issues-url]: https://github.com/Genocs/microservice-template/issues\n[discord-shield]: https://img.shields.io/discord/1106846706512953385?color=%237289da\u0026label=Discord\u0026logo=discord\u0026logoColor=%237289da\u0026style=flat-square\n[discord-url]: https://discord.com/invite/fWwArnkV\n[gitter-shield]: https://img.shields.io/badge/chat-on%20gitter-blue.svg\n[gitter-url]: https://gitter.im/genocs/\n[twitter-shield]: https://img.shields.io/twitter/follow/genocs?color=1DA1F2\u0026label=Twitter\u0026logo=Twitter\u0026style=flat-square\n[twitter-url]: https://twitter.com/genocs\n[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=flat-square\u0026logo=linkedin\u0026colorB=555\n[linkedin-url]: https://www.linkedin.com/in/giovanni-emanuele-nocco-b31a5169/\n[twitterx-shield]: https://img.shields.io/twitter/url/https/twitter.com/genocs.svg?style=social\n[twitterx-url]: https://twitter.com/genocs\n\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Genocs/microservice-template\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Genocs/microservice-template/main/assets/genocs-library-logo.png\" alt=\".NET Microservice Template\"\u003e\n  \u003c/a\u003e\n  \u003ch3 align=\"center\"\u003e.NET Microservice Template\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\n    Open Source Solution Template For .NET9 Microservice\n    \u003cbr /\u003e\n    \u003ca href=\"https://genocs-blog.netlify.app/microservice-template/general/getting-started/\"\u003e\u003cstrong\u003eRead the Documentation »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/Genocs/microservice-template/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/Genocs/microservice-template/issues\"\u003eRequest Feature\u003c/a\u003e\n    .\n    \u003ca href=\"https://github.com/Genocs/microservice-template/issues\"\u003eRequest Documentation\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Genocs .NET Web API Microservice Template\n\nGenocs .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.\n\n\u003e As the name suggests, this is an API / Server Template. You can find other Client Template that consume this API under `@genocs` handle.\n\u003e - Find `Blazor Wasm Template` here - [Blazor Wasm Template](https://github.com/Genocs/blazor-wasm-template)\n\nThe template can be used with the `genocs cli`, `dotnet new` command or with the `Visual Studio 2022`, `Visual Studio Code` IDEs.\n\n\n## Goals\n\nThe goal of this repository is to provide a complete and feature-rich starting point for any .NET Developer / Team to kick-start their next major project using .NET9 Microservices architecture. This also serves the purpose of learning advanced concepts and implementations such as `Multitenancy, CQRS, Onion Architecture, Clean Coding standards, Docker Concepts, Cloud Deployments with Terraform to AWS, CI/CD Pipelines \u0026 Workflows` and so on.\n\n## Features\n\n- :white_check_mark: Built on [.NET9](https://dotnet.microsoft.com/en-us/)\n- :white_check_mark: Follows Clean Architecture Principles\n- :white_check_mark: Domain Driven Design\n- :white_check_mark: Cloud Ready. Can be deployed to AWS Infrastructure as ECS Containers using Terraform\n- :white_check_mark: Docker-Compose File Examples\n- :white_check_mark: Documented at [genocs netlify](https://genocs-blog.netlify.app)\n- :white_check_mark: Multi Tenancy Support with [Finbuckle](https://www.finbuckle.com/)\n  - :white_check_mark: Create Tenants with Multi Database / Shared Database Support\n  - :white_check_mark: Activate / Deactivate Tenants on Demand\n  - :white_check_mark: Upgrade Subscription of Tenants - Add More Validity Months to each tenant!\n- :white_check_mark: Supports MySQL, MSSQL, Oracle, PostgreSQL, SQLite\n- :white_check_mark: Uses [Entity Framework Core 9.0](https://learn.microsoft.com/en-us/ef/core/) as DB Abstraction\n- :white_check_mark: Flexible Repository Pattern\n- :white_check_mark: [Dapper](https://www.learndapper.com/) Integration for Optimal Performance\n- :white_check_mark: Serilog Integration with various Sinks - File, SEQ, Kibana\n- :white_check_mark: OpenAPI - Supports Client Service Generation\n- :white_check_mark: Mapster Integration for Quicker Mapping\n- :white_check_mark: API Versioning\n- :white_check_mark: Response Caching - Distributed Caching + REDIS\n- :white_check_mark: Fluent Validations\n- :white_check_mark: Audit Logging\n- :white_check_mark: Advanced User \u0026 Role Based Permission Management\n- :white_check_mark: Code Analysis \u0026 StyleCop Integration with Rulesets\n- :white_check_mark: JSON Based Localization with Caching\n- :white_check_mark: Hangfire Support - Secured Dashboard\n- :white_check_mark: File Storage Service\n- :white_check_mark: Test Projects\n- :white_check_mark: JWT \u0026 Azure AD Authentication\n- :white_check_mark: MediatR - CQRS\n- :white_check_mark: SignalR Notifications\n- :white_check_mark: MassTransit Integration\n- :white_check_mark: \u0026 Much More\n\n## Documentation\n\nRead Documentation related to this template here - [Template Documentation](https://genocs-blog.netlify.app/microservice-template/)\n\n\u003e Feel free to contribute to the Documentation Repository - [Contribute Documentation](https://github.com/Genocs/genocs-library-docs)\n\n## Getting Started\n\nTo get started with this Template, here are the available options:\n\n- Install using the `genocs cli` tool. Use this for latest release versions of the Template only.\n- Install using the `dotnet new install` tool. Use this for any versions of the Template.\n- Fork the Repository. Use this if you want to always keep your version of the Template up-to date with the latest changes.\n\n\u003e Make sure that your DEV enviroment is setup, [Read the Development Environment Guide](https://genocs-blog.netlify.app/microservice-template/general/development-environment/)\n\n### GENOCS CLI Tool\n\n#### **Prerequisites**\n\nBefore creating your first solution, you should ensure that your local machine has:\n\n- **.NET9** You can find the download [here](https://dotnet.microsoft.com/en-us/download/dotnet/9.0).\n- **NodeJS (16+)** You can find the download [here](https://nodejs.org/en/download).\n- **Visual Studio Code** You can find the download [here](https://code.visualstudio.com/download).\n- **Visual Studio 2022** (Optional) You can find the download [here](https://visualstudio.microsoft.com/vs/preview/vs2022/).\n\n#### **Installation**\n\nAfter you have installed .NET, you will need to install the `cli` console tool.\n\n```bash\ndotnet tool install -g genocs.cli\ngenocs install\n```\n\nThis install the CLI tools and the associated Templates. You are now ready to create your first project!\n\n[Documentation](https://genocs-blog.netlify.app/cli/)\n\n#### Let get started\nHere's how you would create a Solution using the Genocs .NET WebAPI Template.\n\nSimply navigate to a new directory (wherever you want to place your new solution), and open up *bash prompt* at the opened directory.\n\nRun the following command. Note that, in this demonstration, I am naming my new solution as `CompanyName.ProjectName.ServiceName`.\n\n```bash\ngenocs micro-webapi [n|new] CompanyName.ProjectName.ServiceName\n```\n\nThis will create a new .NET9 Web API solution for you using the template.\nFor further steps and details, [Read the Getting Started Guide](https://genocs-blog.netlify.app/microservice-template/)\n\n#### Update\n\nTo update the tool \u0026 templates, run the following commands\n\n```bash\ndotnet tool update genocs.cli --global\ngenocs update\n```\n\n### Forking the Repository\n\nYou 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`.\n\n- Make a fork of this repository in your GitHub account.\n- Create your new `microservice-template` personal project by cloning the forked repository on your personal GitHub.\n- Setup an upstream remote on your personal project pointing to your forked repository using command `git remote add upstream https://github.com/{githubuseraccount}/microservice-template` and `git remote set-url --push upstream DISABLE`\n\nFor step by step instructions, follow: [this](https://discord.com/channels/878181478972928011/892573122186838046/933513103688224838) and [this](https://gist.github.com/0xjac/85097472043b697ab57ba1b1c7530274).\n\n\n### Run the template\n\nMakefile\n-------------------\n\nSo, 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.\n\nTo build the solution:\n\n```bash\nmake build\n```\n\nBy 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.\n\n```bash\nmake start\n```\n\nThat's it, the application would connect to the defined postgresql database and start creating tables, and seed required data.\n\nFor testing this API, we have 3 options:\n1. Swagger @ `localhost:5001/swagger`\n2. Postman collections are available `./postman`\n3. ThunderClient for VSCode. You will have to install the [Thunderclient](https://www.thunderclient.com/) extension for VSCode.\n\nThe default credentials to this API is:\n\n\n```json\n{\n    \"email\":\"admin@root.com\",\n    \"password\":\"123Pa$$word!\"\n}\n```\n\nOpen up Postman, Thunderclient or Swagger.\n\nidentity -\u003e get-token\n\nThis 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`.\n\nHere is a sample CURL command for getting the tokens.\n\n```curl\ncurl -X POST \\\n  'https://localhost:5001/api/tokens' \\\n  --header 'Accept: */*' \\\n  --header 'tenant: root' \\\n  --header 'Accept-Language: en-US' \\\n  --header 'Content-Type: application/json' \\\n  --data-raw '{\n  \"email\": \"admin@root.com\",\n  \"password\": \"123Pa$$word!\"\n}'\n```\n\nAnd here is the response.\n\n```json\n{\n  \"token\": \"\u003cyour token\u003e\",\n  \"refreshToken\": \"\u003cyour refresh token\u003e\",\n  \"refreshTokenExpiryTime\": \"2025-01-01T00:00:00.0000000Z\"\n}\n```\n\nYou will need to pass the `token` in the request headers to authenticate calls to the Genocs API!\n\nFor further steps and details, [Read the Getting Started Guide](https://genocs-blog.netlify.app/microservice-template)\n\n## Containerization\n\nThe 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.\n\nTo 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.\n\n```bash\nmake publish\n```\n\nYou can also push the docker image directly to dockerhub or any supported registry by using the following command.\n\n```bash\nmake publish-to-hub\n```\n\nYou will have to update your docker registry/repo url in the Makefile though!\n\n## Docker Compose\n\nThis 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.\n\n```bash\n#docker compose up - Boots up the webapi \u0026 postgresql container\nmake dcu \n#docker compose down - Shuts down the webapi \u0026 postgresql containers\nmake dcd \n```\n\nThere are also examples for mysql \u0026 mssql variations. You can find the other docker-compose files under the ./docker-compose folder. Read more about docker-compose instructions \u0026 files here [docker-compose](./docker-compose/README.md).\n\n## Cloud Deployment with Terraform + AWS ECS\n\nWe do support cloud deployment to AWS using terraform. The terraform files are available at the `./terraform` folder.\n\n### Prerequisites\n\n- Install Terraform\n- Install \u0026 Configure AWS CLI profiles to allow terraform to provision resources for you. Please see this video about [AWS Credentials Management](https://www.youtube.com/watch?v=oY0-1mj4oCo\u0026ab_channel=MukeshMurugan).\n\nIn brief, the terraform folder has 2 sub-folders:\n- backend\n- environments/staging\n\nThe 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.\n\n```bash\nterraform init\nterraform apply -auto-approve\n```\n\nThis would create the required S3 Buckets and DDB table for you.\n\nNext is the `environments/staging` folder. Here too, run the following command.\n\n```bash\nterraform init\n```\n\nOnce done, you can go the terraform.tfvars file to change the variables like:\n- project tags\n- docker image name\n- ecs cluster name and so on.\n\nAfter that, simply go back to the root of the solution and run the following command.\n\n```bash\nmake ta\n```\n\nThis 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!\n\nTo destroy the deployed resources, run the following\n\n```bash\nmake td\n```\n\n## How to build the template\n\nCheck nuget is installed on your machine. To download nuget, visit [nuget.org](https://www.nuget.org/downloads)\n\n- Download the nuget latest version. At the time of writing this, the latest version is nuget.exe v6.7.0\n- Add the nuget.exe to your PATH environment variable.\n- run the following commands\n\n```bash\nnuget pack ./src/Package.Template.nuspec -NoDefaultExcludes -OutputDirectory ./out -Version 2.0.0\ndotnet new install ./out/Genocs.Microservice.Template.2.0.0.nupkg\ndotnet new gnx-microservice --help\ndotnet new gnx-microservice --name {{CompanyName.ProjectName.ServiceName}}\n```\n\n## Links \u0026 Documentations\n\n[Overview](https://https://genocs-blog.netlify.app/microservice-template/general/overview/)\n\n[Getting Started](https://https://genocs-blog.netlify.app/microservice-template/general/getting-started/)\n\n[Development Environment](https://https://genocs-blog.netlify.app/microservice-template/general/development-environment/)\n\n[Participate in QNA \u0026 General Discussions](https://github.com/Genocs/microservice-template/discussions)\n\n## Changelogs\n\nView Complete [Changelogs](https://github.com/Genocs/microservice-template/blob/main/CHANGELOG.md).\n\n## License\n\nThis project is licensed with the [MIT license](LICENSE).\n\n\n## Community\n\n- Discord [@genocs](https://discord.com/invite/fWwArnkV)\n- Facebook Page [@genocs](https://facebook.com/Genocs)\n- Youtube Channel [@genocs](https://youtube.com/c/genocs)\n\n\n## Support\n\nHas this Project helped you learn something New? or Helped you at work?\n\nHere are a few ways by which you can support.\n\n- ⭐ Leave a star!\n- 🥇 Recommend this project to your colleagues.\n- 🦸 Do consider endorsing me on LinkedIn for ASP.NET Core - [Connect via LinkedIn](https://www.linkedin.com/in/giovanni-emanuele-nocco-b31a5169/)\n- ☕ If you want to support this project in the long run, consider [buying me a coffee](https://www.buymeacoffee.com/genocs)!\n\n\n[![buy-me-a-coffee](https://raw.githubusercontent.com/Genocs/microservice-template/main/assets/buy-me-a-coffee.png \"buy me a coffee\")](https://www.buymeacoffee.com/genocs)\n\n## Code Contributors\n\nThis project exists thanks to all the people who contribute. [Submit your PR and join the team!](CONTRIBUTING.md)\n\n[![genocs contributors](https://contrib.rocks/image?repo=Genocs/microservice-template \"genocs contributors\")](https://github.com/Genocs/microservice-template/graphs/contributors)\n\n## Financial Contributors\n\nBecome a financial contributor and help me sustain the project.\n\n**Support the Project** on [Opencollective](https://opencollective.com/genocs)\n\n## Acknowledgements\n\n- [Mukesh Murugan](https://github.com/iammukeshm)\n- [FullStackHero](https://fullstackhero.net)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenocs%2Fmicroservice-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenocs%2Fmicroservice-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenocs%2Fmicroservice-template/lists"}