# Backend Dotnet

> Deliver C# and .NET backends with explicit API, validation, auth, async, and operational patterns centered on ASP.NET Core.

- Skill: `hantechnology/backend-dotnet` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hantechnology/backend-dotnet`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hantechnology/backend-dotnet/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: HanTechnology (https://skillmd.com/u/hantechnology)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hantechnology/backend-dotnet

---


# Backend .NET

Use this pack for .NET backend work: ASP.NET Core APIs, service layers, auth flows, background processing, data access, and server-side delivery patterns that live in the C# ecosystem.

Defer first-pass route choice and lane selection to `../../reference/routing-matrix.md`.

This is the general .NET backend pack for the repo. Use the overlay in `reference/aspnet-core.md` to tune decisions for controllers, minimal APIs, middleware pipelines, and hosted-service behavior while preserving the same quality bar for contracts, validation, documentation, and runtime clarity.

## Setup posture

- Prefer modernizing, refining, or extending an existing project in place.
- Treat scaffold, `create`, `init`, or `new` flows as greenfield-only and explicit-request-only. Defer to `.opencode/reference/project-setup-policy.md`.

## Core focus

- Design API contracts that are stable across controllers, minimal APIs, filters, and client integrations.
- Keep validation, model binding, and error responses explicit so failures are predictable.
- Choose authentication and authorization flows deliberately: cookies, JWTs, OAuth2, policy-based auth, claims, or service credentials.
- Treat async I/O, hosted services, queue consumers, and cancellation as part of the service design.
- Keep OpenAPI, health signals, and failure semantics visible at the backend edge.

## Shared .NET backend standards

- Keep endpoints thin and move orchestration plus business rules into services that are not coupled to transport or EF internals.
- Decide deliberately between controllers and minimal APIs based on surface area, reuse, and clarity.
- Use request models, validation rules, and `ProblemDetails`-style errors so contracts stay consistent under change.
- Keep dependency-injection lifetimes explicit and make background work, retries, and scheduled execution easy to trace.
- Honor `CancellationToken`, timeouts, and graceful shutdown expectations on I/O-heavy paths.
- Document shared APIs with OpenAPI and keep auth policies, claims, and role checks close to the endpoint surface.

## Default workflow

1. Inspect the current endpoint style, DI setup, and hosting model.
2. Choose the ASP.NET Core overlay in `reference/aspnet-core.md`.
3. Define contracts, validation, auth flow, background behavior, and cancellation boundaries before widening the implementation.
4. Implement endpoints, services, and docs together so runtime behavior stays legible.
5. Run `review-work` after substantial backend changes.

## Collaboration in this repo

- Use `Explore` before editing so the new work matches local endpoint, middleware, and service patterns.
- Use `Librarian` or `Context7` when framework APIs, auth configuration, or hosting behavior need a source-of-truth check.
- Pair with `architecture-integration` when the hard part is really service boundaries, contracts, or client coordination.

## Overlays

- `reference/aspnet-core.md` for controllers, minimal APIs, middleware pipelines, endpoint filters, EF-adjacent services, and hosted background work.

## Guardrails

- Do not leak EF entities, request objects, or framework-specific state through the whole service layer.
- Do not ignore cancellation, retry, and graceful shutdown semantics on long-running paths.
- Do not let DI lifetime mistakes turn background or request behavior into production-only bugs.