dotnet-api-boilerplate — Herald migration demo

A fork published by MMPWorks to demonstrate migrating a real .NET application from Serilog to Herald. This repository is an unmodified copy of the upstream application except for the logging migration described below.

Original project	yanpitangui/dotnet-api-boilerplate — an ASP.NET Core clean-architecture API template
Original authors	Yan Pitangui
License	MIT — © 2020 Yan Pitangui. Preserved unchanged in LICENSE; all copyright remains with the original author.
What MMPWorks changed	Only the logging migration below. The application itself is untouched.

The Serilog → Herald migration

Verdict: viable drop-in. net9. The 86 ILogger<T> call sites did not change — the migration is 4 files and one namespace swap, not your code.

The entire source change

// Directory.Packages.props — Central Package Management
-  <PackageVersion Include="Serilog.AspNetCore" Version="9.0.0" />
+  <PackageVersion Include="MMP.Herald.Serilog" Version="0.12.6" />
+  <PackageVersion Include="Herald.OSS.Serilog.Settings" Version="0.12.6" />

// appsettings.json keeps its Serilog: block; ReadFrom.Configuration reads it.
// Your ILogger<T> call sites do not change.

This is the config-as-data case. The whole point of the project is that logging is declared in JSON, not code — so the migration has to carry the reader, not just the API. It does: the appsettings.json Serilog: block stays in place and ReadFrom.Configuration reads it after the package swap.

What we proved — we ran it, not just compiled it

We proved this on a live run against a real Postgres (Testcontainers Postgres 16), not just a compile.

• The 86 ILogger<T> call sites did not change.
• UseSerilog host wiring carried.
• The ReadFrom.Configuration appsettings reader carried.
• The global level floor carried — we drove it to Warning and watched the line count go to zero.
• Per-source MinimumLevel.Override now carries from appsettings — EF Core lines hold their own Warning floor (proven on the live run).
• A runtime LoggingLevelSwitch takes effect immediately, on every dispatch path — change the level mid-run and the very next event obeys it. This is the thing only a real run shows.
• Serilog.Exceptions structured exception destructuring carries: custom exception properties survive to the sink as flat, queryable keys (exception.data.OrderId, exception.inner.data.RetryCount) through .Enrich.WithExceptionDetails(). This was the one real data loss the migration set surfaced, and it is closed — the structured fields now reach the sink instead of collapsing into the message string.
• Tests: 22 passed, 0 failed, 0 skipped (integration suite against Testcontainers Postgres 16). The logging path is proven by the live run.

The honest caveat

The per-source MinimumLevel.Override carries from appsettings for the global floor and for EF Core — EF Core Database.Command lines obey the JSON Warning floor, which is the part a green build never shows. One honest residual: a single Microsoft.AspNetCore.DataProtection line still prints at INF during host bootstrap. It is emitted before the category level map binds, so the per-category floor has not taken effect yet for that one line. The global floor and the EF Core override both clamp correctly. We state this rather than hide it.

Herald is Apache-2.0 open source: github.com/mmpworks/Herald.OSS.

---

The original project README follows, unchanged.

dotnet-api-boilerplate

English | Português

A .Net 9.0 WebApi boilerplate / template project. MediatR, Swagger, AutoMapper Mapster, Serilog and more implemented.

The goal of this project is to be a kickstart to your .Net WebApi, implementing the most common used patterns and technologies for a restful API in .net, making your work easier.

How to run

• Use this template(github) or clone/download to your local workplace.
• Download the latest .Net SDK and Visual Studio/Code/Rider.

Standalone

1. You may need a running instance of Postgres, with appropriate migrations initialized.
   • You can run just the DB on docker. For that, run the following command: docker-compose up -d db-server. Doing that, the application will be able to reach the container of the db server.
2. Go to the src/Boilerplate.Api folder and run dotnet run, or, in visual studio set the api project as startup and run as console/docker/IIS.
3. Visit http://localhost:7122/api-docs or https://localhost:7123/api-docs to access the application's swagger.

Docker

1. Run docker-compose up -d in the root directory, or, in visual studio, set the docker-compose project as startup and run. This should start the application and DB.

• 1. For docker-compose, you should run this command on the root folder: dotnet dev-certs https -ep https/aspnetapp.pfx -p yourpassword Replace "yourpassword" with something else in this command and the docker-compose.override.yml file. This creates the https certificate.

2. Visit http://localhost:7122/api-docs or https://localhost:7123/api-docs to access the application's swagger.

Running tests

Important: You need to have docker up and running. The integration tests will launch a Postgres container and use it to test the API.

In the root folder, run dotnet test. This command will try to find all test projects associated with the sln file. If you are using Visual Studio, you can also access the Test Menu and open the Test Explorer, where you can see all tests and run all of them or one specifically.

Authentication

In this project, some routes requires authentication/authorization. For that, you will have to use the api/identity/register route to create an account. After that, you can login using the /api/identity/login without using cookies and then use received accessToken on the lock (if using swagger) or via the Authorization header on a http request. For more information, please take a look on swagger documentation.

This project contains:

• SwaggerUI
• EntityFramework
• Postgres
• Minimal apis
• Strongly Typed Ids
• Test coverage collection
• AutoMapper Mapster
• MediatR
• Feature slicing
• Serilog with request logging and easily configurable sinks
• .Net Dependency Injection
• Resource filtering
• Response compression
• Response pagination
• CI (Github Actions)
• Authentication
• Authorization
• Unit tests
• Integration tests with testcontainers
• Container support with docker and docker-compose
• OpenTelemetry support (with OLTP as default exporter)
• NuGet Central package management (CPM)

Project Structure

1. Services
   • This folder stores your apis and any project that sends data to your users.
   1. Boilerplate.Api
      • This is the main api project. Here are all the controllers and initialization for the api that will be used.
   2. docker-compose
      • This project exists to allow you to run docker-compose with Visual Studio. It contains a reference to the docker-compose file and will build all the projects dependencies and run it.
2. Application
   • This folder stores all data transformations between your api and your domain layer. It also contains your business logic.
   1. Auth
      • This folder contains the login Session implementation.
3. Domain
   • This folder contains your business models, enums and common interfaces.
   1. Boilerplate.Domain
      • Contains business models and enums.
      1. Auth
         • This folder contains the login Session Interface.
4. Infra
   • This folder contains all data access configuration, database contexts, anything that reaches for outside data.
   1. Boilerplate.Infrastructure
      • This project contains the dbcontext, entities configuration and migrations.

Adopting to your project

1. Remove/Rename all hero related stuff to your needs.
2. Rename solution, projects, namespaces, and ruleset to your use.
3. Change the dockerfile and docker-compose.yml to your new csproj/folder names.
4. Give this repo a star!

Migrations

To run migrations on this project, you need the dotnet-ef tool.

• Run dotnet tool install --global dotnet-ef
• Now, depending on your OS, you have different commands:
  1. For windows: dotnet ef migrations add InitialCreate --startup-project .\src\Boilerplate.Api\ --project .\src\Boilerplate.Infrastructure\
  2. For linux/mac: dotnet ef migrations add InitialCreate --startup-project ./src/Boilerplate.Api/ --project ./src/Boilerplate.Infrastructure/

If you like it, give it a Star

If this template was useful for you, or if you learned something, please give it a Star! ⭐

Thanks

This project has great influence of https://github.com/lkurzyniec/netcore-boilerplate and https://github.com/EduardoPires/EquinoxProject. If you have time, please visit these repos, and give them a star, too!

About

This boilerplate/template was developed by Yan Pitangui under MIT license.