netcore-boilerplate: a .NET 10 API starter that shows several architectures at once

A playground, not a house style

The description is a boilerplate of API in .NET 10, and the README explains what a boilerplate is in one sentence: a piece of code that helps you quickly kick off a project or start writing your source code, a kind of template so you use code that already contains such snippets instead of adding the same ones each time.

What makes this one different is the intention, and the intention is stated plainly. The intention behind this project is to mix a variety of different approaches to show different available paths, which is why you can find the Service approach mixed up with the Repository approach, or old-fashioned controllers mixed up with brand new minimal API in a separate module, following a modular approach. It is described as a kind of playground for exploring frameworks, packages and tooling, and the conclusion is that you are in charge and it is your decision which path you would like to follow.

That single sentence is the most important thing in the repository for an adopter. A template that mixes two data access styles, two API styles and two module structures is not a house style, and anyone who copies it wholesale without pruning will end up with a codebase that answers none of their questions.

The primary language is C#, the licence is GPL-2.0, the default branch is master, and the last push was on 2026-10-17. The recent releases are v5.0.9 from 2026-08-31, v5.0.8 from 2026-07-15 and v5.0.7 from 2026-06-16, and every one of those three is labelled CVEs, which is a useful thing to know before you pin a version.

The dependency list, and what each choice signals

The Source code contains section is a long inventory, and reading it tells you what the author considered worth including.

Central Package Management is used, so every NuGet version lives in one place rather than in each project file. The Swagger and Swashbuckle pair is struck through and marked as removed in PR488, replaced by OpenAPI with Scalar as the documentation UI. FeatureManagement from Microsoft supplies feature flags and feature toggles, and Xabaril's HealthChecks provide the health endpoints. EF Core is present alongside Dapper, with a MySQL project, an MS SQL Server project and a SQLite option under Dapper, which is the same service-versus-repository split showing up in the data layer.

Logging is Serilog with the Async sink, and DbUp is the database migration tool rather than EF Core migrations.

On security the list is worth reading closely, because it is the part that distinguishes this from a typical template. Mend Bolt gives a WhiteSource security check, NuGet Audit checks the packages you depend on, and Trivy scans the container image. On code quality there are architectural tests, NetArchTest with xUnit.v3, the Microsoft.VisualStudio.Threading.Analyzers package, a code analysis rule set named HappyCode.NetCoreBoilerplate.ruleset, CodeQL for static analysis, an MTP code coverage extension with ReportGenerator and Codecov, and an EditorConfig file.

The thread analysers are the detail that stands out. A template that ships with concurrency analysers enabled is signalling that a .NET service with background work is where the bugs live, and it costs nothing to have them on from the start.

Docker is Alpine Linux with globalization enabled, and the compose file brings up MySQL and SQL Server with initialisation scripts, plus the application itself built from the repository Dockerfile.

Running it: three ways, and the compose file underneath

There are three ways to run the solution, standalone, in docker, and through docker compose, and the README marks the last one as recommended.

The Makefile at the repository root is the entry point for all of them, and its targets are the commands you would otherwise type.

run: ## Runs the app
	dotnet run --project src/HappyCode.NetCoreBoilerplate.Api

docker-build: ## Builds docker image
	docker build -t netcore-boilerplate:local .

docker-compose: ## Starts the docker-compose
	docker compose up

docker-compose-build: ## Builds and starts the docker-compose
	docker compose up --build

docker-compose-down: ## Stops docker-compose
	docker compose down

The compose file is what you get when the recommended path is taken, and it is a good illustration of the template's approach to databases. It runs MySQL 8 and SQL Server 2022 with health checks and initialisation scripts, and the application service itself, which depends on both.

  mysql:
    image: mysql:8
    container_name: mysql
    ports:
      - 3306:3306
    environment:
      MYSQL_ROOT_PASSWORD: SomeStrongPwd123
      MYSQL_DATABASE: employees
      MYSQL_USER: user
      MYSQL_PASSWORD: simplepwd

  netcore-boilerplate:
    container_name: netcore-boilerplate
    build:
      context: .
    ports:
      - 5000:8080
    environment:
      FeatureManagement__DockerCompose: true
    depends_on:
      - mysql
      - mssql

Note the port mapping, 5000 on the host to 8080 in the container, and the FeatureManagement__DockerCompose environment variable, which is the feature flag mechanism from the dependency list being switched on for the compose environment. The double underscore is the .NET convention for nested configuration keys, and here it sets a feature flag named DockerCompose to true.

Both databases are brought up together, and the SQL Server service overrides the container entrypoint with its own script and mounts two more init scripts, which is how the databases get seeded from the files in the db/ directory.

Three test styles, including architectural tests

The test section is the most opinionated part of the repository and the part most worth copying.

Integration tests use an in-memory database and combine AwesomeAssertions, xUnit.v3, Verify and Verify.Http, with TestServer. The Verify library is the interesting choice here, because it works by snapshot testing: the serialised output of a request is compared against a committed file, and a mismatch fails the test with a diff. That is a much better fit for an HTTP API than asserting on individual fields, and it means a change to the response shape shows up as a reviewable diff rather than a green test.

Unit tests use AutoFixture for data generation, with AwesomeAssertions, Moq and Moq.AutoMock, on xUnit.v3. AutoFixture populates an object graph with plausible values so a test does not have to construct one field at a time, and AutoMock removes the explicit constructor injection of mocks.

Both styles sit on Microsoft.Testing.Platform, which the source list attributes to PR551, and the third style is architectural tests using NetArchTest with xUnit.v3. Architectural tests are the unusual part. Instead of testing that a method returns the right value, they assert that a rule holds about the shape of the code, for example that a certain type does not depend on a certain other type. That is how a template can keep the layering it claims to have as people add code to it over months, and it is a better fit for a boilerplate than a comment asking people to follow the pattern.

The coverage story is also modern rather than bolted on, with the MTP code coverage extension feeding ReportGenerator and Codecov, and the repository carrying a codecov.yml at the root.

The result is a test setup where each layer is checked by a different mechanism: unit tests for logic, integration tests with snapshots for the HTTP surface, and architectural tests for the structure itself.

Security scanning in CI, and the release history it produced

The continuous integration configuration is in the repository as four workflow files, and the list of them says what the author thinks should run on every change.

The dotnetcore.yml workflow builds and tests the solution, docker-build.yml builds the container image, codeql-analysis.yml runs CodeQL, and scanners.yml runs the security scanners. The GitHub Actions badges in the README are for Build and Test and for the docker image build, and there is a separate workflow for pushing the image to a registry.

The images go to two places, Docker Hub at lkurzyniec/netcore-boilerplate and the GitHub Container Registry, and the compose file references the local build as netcore-boilerplate:compose.

The three most recent releases are all labelled CVEs, v5.0.7 in June 2026, v5.0.8 in July and v5.0.9 in August. That is worth understanding rather than reading as churn. This is a template that pulls in a large dependency set, it runs Mend Bolt, NuGet Audit and Trivy, and it fixes what those tools find, so a release whose title is a CVE is a release where the scanning pipeline did its job. A project with fewer scanners would have the same vulnerable transitive packages and no release to show for it.

There is a .whitesource directory in the tree, which is the Mend configuration, and a trivy.yml at the root for the container scanner. The globals are centralised in Directory.Build.props and Directory.Packages.props, and there is a global.json pinning the SDK, plus a HappyCode.NetCoreBoilerplate.slnx solution file and a Makefile with a help target that parses its own comments to print usage.

Where this boilerplate stops being the right starting point

There are three limits, and the first is inherent in the design.

The first is that a template that shows several approaches is a template you must prune. The Service and Repository approaches, the controllers and the minimal API module, EF Core and Dapper, MySQL and SQL Server, all of it is present so you can compare, and all of it is present so that a copy-paste of the whole repository gives you a codebase with two ways of doing everything. The README's own conclusion is the guidance: you are in charge, and the choice is yours. That is a fair framing, but it means the first hour with this repository is spent deleting rather than building, and the value depends entirely on whether you would have written those same snippets yourself.

The second is the size of the dependency surface. Central Package Management, feature flags, health checks, two ORMs, two database engines, Serilog, DbUp, three test frameworks, four scanners, CodeQL and the architectural tests. Every one of those is a choice someone has to own, and each one carries a version to track and a set of behaviours to understand. A two-endpoint internal service does not need any of it, and adopting the whole set means adopting the maintenance of the whole set.

The third is the GPL-2.0 licence. That matters specifically because this is a template you copy into your own repository, and a copyleft licence on a scaffold propagates to the code you build on top of it. For an internal service at a company that already ships GPL code it is a non-issue, and for a commercial product the licence is a decision rather than a detail, so read it before you fork.

The alternative is to treat this the way its author describes it, as a playground. Clone it, run it, and copy the two or three pieces you actually wanted, which in practice means the Docker Compose setup, the test project layout, the CI scanners and the architectural tests, rather than the application code and its two competing data access styles.

Editorial conclusion

Adopt netcore-boilerplate if you want a .NET 10 API skeleton with the observability, security scanning and test infrastructure already configured, and you are willing to delete the parts of it you do not want. Do not adopt it as a reference architecture, because the repository's stated purpose is to show several approaches side by side rather than to recommend one. Before you start, check the global.json file for the pinned SDK, and note the last push was on 2026-10-17 with the recent releases all carrying CVE fixes.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. lkurzyniec/netcore-boilerplate on GitHub
4. README
5. Releases