I often need a working API for quick UI prototypes, UI framework testing, integration tool testing, load-testing tools, and demo projects for talks (conference, school, meetup). I do not want to build a new backend every single time just to have realistic endpoints and data.

So I built MMLib.DummyApi: a configurable mock REST API that starts fast and gives me fully functional CRUD endpoints, generated seed data, validation, and edge-case simulation.

Why this project exists

The core idea is simple:

• I have different frontends and tools to test.
• I need realistic data and behavior.
• I need to control “bad” scenarios too.

Instead of creating another one-off API (or asking an agent to generate one again), I provide configuration and the API is ready.

Out of the box, it is not read-only mock data. The API works with:

• GET /{collection}
• GET /{collection}/{id}
• POST /{collection}
• PUT /{collection}/{id}
• DELETE /{collection}/{id}

POST/PUT payloads are validated by your JSON schema, and collections can be seeded with dummy data on startup.

Quick start

Run it with Docker:

docker pull ghcr.io/burgyn/mmlib-dummyapi
docker run -p 8080:8080 ghcr.io/burgyn/mmlib-dummyapi

Try a default collection:

curl http://localhost:8080/products

API docs are available at http://localhost:8080/scalar/v1.

Create your own records collection

In my case, I often need some custom “evidence” or “records” collection. Here is a minimal example:

{
  "collections": [
    {
      "name": "records",
      "displayName": "Records",
      "seedCount": 5,
      "schema": {
        "type": "object",
        "required": ["title", "status"],
        "properties": {
          "title": { "type": "string", "minLength": 2 },
          "status": { "type": "string", "enum": ["new", "processing", "done"] },
          "ownerEmail": { "type": "string", "format": "email" }
        }
      }
    }
  ]
}

Save it as my-collections.json and start the container with config mount:

docker run -p 8080:8080 \
  -v ./my-collections.json:/config/collections.json \
  -e DUMMYAPI__COLLECTIONSFILE=/config/collections.json \
  ghcr.io/burgyn/mmlib-dummyapi

Now verify round-trip CRUD quickly:

curl -X POST http://localhost:8080/records \
  -H "Content-Type: application/json" \
  -d '{"title":"Load test scenario","status":"new","ownerEmail":"john@example.com"}'

curl http://localhost:8080/records

Simulate edge cases without extra coding

This is the part I use a lot in demos and testing:

• Delays: X-Simulate-Delay: 500
• Forced error: X-Simulate-Error: true
• Retry scenario: X-Simulate-Retry: 3 with X-Request-Id
• Random chaos latency/failures with chaos headers
• Background updates with backgroundJob (for example status transitions)

A tiny retry simulation call can look like this:

curl http://localhost:8080/records \
  -H "X-Simulate-Retry: 3" \
  -H "X-Request-Id: demo-retry-1"

This lets me test how UI and integration clients behave when things are not perfect, without implementing custom fault endpoints.

Wrap-up

I built this as a practical utility for my own daily workflows, but maybe it helps you too if you prototype often or need controllable API behavior for tests and demos.

I kept this article intentionally simple. Full details, all configuration options, and more advanced scenarios are in the project README.

Links

• GitHub repository: https://github.com/Burgyn/MMLib.DummyApi

How it works

You need three things:

1. Register validation in DI - call builder.Services.AddValidation(); in Program.cs.
2. Decorate your request types with DataAnnotation attributes: [Required], [MinLength], [EmailAddress], [Range], [Compare], and so on.
3. Do nothing else - a source generator emits the validation logic; your endpoint signature stays the same.

If validation fails, the framework returns 400 Bad Request with a ProblemDetails - style payload before your handler runs.

Where you can use it

This validation works for:

• Request body - e.g. JSON bound to a record or class.
• Query parameters - e.g. [FromQuery] with attributes.
• Headers - when bound from headers with the right attributes.

So you get the same declarative style you know from MVC, but without the controller layer.

Important: the request type must be public

If your request class or record is not public, validation will not run. The generated code only sees public types. Keep that in mind when you define DTOs in the same file as your endpoints or in a separate assembly.

Example

Let’s put it together. First, add the validation services and define a minimal endpoint:

using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);

// 👇 Add validation support
builder.Services.AddValidation();

var app = builder.Build();

// 👇 Nothing changed here in your endpoint
app.MapPost("/users", (CreateUserRequest request) =>
{
    return Results.Ok(new { id = 1, request.Name, request.Email });
});

app.Run();

Your handler still receives a CreateUserRequest; the framework validates it before the lambda runs. The request type is a public record with DataAnnotations:

// 👇 Your model class with validation attributes
public record CreateUserRequest(
    [Required, MinLength(2), MaxLength(100)]
    string Name,
    [Required, EmailAddress]
    string Email,
    [Required, MinLength(8), MaxLength(100)]
    string Password,
    [property: Required, Compare(nameof(CreateUserRequest.Password))]
    string ConfirmPassword,
    [Range(18, 120)] int Age);

For records, note the property: prefix on [Compare] so the attribute is applied to the generated property. Once that’s in place, invalid requests (e.g. short name, bad email, mismatched passwords, or age out of range) get a 400 response automatically.

When you need more than DataAnnotations

DataAnnotations are great for straightforward rules. If you need more complex, FluentValidation-style logic (cross-field rules, async validators, or heavy reuse), you can still use custom endpoint filters - I wrote about that approach in an earlier post (in Slovak): ASP.NET Core Minimal API – Filters & Validation. The built-in validation in .NET 10 simply gives you a zero-friction option when attributes are enough.

🔍 Where I find articles I usually discover interesting content in 4 places:

📬 Marián Vlčák aka vlko’s monthly newsletter Consistently high-quality tech content.

📰 Medium newsletter - Though lately it’s been flooded with “5 things every .NET developer must know” type articles. You have to dig deeper to find the gems.

💼 LinkedIn - Still a solid source for technical articles. After Twitter’s decline, it became even more valuable.

☁️ BlueSky - For me, the best Twitter replacement. I’ve created a custom feed built as a filter over my list of specific people I want to follow. BlueSky’s killer feature is the ability to create your own feeds and have full control over what you see and how much. My Developers list.

🎙️ Podcasts - Another source where I often discover interesting topics to explore further.

📚 My reading workflow When I find an interesting article, I don’t read it immediately. Instead, I bookmark it using raindrop.io - my go-to bookmarking system for everything. Articles I want to read go into a “Blogs” folder, which I’ve set up as a public RSS feed. This RSS feed is connected to Instapaper - a reader that creates a clean copy of the article, optimizes it for mobile reading, and most importantly: preserves scroll position. Whenever I return to an article, I’m exactly where I left off.

🤔 Why this seemingly complex setup? I separate two activities: ⚡ Discovery - scrolling feeds and finding new content 📖 Deep reading - actually consuming the content

My BlueSky feed is limited to max 20 posts per day. I quickly scan what interests me and save it for later. When I’m in the mood for reading, I open Instapaper. Raindrop keeps all my bookmarks organized in one place. What’s your workflow for managing technical articles? Do you read immediately or save for later?

Občas sa ma ľudia pýtajú: „Učím sa programovať a chcel by som sa stať backend vývojárom. Ako začať?” alebo „Som junior/medior vývojár a chcem sa posunúť ďalej. Na čo sa mám zamerať?” Ak ide o niekoho z môjho okolia, vieme si sadnúť a prebrať to. Postupne sa dopracujeme k vhodnej ceste. Keď sa ma však opýta niekto na LinkedIn, odpoveď býva: „Je to špecifické, záleží na tom, čo presne chceš alebo potrebuješ…” A tam to väčšinou končí. Prípadne mu ešte odporúčim veľmi dobre spracovaný zoznam oblastí a zdrojov pre vývoj v prostredí .NET od Milana Milanoviča (čistá zhoda mien 😊).

Preto som sa rozhodol napísať túto mini sériu článkov, kde popíšem, ako môže vyzerať cesta od junior ASP.NET CORE backend vývojára po seniora. Nejde o návod na programovanie, ale skôr o opis cesty, ktorou sa vývojár môže vydať. Vysvetlím, v ktorej fáze je dobré ovládať určité zručnosti a aké vedomosti by mal mať.

💭 Toto nie je žiadna rigorózna práca. Každý človek je iný, každá firma má odlišné očakávania a potreby. Môžeš to brať ako jednu z možností, ktorou sa môžeš inšpirovať.

Mojich 5 odporúčaní pre budúcich vývojárov

Tu je mojich 5 všeobecných odporúčaní, ktoré podľa mňa môžu pomôcť na ceste k tomu, aby sa z teba stal lepší vývojár.

1️⃣ Práca ťa musí baviť

Nezáleží na tom, či práve začínaš a vymýšľaš si projekt, na ktorom sa budeš učiť, či máš nápad, ktorý chceš zrealizovať, alebo hľadáš novú prácu. Vyberaj si tak, aby ťa to bavilo, aby si v tom videl zmysel a aby si videl výsledky. Tieto tri faktory (niekedy potrebuješ všetky tri, inokedy stačí jeden z nich) ťa môžu dostatočne motivovať, aby si sa zlepšoval, rástol a zotrval.

2️⃣ Chuť a vytrvalosť

Z vlastnej skúsenosti so začínajúcimi vývojármi viem, že chuť učiť sa, tvoriť a vytrvalosť sú dôležitejšie než momentálne vedomosti a schopnosti.

3️⃣ Zvedavosť

Zvedavosť a záujem o to, ako veci fungujú, vedomé vnímanie toho, s čím pracuješ, môžu výrazne prispieť k tvorbe lepších riešení. Keď si všímam aplikácie, ktoré používam (čo dokážu, čo na nich oceňujem a čo mi nevyhovuje), môžem zákazníkom priniesť lepší produkt. Ak si uvedomujem, ako fungujú knižnice a frameworky, ktoré využívam, môžem navrhnúť efektívnejší kód.

4️⃣ Lenivosť

Tento bod možno niekoho prekvapí a na prvý pohľad si môže odporovať s predchádzajúcimi. Vysvetlím. Ak mi po tretíkrát príde rovnaká požiadavka, mal by sa prejaviť môj zmysel pre „lenivosť” a mal by som si danú úlohu zautomatizovať. Ak niekto opakovane potrebuje rovnaký report, vytvorím na to skript. Ak často zakladám nový projekt, pripravím si scaffold. Lenivý vývojár = efektívny vývojár 😊. Lenivosť je často motorom inovácií.

5️⃣ Vystúp zo svojej komfortnej zóny

Opustenie komfortnej zóny nás dokáže posunúť výrazne dopredu. Komunikuj s kolegami, nauč sa používať netechnický jazyk, vysvetľuj ľuďom, čo robíš, ich vlastnými slovami. Neboj sa komunikovať so zákazníkmi ani zdieľať svoje vedomosti v komunite. Uč sa soft skills. Nemusíš všetko zvládnuť hneď, ale zamysli sa, kde chceš byť v budúcnosti a vyber si to, čo ťa tam posunie. Práve toto sú veci, ktoré sú v súčasnosti tie rozdielové.

Junior / Medior / Senior

V IT firmách sa zaužívalo rozdelenie na junior, medior a senior vývojárov z pohľadu kariérneho rastu alebo zručností. Neexistuje jednotná definícia toho, kto je junior, medior a senior, pretože každá firma to vníma po svojom. Všeobecne však platí, že tieto úrovne kombinujú odpracované roky, technické schopnosti, samostatnosť, zodpovednosť a soft skills.

Junior vývojár

Poďme sa pozrieť na jednu z možných ciest, ako sa môže junior programátor postupne dostať do vývoja ASP.NET CORE REST API.

Prvý projekt

🚩 Existuje mnoho roadmap a odporúčaní, čo všetko by mal takýto vývojár vedieť. Zvyčajne začínajú tým, že by mal ovládať základy C# a .NET. Ja by som sa však pridržiaval môjho prvého odporúčania: práca ťa musí baviť a musíš vidieť výsledky. Študovať C# je dôležité, ale výsledky prídu až časom.

Preto by som rovno začal s ASP.NET CORE Minimal API a vyskúšal si prvé endpointy.

Takto veľmi rýchlo uvidíš výsledok svojej práce. Máš prvé endpointy, ktoré si môžeš otestovať a postupne si začneš tvoriť obraz o tom, čo daná technológia umožňuje a na čo je dobrá.

Navrhni si svoj prvý jednoduchý projekt a postupne skúšaj, čo do neho dokážeš zapracovať (napr. zoznam kontaktov, nákupný zoznam, receptár atď.).

V tejto fáze si to zjednoduš a dáta nikam neukladaj, maximálne ich drž v pamäti. Na prácu s databázou príde čas.

🚩 Keď už máš prvé endpointy za sebou, vráť sa k C# a preštuduj si základy. Premenné, základné dátové typy, funkcie, metódy a jednoduché triedy ti umožnia postupne riešiť komplexnejšie úlohy.

🚩 Prvé requesty si pravdepodobne vykonal priamo z prehliadača pomocou API dokumentácie. Aby si mohol plnohodnotne pracovať s API, budeš si musieť osvojiť prácu s niektorým z HTTP klientov. Najpoužívanejší je Postman, ale môžeš sa stretnúť aj s Insomnia či inými nástrojmi.

🚩 Dáta sú základom väčšiny projektov. Potrebuješ ich ukladať, manipulovať s nimi a poskytovať klientom. Možnosti na ukladanie dát sú rôzne, ale v prípade štruktúrovaných dát sa väčšinou jedná o SQL alebo NoSQL databázy. V nových projektoch je podiel SQL a NoSQL databáz pomerne vyrovnaný, v starších projektoch však častejšie narazíš na SQL databázy. Pre začiatok odporúčam SQL, keďže pravdepodobnosť, že s ním budeš pracovať, je vysoká.

Na úvod to nemusí byť nič zložité. Skús začať s Entity Frameworkom, pripojiť sa na existujúcu databázu, vytvoriť prvú migráciu a naučiť sa, ako načítať dáta.

🚩 Aby si sa mohol ďalej posúvať, potrebuješ ísť hlbšie do ASP.NET Core. Postupne si rozšír svoje zadanie. Pridaj nové sady endpointov, aby si pochopil, ako funguje routing. Preštuduj si model binding, aby si vedel, akými spôsobmi môžeš posielať dáta na backend (cez path, query params, headers, body).

Dáta, ktoré ti prichádzajú, potrebuješ validovať, aby si mal istotu, že dostávaš to, čo očakávaš. Odporúčam sa rovno pozrieť na FluentValidation, keďže model validation princíp, ktorý sa používal v minulosti, už v MinimalAPI nie je možný.

Aby si mohol lepšie štruktúrovať kód, budeš potrebovať pochopiť základy dependency injection (DI). Skús presunúť prácu s dátami zo samotných endpointov do samostatnej triedy (to, či ju nazveš repository, store, manager, je v tejto fáze jedno). Túto triedu teraz nakonfiguruj do DI kontajnera a nechaj si ju injektnúť do tvojich endpointov. Snaž sa pochopiť, na čo je to dobré a aspoň rámcovo pochop, ako to funguje.

🫡 Ak zvládneš tieto veci, budeš pripravený pridať sa k tímu a začať pracovať na menších úlohách v reálnom projekte.

💁‍♂️ Odporúčam začať s MinimalAPI. Ak však vieš, že firma, v ktorej budeš pracovať (alebo pracuješ), používa klasický prístup cez controllery, prečítaj si o tom tiež.

Toto je napríklad u nás nutné minimum, ktoré musí junior ovládať, aby mohol prísť k nám do firmy. Po pohovore dostane zadanie, ktoré, ak vypracuje, tak by mal mať tieto zručnosti zvládnuté.

✅ Checklist:

🔗 Zdroje

• Create a web API with ASP.NET Core
• Learn C#
• C# Fundamentals for Absolute Beginners
• What is Postman?
• First EF Core App
• FluentValidation Documentation
• ASP.NET Core Minimal API Filters
• Dependency injection in ASP.NET Core

Práca v tíme

Pokiaľ máš ako junior zvládnuté vyššie spomínané veci (v rôznej úrovni. Niečo viac, niečo trochu menej) môže začať robiť v tíme.

🚩 V tíme nie si sám. Na to aby tími dokázali rozumne pracovať nad spoločným code baseom využívajú rôzne verzionovacie systémy. V súčasnej dobe to je najčastejšie GIT. Je potrebné aby si zvládol základnú prácu s GIT-om. Na začiatok stačí vedieť získať aktuálnu verziu, vytvoriť si novú vetvu. Vedieť commitovať zmeny a pushnúť zmeny na server.

🚩 Nasleduje Pull request proces, ktorý má daná firma nastavený. (Budeš musieť spoznať základy s nástrojom, ktorý používajú. GitHub / GitLab / AZURE DevOps / …) Tam získaš feadback na svoj kód. Je to výborné miesto na učenie sa. Pretože dostaneš konštruktívne pripomienky od skúsených ľudí. Naučíš sa veľa o projekte, na ktorom pracuješ, ale aj o samotnom programovaní.

🚩 Firma, v ktorej budeš pracovať, má určite nastavený systém práce, využívajú jednu z viacerých metód riadenia softvérového vývoja. V súčasnosti to bude pravdpodobne nejaká z agilných techník. Skús pochopiť základy agilného riadenia, pozri si čo je scrum.

🚩 Ďalej sa vzdelávaj v C# / .NET. Mal by si zvládnuť základy OOP v .NET (classes, objects, interfaces, inheritance, composition), základy generík, údajové štruktúry, error handling, … Je potrebné naučiť sa pracovať so štruktúrou projektov, závislosťami, balíčkovacím systémom (Nuget).

Na projekte už nepracuješ sám, potrebuješ pochopiť a dodržiavať dohodnuté tímové štandardy, čítaš a orientuješ sa v cudzom kóde.

✅ Checklist:

🔗 Zdroje

• Scrum for Beginners
• Soft Skills Help Developers Level Up: 10 Tips
• Getting Started with GitHub Actions: A Beginner’s Guide
• Create Your First Pipeline with Azure DevOps
• Beginner’s Guide to GitHub: Creating a Pull Request
• Git Tutorial - W3Schools
• Learn C# with .NET

Príprava na Mediora

Keď už zvládneš prácu v tíme a pracuješ na reálnych projektoch, začína sa obdobie, kedy sa pripravuješ na úroveň mediora. Medior vývojár by mal mať zvládnuté nielen technické zručnosti, ale aj schopnosť samostatne riešiť problémy, robiť rozhodnutia a prichádzať s návrhmi zlepšení.

🚩 Postupne budeš čoraz samostatnejší a budeš dostávať komplexnejšie úlohy. Tvoj kód musí byť nielen funkčný, ale aj prehľadný a udržiavateľný. V tejto fáze je dôležité osvojiť si princípy ako DRY (Don’t Repeat Yourself), KISS (Keep It Simple, Stupid) a YAGNI (You Aren’t Gonna Need It). Tieto základné princípi ti pomôžu ľahšie pristupovať k hľadaniu riešení.

🚩 V rámci ASP.NET Core budeš musieť hlbšie pochopiť základy HTTP protokolu, parameter bindingu, autentifikácie a autorizácie. Hoci sa neočakáva, že navrhneš celý proces autorizácie, mal by si rozumieť jej významu a základnému fungovaniu v projekte. Pre efektívnu prácu s dátami je dôležité pochopiť koncept DTO a data mappingu, kde ti môžu pomôcť knižnice ako AutoMapper alebo Mapster. Rovnako je dôležité oboznámiť sa s tým, ako sa v ASP.NET Core používa Options pattern na konfiguráciu služby.

📖 Nauč sa čítať dokumentáciu. Prejdi si dokumentáciu frameworku, s ktorým pracuješ.

🚩 Práca s databázami je kľúčová. Mal by si zvládnuť nielen základné DML príkazy (SELECT, INSERT, UPDATE, DELETE), ale aj prácu s migráciami a vedieť, prečo a ako používať indexy na optimalizáciu dotazov. Technické fungovanie indexov môžeš zatiaľ považovať za mágiu 🔮.

🚩 Základné vývojárske zručnosti zahŕňajú efektívne používanie tvojho IDE (Visual Studio, VS Code, Rider), vrátane skratiek, debugovania a analýzy chýb. Investuj čas do spoznávania možností tvojho IDE, až kým niektoré skratky nebudeš mať v rukách namiesto v hlave. Tým získaš viac priestoru na premýšľanie o samotnom riešení a tvoje ruky budú len pretavovať tvoje myšlienky do kódu.

Rovnako by si mal byť zbehlý v práci s príkazovým riadkom, najmä s nástrojmi ako dotnet CLI a ef CLI, ktoré ti umožnia jednoducho spravovať projekty a databázy. UI sa neustále mení, ale CLI príkazy sú trvácne. Keď sa naučíš pracovať s CLI, tvoja produktivita výrazne vzrastie.

🚩 Základy DevOps ti pomôžu pochopiť, kde a ako je projekt nasadený a osvojíš si proces CI/CD (Continuous Integration / Continuous Deployment), aby si vedel lepšie spolupracovať s rôznymi časťami tímu.

🚩 Nezabúdaj na testovanie. Aj keď budete mať testerov, vývojár je spoluzodpovedný za kvalitu svojho kódu. Mal by si rozumieť tomu, čo vyvíjaš a vedieť otestovať základné scenáre.

Postupne si osvoj aj automatické testovanie. Začni s písaním unit testov a zdokonaľuj sa v nich. Ak sa na projekte používajú aj iné typy testov, ako napríklad E2E, integračné alebo load testy, na začiatku ich budeš vedieť upravovať (keď tvoja zmena spôsobí, že test zlyhá) a neskôr ich budeš sám vytvárať.

💁 Pri všetkej svojej práci nezabúdaj, že máš okolo seba šikovných kolegov, ktorí ti radi pomôžu, poradia a nasmerujú ťa. Využi ich skúsenosti a vedomosti. Na druhej strane, pamätaj, že práve tí najšikovnejší bývajú často veľmi vyťažení. Preto si vyberaj správny prístup, správne slová, a maj pokoru, no aj sebadôveru. Buď trpezlivý, keď odpoveď nepríde hneď.

✅ Checklist

🔗 Zdroje

• Introduction to ASP.NET Core
• Software Design Principles: DRY, YAGNI
• KISS, YAGNI, and DRY Principles
• Entity Framework Documentation
• Microsoft Visual Studio Tips and Tricks
• Mastering Visual Studio 2022: Shortcuts, Tips, and Tricks
• Quick Introduction to xUnit
• FluentAssertions Documentation
• AutoMapper GitHub Repository

Záver

Na záver by som chcel zdôrazniť, že cesta vývojára je vždy individuálna a plná výziev. Každý z nás má iné tempo učenia sa, rôzne záujmy a preferencie. Tento článok ti mal poskytnúť návod, ktorým smerom sa môžeš vydať, no to, ako sa rozhodneš napredovať, je úplne na tebe. Nezabúdaj, že programovanie je o neustálom zlepšovaní a prispôsobovaní sa novým technológiám. Neboj sa urobiť chybu, uč sa z nej a hľadaj spôsoby, ako sa posunúť ďalej. Dôležité je neostať stáť na mieste a stále sa snažiť zlepšovať. Takže držím palce na tvojej ceste za lepším kódom a hlavne – užívaj si to!

However, I discovered Mermaid. Same idea, but given where and how it’s integrated everywhere, it’s a significantly better choice for me.

sequenceDiagram
    participant Author
    participant Notion
    participant Blog1 as blog.burgyn.online
    participant Blog2 as blog.vyvojari.dev
    participant Social as Social media

    Author->>Notion: Record ideas for articles
    Author->>Notion: Select an idea to write about
    Author->>Author: Write the basic structure of the article
    Note right of Author: Drink lots of coffee!
    Author->>Author: Insert images and diagrams
    Author->>Author: Check grammar and style
    Author->>Blog1: Publish the article
    Author->>Blog2: Publish the article
    Author->>Author: Create graphic material
    Author->>Social: Share the article from blog.burgyn.online
    Note right of Author: Wait for feedback!

Benefits for me:

• easy to use directly in markdown
  • so it’s part of the documentation
  • native git support (versioning, sharing, …)
  • post-editing
• possibility to create different types of diagrams (flowchart, sequence, class, state, …)
• various integrations
  • Notion
  • GitHub
  • Jekyll (I used jekyll-mermaid)
  • VsCode
  • AZURE DevOps (Wiki only for now)
  • ChatGPT 🤣
  • …

Plugin for ChatGPT. I created the diagram above with a simple prompt to ChatGPT:

I’m going to post an article just about Mermaid. Create me some interesting sequence diagram on how to write such a blog post. I’m writing the ideas in Notion, posting the post on blog.burgyn.online and blog.vyvojari.dev. I then do a social media post about it.

🤔 It’s not enough to set the generic “LogLeve:Default” to “Information” (Debug, Trace), because by default the ApplicationInsights provider only pushes logs with severity Warning and higher to AppInsights anyway.

💡 In order to push them there you need to explicitly set “ApplicationInsights:LogLevel:Default:” to “Information” (Debug, Trace).

🤞 Maybe this will help you sometime too.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    // 👇 This section is important
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": ""
  }
}

It is bad not only in principle, but also because MSBuild still has a problem and if you reference WebAPI projects in this way, it can non-deterministically give you json files in the output of one of the projects that are from another project. We have had this happen to us quite often.

We decided to do a test on it. I don’t know if this is really the type of an architectural test, but let’s say it is 😊.

I originally tried to use the Microsoft.Build and Microsoft.Build.Locator libraries. These libraries contain the Project and ProjectCollection classes, which can retrieve project properties and references. (Microsoft uses this for MSBuild) But the problem with this was that it was very slow and had its flies.

Fortunately we didn’t need anything complicated from csproj, to be able to find out if it is a host project and its references. So we read the necessary information from the csproj files directly via XDocument.

internal class ProjectFile
{
    private HashSet<string> _projectReferences = [];

    public string Name { get; private set; } = string.Empty;

    public string DirectoryPath { get; private set; } = string.Empty;

    public string FullPath { get; private set; } = string.Empty;

    public string Sdk { get; private set; } = string.Empty;

    public string OutputType { get; private set; } = string.Empty;

    public string AzureFunctionsVersion { get; private set; } = string.Empty;

    public bool IsWebProject
        => OutputType.Equals("Exe", StringComparison.OrdinalIgnoreCase)
        || Sdk.Equals("Microsoft.NET.Sdk.Web", StringComparison.OrdinalIgnoreCase)
        || AzureFunctionsVersion.StartsWith("v", StringComparison.OrdinalIgnoreCase);

    public IEnumerable<string> ProjectsReferences => _projectReferences;

    public static async Task<ProjectFile> LoadAsync(string projectFilePath)
    {
        var projectFile = new ProjectFile();

        projectFile.Name = Path.GetFileNameWithoutExtension(projectFilePath);
        projectFile.FullPath = projectFilePath;
        projectFile.DirectoryPath = Path.GetDirectoryName(projectFilePath) ?? string.Empty;

        using var fileStream = new FileStream(projectFilePath, FileMode.Open, FileAccess.Read);

        var doc = await XDocument.LoadAsync(fileStream, LoadOptions.None, default);

        var projectElement = doc.Element("Project");
        if (projectElement != null)
        {
            projectFile.Sdk = projectElement.Attribute("Sdk")?.Value ?? string.Empty;

            var propertyGroup = projectElement.Element("PropertyGroup");
            if (propertyGroup != null)
            {
                projectFile.OutputType = propertyGroup.Element("OutputType")?.Value ?? string.Empty;
                projectFile.AzureFunctionsVersion = propertyGroup.Element("AzureFunctionsVersion")?.Value ?? string.Empty;
            }

            projectFile._projectReferences = projectElement
                .Elements("ItemGroup")
                .Elements("ProjectReference")
                .Attributes("Include")
                .Select(attr => attr.Value)
                .ToHashSet();
        }

        return projectFile;
    }
}

be careful when using Directory.Build.props, then not all properties are directly in the csproj file. We didn’t mind, though, because the necessary ones were there.

We used the SDK property for ASP.NET Core WebAPI projects to determine if it is a host project and the AzureFunctionsVersion property for Azure Functions.

public bool IsWebProject
    => OutputType.Equals("Exe", StringComparison.OrdinalIgnoreCase)
    || Sdk.Equals("Microsoft.NET.Sdk.Web", StringComparison.OrdinalIgnoreCase)
    || AzureFunctionsVersion.StartsWith("v", StringComparison.OrdinalIgnoreCase);

A ProjectFileCollection class that retrieves all the projects in the subdirectories and their references.

internal class ProjectFileCollection : IEnumerable<ProjectFile>
{
    private readonly Dictionary<string, ProjectFile> _projects = new();

    public static async Task<ProjectFileCollection> LoadSolution(string solutionDirectory)
    {
        var projectFileCollection = new ProjectFileCollection();
        foreach (var projectFile in Directory.GetFiles(solutionDirectory, "*.csproj", SearchOption.AllDirectories))
        {
            var project = await ProjectFile.LoadAsync(projectFile);
            projectFileCollection._projects.Add(project.FullPath, project);
        }

        return projectFileCollection;
    }

    public ProjectFile GetProject(string projectPath)
        => _projects[projectPath];

    public IEnumerable<ProjectFile> GetProjectReferences(ProjectFile project)
        => project.ProjectsReferences
            .Select(p => GetProject(GetReferenceFullPath(project.DirectoryPath, p)));

    private static string GetReferenceFullPath(string projectDir, string referencePath)
    {
        if (Path.IsPathRooted(referencePath))
        {
            return referencePath;
        }

        return Path.GetFullPath(Path.Combine(projectDir, referencePath));
    }

    public IEnumerator<ProjectFile> GetEnumerator() => _projects.Values.GetEnumerator();

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
}

The test itself can then look like this:

[Fact]
public async Task WebProjects_ShouldNotReferenceOtherWebProjects()
{
    string solutionDirectory = FindSolutionDirectory();
    var projects = await ProjectFileCollection.LoadSolution(Path.Combine(solutionDirectory, "src"));

    var webProjects = projects.Where(p => p.IsWebProject);
    var errorMessage = new StringBuilder();
    var wrongRecerencesCount = 0;

    foreach (var webProject in webProjects)
    {
        var projectReferences = projects.GetProjectReferences(webProject);
        var webProjectReferences = projectReferences.Where(p => p.IsWebProject);

        if (webProjectReferences.Any())
        {
            errorMessage.AppendFormat("> {0}:", webProject.Name).AppendLine();
            foreach (var reference in webProjectReferences)
            {
                errorMessage.AppendFormat("\t- {0}", reference.Name).AppendLine();
            }
            wrongRecerencesCount++;
            errorMessage.AppendLine("----------------------------------------");
        }
    }

    wrongRecerencesCount.Should()
        .Be(0, "Web project should not reference other web project:\n" + errorMessage.ToString());
}

The result may look like this:

Expected wrongRecerencesCount to be 0 because Web project should not reference other web project:
> Kros.Esw.ApiProjectA:
	- Kros.Esw.ApiProjectB
	- Kros.Esw.ApiProjectC
	- Kros.Esw.ApiProjectD
----------------------------------------
, but found 1 (difference of 1).

However, there are situations where we can’t/don’t want to use a third party library. For example, you are writing some custom library/framework and you don’t want to introduce such dependencies into it.

Something similar happened to us. Fortunately, we didn’t need the complete functionality that MediatR provides, but just a basic event dispatch and processing was enough.

Therefore, I will now show how to easily create such an implementation of your own Mediator.

Let’s start with defining the message interface. In our case it was a domain event, hence the name.

public interface IDomainEvent
{
}

It’s just a pure markup interface. We could do without it, but it’s a good way to indicate that it’s an event.

Then the event processing interface.

public interface IDomainEventHandler<TEvent> 
    where TEvent : IDomainEvent
{
    Task HandleAsync(TEvent domainEvent, CancellationToken cancellationToken = default);
}

We need an interface for sending events.

public interface IEventPublisher
{
    Task PublishAsync<TEvent>(TEvent domainEvent, CancellationToken cancellationToken = default)
        where TEvent : IDomainEvent;
}

We could stop with the abstractions here and start implementing. However, we decided to add an abstraction for the processing strategy in there. For now, the sequential processing of events was enough, but we might need other strategies in the future.

public interface IEventPublisherStrategy
{
    Task PublishAsync<TEvent>(
        IEnumerable<IDomainEventHandler<TEvent>> handlers,
        TEvent domainEvent,
        CancellationToken cancellationToken)
        where TEvent : IDomainEvent;
}

Implementation

Publisher can look like this:

internal class EventPublisher : IEventPublisher
{
    private readonly IServiceProvider _serviceProvider;
    private readonly IEventPublisherStrategy _publisherStrategy;
    private readonly IHttpContextAccessor _httpContextAccessor;

    public EventPublisher(
        IServiceProvider serviceProvider,
        IHttpContextAccessor httpContextAccessor,
        IEventPublisherStrategy publisherStrategy)
    {
        _serviceProvider = serviceProvider;
        _publisherStrategy = publisherStrategy;
        _httpContextAccessor = httpContextAccessor;
    }

    public async Task PublishAsync<TEvent>(TEvent domainEvent, CancellationToken cancellationToken = default)
        where TEvent : IDomainEvent
    {
        IEnumerable<IDomainEventHandler<TEvent>> handlers;
        if (_httpContextAccessor.HttpContext is not null)
        {
            // 👇 if available, then find handlers in HttpContext services
            handlers = GetHandlers<TEvent>(_httpContextAccessor.HttpContext.RequestServices);
            // 👇 publish event to all handlers
            await _publisherStrategy.PublishAsync(handlers, domainEvent, cancellationToken);
        }
        else
        {
            // 👇 if not, then create new scope
            using var scope = _serviceProvider.CreateScope();
            handlers = GetHandlers<TEvent>(scope.ServiceProvider);
            // 👇 publish event to all handlers
            await _publisherStrategy.PublishAsync(handlers, domainEvent, cancellationToken);
        }
    }

    private static IEnumerable<IDomainEventHandler<TEvent>> GetHandlers<TEvent>(IServiceProvider serviceProvider)
        where TEvent : IDomainEvent
        => serviceProvider.GetServices<IDomainEventHandler<TEvent>>();
}

Publisher takes care of getting the handlers from the container and then forwards them to publisher strategy, which decides how they will be processed.

public sealed class ForeachAwaitPublisherStrategy : IEventPublisherStrategy
{
    public async Task PublishAsync<TEvent>(
        IEnumerable<IDomainEventHandler<TEvent>> handlers,
        TEvent domainEvent,
        CancellationToken cancellationToken)
        where TEvent : IDomainEvent
    {
        // 👇 publish event to all handlers
        foreach (var handler in handlers)
        {
            await handler.HandleAsync(domainEvent, cancellationToken);
        }
    }
}

Our ForeachAwaitPublisherStrategy handles events sequentially. It forwards the message to all handlers and waits for them to process it.

Registration

In order to use the abstractions we create, we need to register them in the DI container.

public static IServiceCollection AddEventPublisher(this IServiceCollection services)
{
    services.AddHttpContextAccessor();
    services.TryAddSingleton<IEventPublisher, EventPublisher>();
    services.TryAddSingleton<IEventPublisherStrategy, ForeachAwaitPublisherStrategy>();
    return services;
}

We can also create an extension for easy registration of handlers.

public static IServiceCollection AddDomainEventHandler<TEvent, THandler>(
    this IServiceCollection services,
    ServiceLifetime lifetime = ServiceLifetime.Transient)
    where TEvent : IDomainEvent
    where THandler : class, IDomainEventHandler<TEvent>
{
    services.Add(new ServiceDescriptor(typeof(IDomainEventHandler<TEvent>), typeof(THandler), lifetime));

    return services;
}

Using this extension looks like this services.AddDomainEventHandler<YourEvent, YourHandler>();. This is because I wanted to avoid reflection. If reflection doesn’t bother you, a simplified call to services.AddDomainEventHandler<YourHandler>();. But I’ll leave that up to you 😉.

Usage

Finally, we’ll show you how to use our own Mediator.

Event and handler:

// 👇 The event that the product was created
public record ProductCreated(int Id, string Name, decimal Price) : IDomainEvent;

// 👇 The handler that will process the event
public class ProductCreatedHandler : IDomainEventHandler<ProductCreated>
{
    public Task HandleAsync(ProductCreated domainEvent, CancellationToken cancellationToken = default)
    {
        // 👇 Process the event
        Console.WriteLine($"Product created: {domainEvent.Name}");
        return Task.CompletedTask;
    }
}

The registration:

builder.Services.AddEventPublisher();
builder.Services.AddDomainEventHandler<ProductCreated, ProductCreatedHandler>();

Use in endpoint:

app.MapPost("/products", async (Product product, IEventPublisher publisher) =>
{
    // Save the product
    // 👇 Publish the event
    await publisher.PublishAsync(new ProductCreated(product.Id, product.Name, product.Price));
    return product;
});

Links

• Sample project

Why Use ETag Caching?

ETag caching is particularly useful in scenarios where data changes infrequently but is requested frequently. It optimizes network usage and improves response times by minimizing data transfer. By using ETags, clients can ensure they always have the most recent version of the data.

How ETag Caching Works

ETag caching involves the use of two HTTP headers:

• ETag: A unique identifier for the data, typically a hash or a version number.
• cache-control: Instructs the client that the response can be cached. For ETag caching, this should be set to private.

When a client receives a response with these headers, it caches the data and the ETag value. On subsequent requests, the client sends an If-None-Match header with the ETag value. The server then compares the ETag with the current version of the data. If they match, the server returns a 304 Not Modified status, indicating the client should use the cached data.

Implementation in Ocelot

The Kros.Ocelot.ETagCaching library integrates seamlessly with Ocelot’s middleware. It handles ETag generation, storage, and validation transparently. Here’s how to get started:

Ocelot Configuration

Configure your routes in the ocelot.json file, specifying cache policies:

{
    "Routes": [
        {
            "Key": "getAllProducts",
            "DownstreamPathTemplate": "/api/products/",
            "UpstreamPathTemplate": "/products/",
            "CachePolicy": "getAllProducts" // 👈 Cache policy key
        },
        {
            "Key": "getProduct",
            "DownstreamPathTemplate": "/api/products/{id}",
            "UpstreamPathTemplate": "/products/{id}",
            "CachePolicy": "getProduct" // 👈 Cache policy key
        },
        {
            "Key": "deleteProduct",
            "DownstreamPathTemplate": "/api/products/{id}",
            "UpstreamPathTemplate": "/products/{id}",
            "InvalidateCachePolicy": "invalidateProductCachePolicy"
        }
    ]
}

Program.cs Configuration

Set up the ETag caching policies in Program.cs:

// 👇 Define policies
builder.Services.AddOcelotETagCaching((c) =>
{
    //  👇 Simple policy with expiration and tag templates
    c.AddPolicy("getAllProducts", p =>
    {
        p.Expire(TimeSpan.FromMinutes(5));
        p.TagTemplates("products:{tenantId}", "all", "tenantAll:{tenantId}");
    });

    // 👇 Policy with custom cache key, ETag generator, and cache control
    c.AddPolicy("getProduct", p =>
    {
        p.Expire(TimeSpan.FromMinutes(5));
        p.TagTemplates("product:{tenantId}:{id}", "tenant:{tenantId}:all", "all");
        p.CacheKey(context => context.Request.Headers.GetValues("id").FirstOrDefault());
        p.ETag(context => new($""{Guid.NewGuid()}""));
        p.CacheControl(new() { Public = false });
    });
});

Add the ETag caching middleware to the Ocelot pipeline:

app.UseOcelot(c =>
{
    // 👇 Add ETag caching middleware
    c.AddETagCaching();
}).Wait();

Tag Templates and Cache Invalidation

Tag templates are used to generate cache tags based on request parameters, making it easy to invalidate specific cache entries. For example, for the route /api/{tenantId}/products/{id} and the tag template product:{tenantId}:{id}, the tag will be product:1:2.

Automatic Cache Invalidation

Define invalidate cache policies in ocelot.json:

{
    "Key": "deleteProduct",
    "UpstreamHttpMethod": [ "Delete" ],
    "DownstreamPathTemplate": "/api/products/{id}",
    "UpstreamPathTemplate": "/products/{id}",
    "InvalidateCachePolicy": "invalidateProductCachePolicy" 
    // 👆 Invalidate cache policy key
}

And configure them in Program.cs:

builder.Services.AddOcelotETagCaching(conf =>
{
    // 👇 Define invalidate cache policy
    conf.AddInvalidatePolicy("invalidateProductCachePolicy", builder =>
    {
        // 👇 Define tag templates to invalidate
        builder.TagTemplates("product:{tenantId}", "product:{tenantId}:{id}");
    });
});

Manual Cache Invalidation

Manually invalidate cache entries using the IOutputCacheStore:

public class ProductsService {
    private readonly IOutputCacheStore _outputCacheStore;

    public ProductsService(IOutputCacheStore outputCacheStore)
    {
        _outputCacheStore = outputCacheStore;
    }

    public async Task DeleteProduct(int tenantId, int id)
    {
        await _outputCacheStore.InvalidateAsync(
            $"product:{tenantId}", $"product:{tenantId}:{id}");
        // 👆 Invalidate cache entries by tags            
    }
}

Redis Integration

By default, the library uses InMemoryCacheStore, but you can configure it to use Redis for distributed caching:

builder.Services.AddStackExchangeRedisOutputCache(options =>
{
    options.Configuration 
        = builder.Configuration.GetConnectionString("MyRedisConStr");
    options.InstanceName = "SampleInstance";
});

Sources

• Kros.Ocelot.ETagCaching GitHub Repository
• Ocelot

⚠️ This is a functional implementation, but it doesn’t cover all scenarios and is just a basic example of what such support could look like.

The whole solution is based on a custom implementation for IResult. More info in the documentation.

IResponseNegotiator

Let’s first define the interface whose implementation will be responsible for serializing the response.

public interface IResponseNegotiator
{
    string ContentType { get; }

    bool CanHandle(MediaTypeHeaderValue accept);

    Task Handle<TResult>(HttpContext httpContext, TResult result, CancellationToken cancellationToken);
}

Implementation for JSON

For JSON, we can directly use Ok<TResult> result, which is part of the Minimal API.

public class JsonNegotiator : IResponseNegotiator
{
    public string ContentType => MediaTypeNames.Application.Json;

    public bool CanHandle(MediaTypeHeaderValue accept)
        => accept.MediaType == ContentType;

    public Task Handle<TResult>(HttpContext httpContext, TResult result, CancellationToken cancellationToken)
    {
        // 👇 Use original Ok<TResult> type for JSON serialization
        return TypedResults.Ok(result).ExecuteAsync(httpContext);
    }
}

Implementation for XML

For XML, we can create a custom implementation that uses, for example, DataContractSerializer.

public class XmlNegotiator : IResponseNegotiator
{
    public string ContentType => MediaTypeNames.Application.Xml;

    public bool CanHandle(MediaTypeHeaderValue accept)
        => accept.MediaType == ContentType;

    public async Task Handle<TResult>(HttpContext httpContext, TResult result, CancellationToken cancellationToken)
    {
        httpContext.Response.ContentType = ContentType;

        // 👇 Use DataContractSerializer for XML serialization
        using var stream = new FileBufferingWriteStream();
        using var streamWriter = new StreamWriter(stream);
        var serializer = new DataContractSerializer(result.GetType());

        serializer.WriteObject(stream, result);

        await stream.DrainBufferAsync(httpContext.Response.Body, cancellationToken);
    }
}

Registration

Unfortunately, due to the way IEndpointMetadataProvider works and the way serialization works directly in the Minimal API, I couldn’t find an elegant way to use the DI container (there would be a few inelegant ones 😊). So I resorted to a custom registrar for negotiators.

public static class ContentNegotiationProvider
{
    private static readonly List<IResponseNegotiator> _negotiators = [];

    // 👇 Internal list of negotiators
    internal static IReadOnlyList<IResponseNegotiator> Negotiators => _negotiators;

    // 👇 Add negotiator to the list
    public static void AddNegotiator<TNegotiator>()
        where TNegotiator : IResponseNegotiator, new()
    {
        _negotiators.Add(new TNegotiator());
    }
}

We register the negotiators in Program.cs or Startup.cs.

ContentNegotiationProvider.AddNegotiator<JsonNegotiator>();
ContentNegotiationProvider.AddNegotiator<XmlNegotiator>();

ContentNegotiationResult<TResult>

public class ContentNegotiationResult<TResult>(TResult result)
    : IResult, IEndpointMetadataProvider, IStatusCodeHttpResult, IValueHttpResult
{
    private readonly TResult _result = result;

    // ...

    public Task ExecuteAsync(HttpContext httpContext)
    {
        if (_result == null)
        {
            httpContext.Response.StatusCode = StatusCodes.Status204NoContent;
            return Task.CompletedTask;
        }

        // 👇 Get negotiator based on Accept header
        var negotiator = GetNegotiator(httpContext);
        if (negotiator == null)
        {
            httpContext.Response.StatusCode = StatusCodes.Status406NotAcceptable;
            return Task.CompletedTask;
        }

        // 👇 Set status code
        httpContext.Response.StatusCode = StatusCode;

        // 👇 Handle the result
        return negotiator.Handle(httpContext, _result, httpContext.RequestAborted);
    }

    private static IResponseNegotiator? GetNegotiator(HttpContext httpContext)
    {
        var accept = httpContext.Request.GetTypedHeaders().Accept;
        // 👇 Get negotiator based on Accept header (use ContentNegotiationProvider)
        return ContentNegotiationProvider.Negotiators.FirstOrDefault(n =>
        {
            return accept.Any(a => n.CanHandle(a));
        });
    }

    //...
}

To make the documentation nicely generated and contain information about possible formats, we can implement IEndpointMetadataProvider.

static void IEndpointMetadataProvider.PopulateMetadata(MethodInfo method, EndpointBuilder builder)
{
    // 👇 Add produces response type metadata
    builder.Metadata.Add(new ProducesResponseTypeMetadata(StatusCodes.Status200OK, typeof(TResult),
        ContentNegotiationProvider.Negotiators.Select(n => n.ContentType).ToArray()));
}

Helper method

Let’s create a static helper for ease of use.

public static class Negotiation
{
    public static ContentNegotiationResult<T> Negotiate<T>(T result)
        => new(result);
}

Usage

app.MapGet("/products", () =>
{
    // 👇 Use Negotiation
    return Negotiation.Negotiate(new List<Product>() { new(1, "Product 1", 100) });
});

app.MapGet("/products/{id}", GetProduct);

static Results<ContentNegotiationResult<Product>, NotFound> GetProduct(int id)
{
    if (id == 1)
    {
        // 👇 Use Negotiation
        return Negotiation.Negotiate(new Product(1, "Product 1", 100));
    }
    else
    {
        return TypedResults.NotFound();
    }
}

That’s it ✅.

### GET products as XML
GET http://localhost:5210/product/
Accept: application/xml

### Response
<ArrayOfProduct xmlns="http://schemas.datacontract.org/2004/07/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Product>
    <Id>1</Id>
    <Name>Product 1</Name>
    <Price>100</Price>
  </Product>
</ArrayOfProduct>

⚠️ This solution is just a basic suggestion and does not cover all possible scenarios. For example, the way it is done you can only use it for 200 OK answers (but it can be extended).

The full example is on GitHub.