Boilerplate of API in .NET Core 3.1 .NET 8

GitHub	Codecov	Docker Hub

Boilerplate is a piece of code that helps you to quickly kick-off a project or start writing your source code. It is kind of a template - instead of starting an empty project and adding the same snippets each time, you can use the boilerplate that already contains such code.

Intention - The intention behind this project is to mix a variety of different approaches to show different available paths. That's why you can find here the Service approach mixed-up with Repository approach, or old-fashioned controllers mixed-up with brand new minimal API in a separate module (modular approach). As well as, it's a kind of playground for exploring frameworks, packages, tooling. At the end, You are in charge, so it's your decision to which path you would like to follow.

• Source code contains
• Run the solution
  • Standalone
  • In docker
    • Download form registry
    • Build your own image
  • Docker compose
    • Migrations
• How to adapt
• Architecture
  • Api
  • Core
• DB Migrations
• Tests
  • Integration tests
  • Unit tests
  • Architectural tests
• Books module
  • Module
  • Integration Tests
• To Do

1. Central Package Management (CPM)
2. [Autofac](https://autofac.org/) (Removed in PR19)
3. Swagger + Swashbuckle
4. FeatureManagement (Feature Flags, Feature Toggles)
5. HealthChecks
6. EF Core
   • MySQL provider from Pomelo Foundation
   • MsSQL from Microsoft
7. Dapper
   • Microsoft.Data.Sqlite
8. Tests
   • Integration tests with InMemory database
     • FluentAssertions
     • xUnit
     • Verify
     • Verify.Http
     • TestServer
   • Unit tests
     • AutoFixture
     • FluentAssertions
     • Moq
     • Moq.AutoMock
     • xUnit
   • Load tests (Removed in PR135)
     • [NBomber](https://nbomber.com/)
9. Code quality
   • Architectural tests (conventional tests)
     • NetArchTest
     • xUnit
   • Analyzers
     • Microsoft.CodeAnalysis.Analyzers
     • Microsoft.AspNetCore.Mvc.Api.Analyzers
     • Microsoft.VisualStudio.Threading.Analyzers
   • Code analysis rule set HappyCode.NetCoreBoilerplate.ruleset
   • Code analysis with CodeQL
   • Code coverage
     • Coverlet
     • Codecov
   • EditorConfig (.editorconfig)
10. Docker
    • Dockerfile
    • Docker-compose
      • mysql:8 with DB initialization
      • mcr.microsoft.com/mssql/server:2017-latest with DB initialization
      • netcore-boilerplate:compose
    • Build and test
    • Push to registry
      • Docker Hub
      • GitHub Container Registry
11. Serilog
    • Sink: Async
12. DbUp as a db migration tool
13. Continuous integration
    • [Travis CI](https://travis-ci.org/) (travisci.yml)
    • GitHub Actions
      • dotnetcore.yml
      • codeql-analysis.yml
      • docker-build.yml

To run the solution, use one of the options:

• Standalone
• In docker
• Docker compose (recommended)

After successful start of the solution in any of above option, check useful endpoints:

• swagger - http://localhost:5000/swagger/
• health check - http://localhost:5000/healthz/ready
• version - http://localhost:5000/version

When running standalone, features like cars and employees might be disabled.

Execute dotnet run --project src/HappyCode.NetCoreBoilerplate.Api in the root directory.

When running in docker, features like cars and employees are disabled.

• Docker Hub - https://hub.docker.com/r/lkurzyniec/netcore-boilerplate
• GitHub Container Registry - https://github.com/lkurzyniec/netcore-boilerplate/pkgs/container/netcore-boilerplate

Simply execute docker run --rm -p 5000:8080 --name netcore-boilerplate lkurzyniec/netcore-boilerplate to download and spin up a container.

To run in docker with your own image, execute docker build . -t netcore-boilerplate:local in the root directory to build an image, and then docker run --rm -p 5000:8080 --name netcore-boilerplate netcore-boilerplate:local to spin up a container with it.

When running on Linux (i.e. WSL), make sure that all docker files (dockerfile, docker-compose and all mssql files) have line endings LF.

Just execute docker-compose up command in the root directory.

When the entire environment is up and running, you can additionally run a migration tool to add some new schema objects into MsSQL DB. To do that, go to src/HappyCode.NetCoreBoilerplate.Db directory and execute dotnet run command.

Generally it is totally up to you! But in case you do not have any plan, You can follow below simple steps:

1. Download/clone/fork repository ⤵️
2. Remove components and/or classes that you do not need to 🔥
3. Rename files (e.g. sln or csproj), folders, namespaces etc 📝
4. Appreciate the work ⭐

HappyCode.NetCoreBoilerplate.Api

• The entry point of the app - Program.cs
• Simple Startup class - Startup.cs
  • MvcCore
  • DbContext (with MySQL)
  • DbContext (with MsSQL)
  • Swagger and SwaggerUI (Swashbuckle)
  • HostedService and HttpClient
  • FeatureManagement
  • HealthChecks
    • MySQL
    • MsSQL
• Filters
  • Simple ApiKey Authorization filter - ApiKeyAuthorizationFilter.cs
  • Action filter to validate ModelState - ValidateModelStateFilter.cs
  • Global exception filter - HttpGlobalExceptionFilter.cs
• Configurations
  • Serilog configuration place - SerilogConfigurator.cs
  • Swagger registration place - SwaggerRegistration.cs
    • Feature flag documentation filter - FeatureFlagSwaggerDocumentFilter.cs
    • Security requirement operation filter - SecurityRequirementSwaggerOperationFilter.cs
• Logging
  • Custom enricher to have version properties in logs - VersionEnricher.cs
• Simple exemplary API controllers - EmployeesController.cs, CarsController.cs, PingsController.cs
• Example of BackgroundService - PingWebsiteBackgroundService.cs

HappyCode.NetCoreBoilerplate.Core

• Models
  • Dto models
  • DB models
  • AppSettings models - Settings
• DbContexts
  • MySQL DbContext - EmployeesContext.cs
  • MsSQL DbContext - CarsContext.cs
• Providers
  • Version provider - VersionProvider.cs
• Core registrations - CoreRegistrations.cs
• Exemplary MySQL repository - EmployeeRepository.cs
• Exemplary MsSQL service - CarService.cs

HappyCode.NetCoreBoilerplate.Db

• Console application as a simple db migration tool - Program.cs
• Sample migration scripts, both .sql and .cs - S001_AddCarTypesTable.sql, S002_ModifySomeRows.cs

HappyCode.NetCoreBoilerplate.Api.IntegrationTests

• Infrastructure
  • Fixture with TestServer - TestServerClientFixture.cs
  • TestStartup with InMemory databases - TestStartup.cs
  • Simple data feeders - EmployeeContextDataFeeder.cs, CarsContextDataFeeder.cs
  • Fakes - FakePingService.cs
• Exemplary tests - EmployeesTests.cs, CarsTests.cs, PingsTests.cs

HappyCode.NetCoreBoilerplate.Api.UnitTests

• Exemplary tests - EmployeesControllerTests.cs, CarsControllerTests.cs, PingsControllerTests.cs
• API Infrastructure Unit tests
  • ApiKeyAuthorizationFilterTests.cs
  • ValidateModelStateFilterTests.cs
  • VersionEnricherTests.cs

HappyCode.NetCoreBoilerplate.Core.UnitTests

• Extension methods to mock DbSet faster - EnumerableExtensions.cs
• Exemplary tests - EmployeeRepositoryTests.cs, CarServiceTests.cs
• Providers tests
  • VersionProviderTests.cs with HappyCode.NetCoreBoilerplate.Core.UnitTests.runsettings

HappyCode.NetCoreBoilerplate.ArchitecturalTests

• Exemplary tests - ApiArchitecturalTests.cs, CoreArchitecturalTests.cs

Totally separate module, developed with a modular monolith approach.

The code organized around features (vertical slices).

HappyCode.NetCoreBoilerplate.BooksModule

• Features
  • Delete book - Endpoint.cs, Command.cs
  • Get book - Endpoint.cs, Query.cs
  • Get books - Endpoint.cs, Query.cs
  • Upsert book - Endpoint.cs, Command.cs
• Sqlite db initializer - DbInitializer.cs
• Module configuration place - BooksModuleConfigurations.cs

HappyCode.NetCoreBoilerplate.BooksModule.IntegrationTests

• Infrastructure
  • Fixture with TestServer - TestServerClientFixture.cs
  • Very simple data feeder - BooksDataFeeder.cs
• Exemplary tests - BooksTests.cs

• any idea? Please create an issue.

If:

• you like this repo/code,
• you learn something,
• you are using it in your project/application,

then please give me a star, appreciate my work. Thanks!

You are also very welcome to acknowledge my time by buying me a small coffee.