This template uses .Net Core 3.1, to create a foundation for a standard CRUD API using the .Net Template Engine to create new projects on demand using dotnet new
.
Note that, while this package can be used as a stand alone template using the processes described below, it is optimized to be run using the craftsman dotnet tool. For the best development experience, please see the linked
craftsman
repo for operational details.
- VS2019 .Net Core Feature Set or .Net Core 3.1 SDK https://dotnet.microsoft.com/download/dotnet-core/3.1
✅ Basic 'Clean' Scaffold ✅ Repository Pattern ✅ DTOs with Automapper Profiles
✅ Basic CRUD Operations ✅ Add Fluent Validation ✅ Add Custom Pagination
✅ Add Sieve Filters and Sorting ✅ Healthchecks ✅ Add Unit Tests
✅ Add Integration Tests 🔲 Swagger 🔲 Logging
🔲DbMigrations 🔲 Auth 🔲 Breakout Environments
🔲 Rookout 🔲 CloudFormation Scripts 🔲 CircleCi
To get started, all you need to do is run the following command to install it. Once installed, you can use it as described here
dotnet new -i foundation.api
To see the packages you can run
dotnet new -u
To check or apply for updates you can run each of the respectively:
dotnet new foundation.api --update-check
dotnet new foundation.api --update-apply
And to uninstall it, you can run this:
dotnet new -u Foundation.Api
Once a successful installation has completed, you can use the dotnet new
command along with a few different parameters to create your project.
- Name:
-n|--name
This is the name of your project. Generally, I do the company or app name, then the plural entity, then Api as a period separated name in Pascal Case (e.g. CarbonKitchen.Recipes.Api) - EntityName:
-e|--entity
This is the primary database entity that your API will be interacting with (e.g. Orders, OrderItems). The parameter should be singular case and PascalCase (not camelCase). - EntityNameCamel:
-en|--entitycamel
This should be the same as the EntityName parameter, but in camelCase and not PascalCase (e.g. orders, orderItems). - LambdaInitials:
-la|--lambdainitials
This is the value that will be used in lambda expressions. Generally, this would be an all lowercase value that uses the first letter in each word of the entity name (e.g. o for orders, oi for OrderItems)
λ dotnet new foundation -n CarbonKitchen.Recipes.Api -e "Recipe" -en "recipe" --la "r"
Instead of making you learn some custom directory structure, this template was built using the well known clean architecture format. If you are not familiar with it, the Clean Architecture section breakdown of the project structure.
The core layer is split into two projects, the Application
and Domain
layers.
The Domain
project is pretty simple and will capture all of the entities and items directly related to that. This layer should never depend on any other project.
The Application
project is meant to abstract out our specific business rules for our application. It is dependent on the Domain
layer, but has no dependencies on any other layer or project. This layer defines our interfaces, DTOs, Enums, Exceptions, Mapping Profiles, Validators, and Wrappers that can be used by our external layers.
Our infrastructure layer is used for all of our external communication requirements (e.g. database communication). For more control, this layer is split into a Persistence
project as well as a Shared
project. Additional layers can be added here if needed (e.g. Auth
).
The Persistence
project will capture our application specific database configuration. The Shared
project will capture any external service requirements that we may need across our infrastructure layer (e.g. DateTimeService).
Finally, we have our API layer. This is where our WebApi
project will live to provide us access to our API endpoints. This layer depends on both the Core
and Infrastructure
layers, however, the dependency on Infrastructure
is only to support dependency injection. Therefore only Startup
classes should reference Infrastructure
.
If you're using this as a standalone template and not with Craftsman
, this template with scaffold out the bones of your project, but there are a few things you'll need to do to have it operate with you entity.
- Update the parameters in the Entity and the DTOs. It is recommended to do this with a global replace (
ctrl+shift+f
). For example, if you had aRecipe
entity, you could replaceRecipeTextField1
withTitle
- Update the validators to suit your needs
- Adjust Sieve Filters and Sorts on the Entity
- Update the QueryString search in the Repository.GetList method to use whichever fields you'd like, or remove it all together. Note that modifications here might require you to update or remove some repository tests.
- If needed, update repository tests for gets to accommodate filter and sorts
- If needed, update any integration tests
- Add any additional tests that you may want to run
While the nuget installation is recommended, you can also run it locally if you'd like.
For your first time using this template, follow these steps to get things set up.
- Clone this repository to your computer in an accessible location:
git clone https://github.com/pdevito3/foundation.api
- Pull the latest updates from the master remote, if needed.
- Run the uninstall script using
new
. Usedotnet new -u [your repo dir]
. For example:dotnet new -u C:\Users\Paul\Documents\repos\Foundation.Api\templates\FoundationApi
. - Using the command prompt,
cd
to your your repository directory. For example:cd C:\Users\Paul\Documents\repos\Foundation.Api
- Run
dotnet new -i .\
to reinstall the foundation template cd
to the directory that you want to add your new repository- run
dotnet new foundation
as you normally would to create your project
dotnet new -u C:\Users\Paul\Documents\repos\Foundation.Api\templates\FoundationApi
cd C:\Users\Paul\Documents\repos\Foundation.Api
dotnet new -i .\
cd..
dotnet new foundation -n CarbonKitchen.Recipes.Api -e "Recipe" -en "recipe" -la "r"