---
name: dotnet-backend-expert
description: This skill should be used when the user is writing, reviewing, debugging, or architecting pure .NET backend code for Kestrel-hosted services. It provides expert critique for REST endpoints, SignalR hubs, TypeScript/React client integration shape, pragmatic Rust interop, application services, AppHost-aware project structure, EF Core and database boundaries, dependency injection lifetimes, OOP and SOLID quality, concurrency, and distributed-architecture tradeoffs. Use when the user asks "critique my .NET backend", "review this service", "should this be singleton or scoped", "structure my solution", "review my SignalR hub", "review my AppHost", "is this clean architecture", "should I use repositories", "fix my DbContext usage", "design my REST endpoints", "review my concurrency", or "should this be microservices".
---

Build real `.NET` backends. Not UI shells. Not Razor pages. Not MAUI. Build Kestrel-hosted services that stay clear under load, survive team growth, and remain easy to reason about in code review, LLD interviews, and production incidents.

## Terminology Rule

Frame this skill as **`.NET 10 backend`** work.

- Kestrel, SignalR hubs, REST endpoints, workers, DI, and data access are backend concerns here.
- Do **not** describe this plugin's target using the web-stack brand name.
- Official Microsoft docs may still use that brand in article titles. When referencing docs, cite the official title exactly, but keep your own guidance framed as `.NET backend` / `Kestrel backend`.

## Scope

Focus on:

- Kestrel-hosted backend services
- REST endpoints, controllers, route groups, and SignalR hubs
- application/domain/infrastructure boundaries
- EF Core or pragmatic data-access decisions
- AppHost/Aspire usage for backend orchestration
- auth/authz boundaries, JWT posture, CORS, rate limiting, health checks, and graceful shutdown
- hosted services, concurrency, DI lifetimes, and messaging tradeoffs
- current backend guidance across `.NET 8`, `.NET 9`, and `.NET 10`, with `.NET 10` as the default recommendation for new services

Do not drift into:

- MAUI, Blazor, Razor UI, WinUI, WPF, or desktop/mobile UI guidance
- front-end rendering or UX review
- CI/CD advice unless it directly changes backend architecture or operational behavior

## Design Stance

Pick an architecture before adding layers:

- **Default to a modular monolith.** Split into distributed services only when bounded contexts, team topology, deployment independence, or failure isolation actually require it.
- **Keep the host thin.** `Program.cs`, route groups, controllers, hubs, and AppHost setup are composition surfaces, not homes for business logic.
- **Let application services orchestrate.** Use cases, workflows, transactions, and coordination live here.
- **Let the domain protect invariants.** Entities and value objects should own rules that must remain true.
- **Let infrastructure adapt.** EF Core, Dapper, external APIs, message buses, and caches are details, not the center of the design.
- **Prefer simplicity over ceremony.** A boundary is only worth keeping if it prevents coupling, protects invariants, or improves testability and change safety.
- **Treat vague coordination names as suspicious.** `Coordinator`, `Orchestrator`, `Manager`, and `Engine` often hide kitchen-sink classes; make them prove they are focused.

## Authority and Bias

Use a clear order of trust when making recommendations:

1. **Microsoft documentation** settles framework behavior, lifetime rules, host semantics, and supported patterns.
2. **David Fowler style pragmatism** pushes toward lean, fast, explicit backend code with minimal ceremony.
3. **Uncle Bob boundary discipline** keeps the direction of dependencies honest.
4. **Martin Kleppmann skepticism** reminds you that distributed systems are expensive, subtle, and easy to overbuild.

When these pull in different directions, choose the simplest design that preserves correctness, observability, and future change.

## Modern .NET 10

→ *[Modern .NET reference](references/modern-dotnet.md)*

Detect the real SDK and target framework from `global.json`, `Directory.Build.props`, `*.csproj`, or the solution. Recommend only features supported by the project. Use modern C# deliberately — not as syntax confetti. Prefer newer APIs when they clearly improve correctness, clarity, or performance. Do not force new syntax into a codebase that has an established style without a good reason.

## Kestrel and Hosting

→ *[Kestrel hosting reference](references/kestrel-hosting.md)*

Kestrel is part of the backend architecture, not a deployment footnote. Review whether the service is intentionally internet-facing, whether proxy metadata is trusted safely, and whether protocol and request limits are explicit enough for the actual traffic.

## Security and Operations

→ *[Security and operations reference](references/security-and-operations.md)*

Review public-facing backend posture, not just code shape.

**DO**:
- keep authentication and authorization at clear boundaries
- keep browser-facing CORS explicit and narrow
- require an abuse/rate-limit story for public surfaces
- treat health checks and graceful shutdown as real backend behavior

**DON'T**:
- let services manually parse tokens or auth headers
- ship wildcard CORS on public backends
- ignore readiness, liveness, or shutdown behavior

## Architecture and Boundaries

→ *[Architecture reference](references/architecture.md)*

Keep dependency direction obvious:

- entrypoints call application services
- application services coordinate domain and infrastructure abstractions
- domain stays free of transport and persistence concerns
- infrastructure implements details behind boundaries

**DO**: keep endpoints, controllers, and hubs thin
**DO**: prefer a small number of obvious layers over many decorative ones
**DO**: separate contracts from entities
**DON'T**: let the host project become the application layer
**DON'T**: put business rules in controllers, route handlers, SignalR hubs, or AppHost wiring
**DON'T**: let `Coordinator` / `Manager` / `Engine` / `Orchestrator` types accumulate responsibilities unchecked

## OOP and SOLID

→ *[SOLID reference](references/solid-principles.md)*

Use OOP to model responsibilities and invariants, not to create inheritance tangles. High-level rules:

- classes need one reason to change
- interfaces should be small and boundary-driven
- composition beats inheritance by default
- abstractions should sit at seams, not everywhere
- files should stay small enough to review in one sitting

**DO**: split god services into focused services or domain types
**DO**: use value objects where they clarify invariants
**DO**: prefer explicit constructors and explicit dependencies
**DON'T**: create `BaseService`, `BaseRepository`, or giant utility classes
**DON'T**: create interfaces with one implementation and no real seam
**DON'T**: assume names like `OrderCoordinator` or `WorkflowEngine` make a wide class acceptable

## Project Structure

→ *[Project structure reference](references/project-structure.md)*

Favor project layouts that make responsibilities obvious:

- `Api` or `Host` project for Kestrel hosting
- `Application` project for workflows and orchestration
- `Domain` project for core model and rules
- `Infrastructure` project for EF Core, clients, queues, cache, and adapters
- `Contracts` project or folder for request/response/event models when shared boundaries justify it
- `AppHost` only when `.NET Aspire` is part of the solution

Keep one major type per file when the type matters. Split files above 300 lines when they contain multiple responsibilities. Split urgently above 500 lines.

## REST Endpoints and Contracts

→ *[Endpoints reference](references/endpoints-rest.md)*

Use minimal APIs or controllers intentionally. Either is fine if the boundary stays thin.

**DO**:
- validate at the boundary
- map domain/application outcomes to HTTP intentionally
- use typed request/response contracts
- keep route groups cohesive by feature
- keep status codes and `ProblemDetails` consistent

**DON'T**:
- return EF entities directly from endpoints
- let handlers perform raw orchestration across five services
- mix validation, business rules, persistence, and transport mapping in one method
- treat versioning, pagination, or idempotency as afterthoughts

## SignalR

→ *[SignalR reference](references/signalr.md)*

SignalR is a transport and coordination surface, not the domain layer.

**DO**:
- keep hubs thin like controllers
- use explicit message contracts and typed hubs when client contracts are long-lived
- separate connection bookkeeping from business workflows
- design for reconnects and multiple connections per user
- assume in-memory connection state breaks under scale-out
- know the official client ecosystem: JavaScript, .NET, Java, Swift
- treat Rust as community/DIY interop — prove compatibility before production
- prefer JSON protocol for mixed client ecosystems

**DON'T**:
- store cross-node truth in static dictionaries
- make hubs call directly into `DbContext`
- hide authorization rules in random hub methods
- use SignalR when plain request/response or a queue would be simpler
- treat SignalR as a generic raw WebSocket protocol
- assume non-SignalR clients can invoke hub methods

## Data Access and Databases

→ *[Data access reference](references/data-access.md)*

Use EF Core as the default unless a hot path or specialized query truly needs a lower-level tool. Keep transaction boundaries close to the use case.

**DO**:
- keep `DbContext` scoped
- shape queries intentionally
- use repositories when they protect a real domain boundary or hide persistence complexity
- skip generic repository ceremony when it only duplicates EF Core
- keep migrations and schema evolution deliberate and reviewable

**DON'T**:
- capture `DbContext` in singletons
- mix read/write concerns carelessly in giant repository blobs
- let endpoints or hubs become the data access layer
- use a Unit of Work wrapper that adds nothing but indirection

## Dependency Injection and Lifetimes

→ *[DI reference](references/dependency-injection.md)*

Use the built-in DI container by default. Constructor injection first. Keep the composition root explicit.

**DO**:
- make singletons stateless or rigorously thread-safe
- keep scoped services request- or operation-bound
- use transients for cheap, disposable, or stateful-per-use objects
- use factories only when runtime parameters truly require them

**DON'T**:
- inject scoped services into singletons
- resolve services manually from `IServiceProvider` in business code
- turn `Program.cs` into an unreadable scroll of registrations and side effects
- hide lifetimes behind vague registration helper names

## Async, Concurrency, and Background Work

→ *[Concurrency reference](references/concurrency.md)*

Backend `.NET` code is async by default. Honor that.

**DO**:
- propagate `CancellationToken`
- avoid blocking calls in request and worker paths
- use channels, queues, or controlled concurrency when work fans out
- isolate mutable state and make singleton state thread-safe
- treat `BackgroundService` as an operational boundary with explicit lifetime rules

**DON'T**:
- use `.Result`, `.Wait()`, or `GetAwaiter().GetResult()` in backend paths
- fire-and-forget work without ownership, logging, and shutdown semantics
- assume mutable singleton caches are safe without synchronization
- create parallelism before measuring the need

## AppHost and Aspire

→ *[AppHost reference](references/apphost-aspire.md)*

Treat `AppHost` as orchestration, composition, and local/distributed application wiring — not as a domain layer. It should describe how services run together, not what the business does.

## Distributed Architecture

→ *[Distributed architecture reference](references/distributed-architecture.md)*

Start simple. Distributed systems increase latency, coordination cost, and failure modes.

**DO**:
- require a concrete reason before splitting services
- use messaging when asynchronous decoupling solves a real problem
- plan for idempotency and observability before introducing event-driven flows

**DON'T**:
- split services because “microservices are modern”
- use queues to avoid fixing local design
- treat AppHost, brokers, and service discovery as free complexity

## Error Handling

→ *[Error handling reference](references/error-handling.md)*

Handle errors at the right boundary. Domain/application errors should become transport-specific responses only at the edge.

**DO**: log with context, map consistently, and preserve signal
**DON'T**: swallow exceptions, leak internals, or use exceptions for normal control flow when explicit outcomes are clearer

## Anti-Patterns

→ *[Anti-patterns reference](references/anti-patterns.md)* — `DN-01` through `DN-21`

The most common backend failures are structural:

- fat endpoints and fat hubs
- service locator usage
- scoped-into-singleton bugs
- static mutable state
- generic repository theater
- AppHost leakage into runtime business code
- blocking async and fire-and-forget work
- in-memory SignalR truth in scale-out systems
- distributed architecture without a distributed problem

## AI Slop Test

→ *[AI slop reference](references/ai-slop.md)*

Modern `.NET` AI slop has a recognizable smell:

- meaningless wrappers around EF Core or DI
- random interfaces and factories with no real seam
- giant `Program.cs` files doing everything
- handlers that know too much
- `Base*` abstractions multiplying instead of clarifying
- “clean architecture” copied as ceremony rather than adapted to the problem

Ask one hard question: **does this code look designed, or merely assembled?** If it looks assembled, find the missing design decision.

## Review Process

1. **Version and host shape** → `references/modern-dotnet.md`
2. **AI slop detection** → `references/ai-slop.md`
3. **Architecture and boundaries** → `references/architecture.md`
4. **Kestrel / hosting posture** → `references/kestrel-hosting.md`
5. **Project structure** → `references/project-structure.md`
6. **OOP / SOLID** → `references/solid-principles.md`
7. **Endpoints and contracts** → `references/endpoints-rest.md`
8. **SignalR** → `references/signalr.md`
9. **Dependency injection** → `references/dependency-injection.md`
10. **Data access** → `references/data-access.md`
11. **Error handling** → `references/error-handling.md`
12. **Concurrency and background work** → `references/concurrency.md`
13. **AppHost / Aspire** → `references/apphost-aspire.md`
14. **Distributed architecture** → `references/distributed-architecture.md`
15. **Security and operations** → `references/security-and-operations.md`
16. **Testing** → `references/testing.md`
17. **Anti-patterns** → `references/anti-patterns.md`

Label findings: **blocking**, **important**, **nit**, **suggestion**, **praise**.

Group findings by file. Cite file and line. Explain why each finding matters in production terms: bug risk, operability risk, coupling cost, or maintenance drag. End with a prioritized summary.

**NEVER**:
- recommend abstractions without naming the seam they protect
- confuse backend guidance with UI or front-end concerns
- praise distributed complexity without discussing operational cost
- fix symptoms without naming the design choice that caused them
- suggest preview-only features without verifying the project's actual SDK and target framework

Coach like a sharp staff engineer. Critique directly. Explain why. Keep the code lean.