dotnet-backend-patterns
/dotnet-backend-patterns
Provides the .NET backend execution contract: solution segregation (Domain/Application/API/Infrastructure), the two sanctioned API modes (CQRS+MediatR pipelines or REPR minimal APIs), EF Core AsNoTracking + DTO projections, async with CancellationToken, and zero-mock integration testing against the real Dev DB. Use if the project uses .NET / C#. Squad-internal execution contract loaded by agents via their Methodology Dependencies table.
- Author
- muhammadshaharyarnaeem ↗
- Repository
- blackgoat-agentskills ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Provides the .NET backend execution contract: solution segregation (Domain/Application/API/Infrastructure), the two sanctioned API modes (CQRS+MediatR pipelines or REPR minimal APIs), EF Core AsNoTracking + DTO projections, async with CancellationToken, and zero-mock integration testing against the real Dev DB. Use if the project uses .NET / C#. Squad-internal execution contract loaded by agents via their Methodology Dependencies table.
Original author description
Provides the .NET backend execution contract: solution segregation (Domain/Application/API/Infrastructure), the two sanctioned API modes (CQRS+MediatR pipelines or REPR minimal APIs), EF Core AsNoTracking + DTO projections, async with CancellationToken, and zero-mock integration testing against the real Dev DB. Use if the project uses .NET / C#. Squad-internal execution contract loaded by agents via their Methodology Dependencies table.
How it works
- Quick card
- Worker Execution Contract
- Deep Dive — Mode-Scoped Playbooks
SKILL.md preview
---
name: dotnet-backend-patterns
description: "Provides the .NET backend execution contract: solution segregation (Domain/Application/API/Infrastructure), the two sanctioned API modes (CQRS+MediatR pipelines or REPR minimal APIs), EF Core AsNoTracking + DTO projections, async with CancellationToken, and zero-mock integration testing against the real Dev DB. Use if the project uses .NET / C#. Squad-internal execution contract loaded by agents via their Methodology Dependencies table."
---
# .NET Backend Patterns
Strict solution segregation, exactly two sanctioned API modes, lean EF Core queries, and tests that run against reality — never against mocks.
## Quick card
Derived from the contract below for a ≤ 3-file change; no new rules (convention #8).
1. Stay in the existing layer; `Domain` stays dependency-free (§ Solution Segregation).
2. Match the declared API mode; never mix (§ API Mode).
3. `BaseResponse<T>` for new APIs; a migration keeps its wire contract (§ Response Pattern).
4. Read-only queries: `AsNoTracking()` plus a DTO projection (§ EF Core).
5. A wire or envelope claim needs Tier 3 (§ Testing Doctrine).
- Brief → the quick note (What / Where / How verified)
- Artifact → the capture at `{quick-root}/evidence/check.md`
- Handoff → the `## Result` bullet in `note.md`
## Worker Execution Contract
This is the operational spine. Follow it as written. For a change of ≤ 3 files outside a pipeline, the Quick card above is the contract; the full contract applies inside a lane.
### Solution Segregation
- Segregate the solution into distinct projects: `Domain` (pure logic, zero dependencies), `Application` (use cases, MediatR handlers), `API` (endpoints/controllers), `Infrastructure` (EF Core, external APIs).
- Third-party packages are isolated in their own projects so they can be reused across solutions. `Domain` references nothing.
- **Mode B (REPR) uses `Api` / `Core` / `DAL.EF` / `Infrastructure` instead** — deliberately diverging from the four-project list above (convention #8): no `Application` project, since REPR has no MediatR handlers; `Core` plays `Domain`'s dependency-free role and holds only contracts — interfaces, models/DTOs, enums, constants, config POCOs; no entities, no EF, Redis, Service Bus or vendor SDK. EF Core lives in `DAL.EF`, whose entities and `AppDbContext` are **scaffolded database-first** from SQL Server as `partial` classes — no hand-written migrations; hand-written model fixes go in `AppDbContext.Partial.cs`. REPR adopted on an existing controller + MediatR solution keeps its `API` / `BLL` / `EF` projects instead — a second deliberate divergence (convention #8): the BLL serves as the service layer and the four-project split is not imposed. See [repr-playbook.md §2](references/repr-playbook.md).
### API Mode — Two Sanctioned Modes, Never Mixed
The blueprint (Aria's `detailed-design.md`) — or, for lite-originated work, the mode constraint recorded in `requirements.md` — declares which mode the project uses. Follow it. Never mix modes, never invent a third.
- **Mode A — CQRS + MediatR:** Commands/queries with pipeline behaviors for authorization, validation, and domain-event dispatch. Generic base controllers (`BaseController<T>`) map every result to the standardized `BaseResponse<T>` envelope from `BG.Infrastructure.Core` — via `ExecuteWithOKCommandResponse` (`ExecuteWithOKResponse` is deprecated — do not use in new code) — so the frontend receives predictable contracts. Do not hand-roll a per-service response type.
- **Mode B — REPR minimal APIs:** Request-Endpoint-Response with minimal APIs exclusively. Everything the route needs lives in the endpoint file. Reusable logic is extracted strictly as decoupled services. NO repository pattern in REPR mode — it is bloat here. All endpoints of a feature live in one `Endpoints/{Feature}/` folder and are mapped by that feature's `{Feature}EndpointsExtension` on one route group. A **new** REPR API emits the **same** `BaseResponse<T>` envelope as Mode A (so the frontend sees one contract), via `.ToResult()` (`IResult` bridge) for success and a native `IExceptionHandler` for failures — not a base controller. A migration of an existing API to REPR keeps that API's wire contract instead (see Response Pattern below), still with one `IExceptionHandler`.
### Response Pattern, Errors & Exceptions (Both Modes)
Every API result — in **both** modes — maps to the standardized `BaseResponse<T>` envelope from `BG.Infrastructure.Core` (`StatusCode`, `IsSuccess`, `Data`, `DataContext`, `Notifications`). One contract, so the frontend interceptor reads every response uniformly. Never return bare payloads or ad-hoc `{ message }` bodies.
- **Errors are structured, not strings.** Failures are conveyed as `Error` records in `BaseResponse.Notifications`. Each `Error` carries a 6-digit `ErrorCode` (`MM`=microservice, `TT`=error type, `NN`=number — compose from the `MicroserviceCodes` / `ErrorTypeCodes` registries, never magic numbers), a message, and optional `PropertyName` / `ActionHint`. The `ErrorType` drives frontend UX (field / popup / toast / redirect / silent).
- **Throw `CustomException`** from handlers/services/domain for expected failures — it carries the `ErrorCode`, HTTP status, and UX context, and maps cleanly to an `Error`.
- **Map failures once, per mode:** Mode A via the `BaseController<T>` try/catch → `.ToActionResult()`; Mode B via a native `IExceptionHandler` → `.ToResult()`. Do not build error envelopes inline in each handler.
- **Mode B migration — the wire contract is preserved.** Deliberate refinement (convention #8) of "every API result maps to `BaseResponse<T>`" above: that rule binds new APIs and separately declared contract changes. A migration of an existing controller + MediatR API to REPR is a pattern change, not a contract change — routes, request shapes, response bodies, status codes and headers stay byte-compatible with the legacy controllers: no envelope, no `/api/v1` prefix the legacy route lacked. Failures are still mapped once, by one `IExceptionHandler` that reproduces the legacy error body rather than the envelope; never a try/catch per handler. "Byte-compatible" is a Tier 3 claim, and that capture's `--require-key` set is the legacy body's keys, not the envelope's. Pattern and handler: [repr-playbook.md](references/repr-playbook.md), "Response Pattern in REPR".
- Full model + code: [response-and-errors.md](references/response-and-errors.md).
### Design Principles — SOLID & Separation of Concerns
Solution Segregation (above) and the two API modes already *are* SOLID applied here. The full mapping — SoC, DIP, SRP, ISP, OCP/LSP, each stated against this contract's own structure — is in [solid-and-separation.md](references/solid-and-separation.md). One rule the sections above do not already imply, and it binds:
- **No `NotImplementedException` interface members.** An implementation honours its interface fully, or the interface is wrong and gets narrowed (ISP). This is the failure mode that surfaced when EF repository implementations drifted from their interfaces.
### EF Core & Data Discipline
- Every read-only query uses `AsNoTracking()`. No exceptions.
- Project to DTOs (`Select(x => new Dto {...})`) instead of hydrating full entities when only a subset is needed.
- No cascade deletes on critical records — configure `DeleteBehavior.Restrict` and handle removal explicitly.
- Handle concurrency explicitly where concurrent writes are possible — optimistic via rowversion/concurrency token + `DbUpdateConcurrencyException` handling; pessimistic via row locks (`SELECT ... FOR UPDATE`) taken inside an explicit transaction.
- **Keep the transaction span in-process.** Nothing between `BeginTransactionAsync` and `CommitAsync` may await an out-of-process dependency — no `HttpClient`, supplier SDK, gateway, or broker call. Locking a row that is shared across all callers (a global settlement, clearing, or sequence account) and then awaiting a remote call serializes the whole endpoint at that remote's latency. Where the span existed to make a locked check-then-write atomic, it is replaced by a committed reservation before the call and a second short transaction after it — never merely by widening the gap between check and write.
### Async Discipline
- Async everywhere on the I/O path. Every async method accepts and propagates a `CancellationToken` down to EF Core and HTTP calls. No `.Result`, no `.Wait()`.
### Testing Doctrine — the Tier Ladder (Zero-Mock)
**"Zero-mock" is scoped to the DATABASE boundary.** It says nothing about the transport, and conflating the two is what let a missing response envelope pass every gate in 2026-08. Each tier proves a different class of claim; a higher tier is never substituted by a lower one.
- **Tier 1 — Unit.** Pure logic in `Domain`/`Application`, at function scope. Fast, no I/O.
- **Tier 2 — Integration (in-process host, real Dev DB).** `WebApplicationFactory<Program>` + `CreateClient()` against the real Dev DB. Mocking `DbContext` (or its providers) is forbidden — a test against a mocked database proves nothing. Anything crossing the database boundary lives here.
**What this tier cannot prove:** it opens no socket, runs no Kestrel, resolves no host startup/config chain, and serves no Swagger — so the entire *what it cannot* column of the Tier Ladder in `{PLUGIN_ROOT}/runtime-evidence/SKILL.md` (the doctrine's owner; this ladder is its .NET application) binds here, including which `JsonSerializerOptions` resolved and whether the Swagger document a human can open exists at all. See [data-and-testing.md](references/data-and-testing.md) §3 for the assertion form that at least catches an unwrapped body *here*.
- **Tier 3 — Out-of-process wire (mandatory for wire claims).** The application started the way a user starts it — real Kestrel, real `Program.cs` environment branch — probed over a socket by an external client (Postman/newman or an HTTP client), with the response body captured to disk. Required for any requirement about the response envelope, status codes, headers, auth challenge shape, or content negotiation. Contract: `{PLUGIN_ROOT}/runtime-evidence/SKILL.md`. This stack's gate invocation is `--require-key isSuccess --require-key notifications --require-key statusCode --require-openapi-reachable`. The OpenAPI flag belongs in the stack contract rather than left to the caller because a .NET API's Swagger endpoint lives behind the very Development environment branch Tier 2 never resolves — so "the document is reachable" is precisely the assertion that separates a started application from a test host.
The `ErrorCode` serialization hazard in [response-and-errors.md](references/response-and-errors.md) is a **Tier 3** obligation specifically: the envelope travels three distinct serialization paths (`ObjectResult`, `Results.Json`, `WriteAsJsonAsync`), each resolving its own options, so it takes at minimum one success capture and one failure capture — cited separately — to prove both. The failure capture doubles as the negative-half proof.
### Build & Test Log Discipline
- When a Python 3 runtime is available, run builds and test runs through `{PLUGIN_ROOT}/pipeline-tools/scripts/run_quiet.py` — the full log lands on disk, and only errors-with-context plus a tail enter the transcript. Invocation shape:
`python {PLUGIN_ROOT}/pipeline-tools/scripts/run_quiet.py --log <path> -- dotnet build` (same shape for `dotnet test`). `run_quiet.py` defaults to a 240s timeout — pass an explicit `--timeout` (e.g. 900) for integration suites hitting the real Dev DB. Treat exit 124 with a `TIMEOUT:` header as a harness result to escalate — never record it as a test FAIL.
- No Python 3 runtime available → fall back to `dotnet build -nologo -v:q -clp:"ErrorsOnly;Summary"` and `dotnet test -nologo --logger "console;verbosity=quiet"`.
- Never paste a full build/test log into a report. Cite the log path plus the relevant excerpt.
- A full-verbosity rerun (`-v:normal`/`-v:detailed`, or dropping `--logger "console;verbosity=quiet"`) is for diagnosing only what the filtered output cannot localize — not the default way to read results.
- Deliberate divergence (convention #8): the no-Python fallback above is tighter than `run_quiet.py`'s no-information-lost guarantee above — `-clp:ErrorsOnly` suppresses warnings outright at the MSBuild level rather than merely filtering them from the transcript, so they are not recoverable from a log afterward. This is deliberate: warning review stays with the reviewer axis (code-review-and-quality) and CI either way, never agent transcripts, so nothing the agent needed is lost.
### Verification Checklist
Before marking work complete:
- [ ] New code lands in the correct project layer; `Domain` remains dependency-free
- [ ] The API mode matches the blueprint; no mode mixing (no repositories in REPR, no ad-hoc endpoints in CQRS)
- [ ] Every read-only query has `AsNoTracking()` and projects to a DTO where a subset suffices
- [ ] No cascade delete introduced on critical records; concurrency handled where writes race
- [ ] No `BeginTransactionAsync` / `FOR UPDATE` span awaits an out-of-process call; any check-then-write invariant that lost its span is carried by a committed reservation
- [ ] All async methods propagate `CancellationToken`; no sync-over-async
- [ ] Integration tests against the real Dev DB cover DB-crossing behavior — zero mocked `DbContext`, no EF InMemory provider. Mode B fast endpoint tests may run the real model on SQLite in-memory instead — a deliberate convention-#8 divergence, scoped in [data-and-testing.md](references/data-and-testing.md) §3.1; they never stand in for a wire claim. (Builders do not author these — verify they exist or flag the gap to the Orchestrator; QA (Quinn) authors them.)
- [ ] Every response of Mode A and of a new Mode B API is a `BaseResponse<T>` envelope from BG.Core; failures are structured `Error`s (registry-composed `ErrorCode`) in `Notifications`, mapped once via `ToActionResult<T>()` (Mode A) or `ToResult<T>()` + `IExceptionHandler` (Mode B) — no bare payloads, no ad-hoc status codes. A Mode B migration instead keeps the legacy wire contract, failures mapped once by one `IExceptionHandler` reproducing the legacy error body, proven by Tier 3 captures of the legacy and the migrated app (Response Pattern)
- [ ] Every response-envelope claim is backed by a **Tier 3** capture under `evidence/runtime/` — never by a `WebApplicationFactory` test alone, and never by a source read of the wrapper's registration
- [ ] Dependencies point inward (DIP): `Core`/`Domain` defines interfaces, `Infrastructure` implements, concretes bind only at the composition root; no framework/IO types leak into `Domain`/`Core`; no `NotImplementedException` interface members
### Escalate When
- The blueprint does not declare an API mode, or the requested change requires mixing modes → report to the Orchestrator.
- The Dev DB is unreachable or its schema diverges from migrations → report to the Orchestrator; do not fall back to mocks.
- The application cannot be started out-of-process in this environment (Tier 3 impossible) → report to the Orchestrator and record the wire criterion `BLOCKED`. **Never substitute Tier 2** — an in-process pass on a wire claim is a fabrication in effect (`base-persona.md`, Evidence Integrity).
- A requirement demands cascade delete on critical records or an untracked write path → report to the Orchestrator before implementing.
## Deep Dive — Mode-Scoped Playbooks
Read on demand. **Load only the playbook for the mode the blueprint declares**, plus the shared data/testing one — don't load the other mode's playbook (it's noise for this project).
- **Mode A →** [cqrs-playbook.md](references/cqrs-playbook.md) — MediatR validation pipeline behavior, and how Mode A emits the Response Pattern via `BaseController<T>` (`ExecuteWithOKCommandResponse`; `ExecuteWithOKResponse` is deprecated — do not use in new code).
- **Mode B →** [repr-playbook.md](references/repr-playbook.md) — REPR + Vertical Slice patterns for a new API and for REPR on an existing API / BLL / EF solution: endpoint file structure, feature endpoint grouping, endpoint filters (replacing MediatR behaviors), database-first scaffolding, `IQueryable<T>` extensions, DI composition root, a worked case study, anti-patterns from earlier conversions, and how REPR emits the Response Pattern (or preserves a legacy contract) through one `IExceptionHandler`.
- **Both modes →** [response-and-errors.md](references/response-and-errors.md) — the shared `BaseResponse<T>` envelope, the `Error` / `ErrorCode` model + code registries, `Notifications`, `CustomException`, and the per-mode emit paths.
- **Both modes →** [data-and-testing.md](references/data-and-testing.md) — AsNoTracking + projection GOOD/BAD, async + `CancellationToken` propagation, and the zero-mock integration-test-against-Dev-DB pattern.
- **Both modes →** [solid-and-separation.md](references/solid-and-separation.md) — SoC, DIP, SRP, ISP and OCP/LSP mapped onto the structural rules above, as vocabulary for a review.
Files in this package (6)
- SKILL.md 17 KB
- references/cqrs-playbook.md 4 KB
- references/data-and-testing.md 7 KB
- references/repr-playbook.md 75 KB
- references/response-and-errors.md 11 KB
- references/solid-and-separation.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · muhammadshaharyarnaeem/blackgoat-agentskills | 100 | MIT |
| rmyndharis/antigravity-skills | 100 | MIT |
| agent-skills-hub/agent-skills-hub | 100 | MIT |
| wshobson/agents | 95 | MIT |
| tranhieutt/software_development_department | 90 | MIT |
Database snapshot: 13.11.2026 · package version b9b6badadb08 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95dotnet-patterns
Use this skill when implementing .NET patterns — MediatR pipelines, CQRS, Result pattern, EF Core patterns, pipeline behaviors, and event sourcing. This skill enforces: MediatR for CQRS, FluentValidation for validation, Result type for error handling, EF Core conventions.… - 100dotnet-core-expert
Use when building .NET 8 applications with minimal APIs, clean architecture, or cloud-native microservices. Invoke for Entity Framework Core, CQRS with MediatR, JWT authentication, AOT compilation. - 95dotnet-expert
Use when building .NET 8/9 applications, ASP.NET Core APIs, Entity Framework Core, MediatR CQRS, modular monolith architecture, FluentValidation, Result pattern, JWT authentication, or any C# backend development question. - 90dotnet-architecture
Use this skill when structuring .NET applications — clean architecture, vertical slices, CQRS, MediatR, dependency injection, and project organization. This skill enforces: solution structure conventions, dependency flow direction, DI registration patterns, and architecture… - 100dotnet-core-expert
Use when building .NET 8 applications with minimal APIs, clean architecture, or cloud-native microservices. Invoke for Entity Framework Core, CQRS with MediatR, JWT authentication, AOT compilation. - 100clean-architecture-scaffolder
Scaffold a .NET solution using Clean Architecture or Vertical Slice Architecture. Use this skill whenever the user wants to start a new .NET project/solution, structure an existing one, add a new feature/use-case/slice, set up layers (Domain, Application, Infrastructure, API),…