Skip to content
Skills Library
Programming · Building & coding

aspnet-core-api-engineering

/aspnet-core-api-engineering

Engineering skill: ASP.NET Core Web API — how to build and ship a api / service with ASP.NET Core, C#, xUnit. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.

Licence
Apache-2.0
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Engineering skill: ASP.NET Core Web API — how to build and ship a api / service with ASP.NET Core, C#, xUnit. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.

Original author description

Engineering skill: ASP.NET Core Web API — how to build and ship a api / service with ASP.NET Core, C#, xUnit. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.

How it works

  1. Stack
  2. Commands
  3. Structure
  4. Naming
  5. From design and experience skills
  6. Conventions
  7. Do
  8. Don't
  9. Quality gates
  10. Workflow
Original SKILL.md headings · 171 lines, 1,388 words
SKILL.md preview
---
name: aspnet-core-api-engineering
description: "Engineering skill: ASP.NET Core Web API — how to build and ship a api / service with ASP.NET Core, C#, xUnit. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code."
type: engineering
stack: api
core: "1.0"
checked: 2026-10-26
---

# ASP.NET Core Web API

A C# Web API on ASP.NET Core with minimal-API endpoint groups, EF Core migrations and integration tests that boot the real host.

For line-of-business backends, integration services and product APIs on .NET. Published as a self-contained container image and run behind a reverse proxy or load balancer, with health checks and OpenTelemetry built in.

## Stack
- **Language:** C# 13+ — Nullable reference types and records make contracts explicit.
- **Framework:** ASP.NET Core .NET 10 (LTS) — Minimal APIs, built-in DI, auth, rate limiting and OpenAPI generation.
- **State:** Stateless requests; distributed cache when needed — Any instance can serve any request.
- **Data:** PostgreSQL or SQL Server with EF Core EF Core 10 — LINQ queries, migrations and change tracking in one library.
- **Build:** dotnet CLI .NET 10 SDK — Restore, build, test and publish with one tool.
- **Hosting:** Container platform with health probes — Rolling updates gated on /health/ready.
- **Package manager:** NuGet with central package management Directory.Packages.props — One place for every package version.
- **Testing:** xUnit ^2.9 — Standard .NET test framework.
- **Testing:** WebApplicationFactory Microsoft.AspNetCore.Mvc.Testing — Boots the real host in memory for API tests.
- **Testing:** Testcontainers for .NET ^4 — Integration tests against a real database.

## Commands
- dev: `dotnet watch --project src/Api`
- lint: `dotnet format --verify-no-changes && dotnet build -warnaserror`
- test: `dotnet test`
- build: `dotnet publish src/Api -c Release`
- deploy: `dotnet publish src/Api -c Release -t:PublishContainer`
- install: `dotnet restore`

## Structure
- `src/Api/Program.cs` — Host setup: services, middleware order, endpoint group registration
- `src/Api/Features/<Feature>/` — Endpoints, request/response records, validators and handlers per feature
- `src/Api/Infrastructure/` — DbContext, EF configurations, external clients
- `src/Api/Migrations/` — EF Core migrations
- `tests/Api.Tests/` — Unit tests for handlers and validators
- `tests/Api.IntegrationTests/` — WebApplicationFactory tests against a containerised database
- `Directory.Build.props` — Shared settings: nullable on, warnings as errors, analyzers

## Naming
- Files: PascalCase.cs, one type per file
- Tests: <Type>Tests.cs; methods Method_Scenario_Expected
- Branches: type/short-description, e.g. feat/supplier-sync

## From design and experience skills
This stack has no UI; design skills do not apply.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events `object_action` from its measures.

## Conventions
### Code
- Prefer small, pure functions and explicit types at module boundaries. _(Easier to test, review and change.)_
- Group endpoints per feature with MapGroup and keep each handler a small static method or class taking its dependencies as parameters. _(Features stay discoverable and handlers are unit-testable.)_
- Enable nullable reference types and treat warnings as errors in Directory.Build.props. _(Null mistakes fail the build instead of production.)_

### Components
- Components read design tokens; no raw hex values, pixel sizes or font names in component code. _(One token change restyles the product.)_

### Data
- Analytics events are object_action in snake_case and come from the experience skill’s measures. _(Names stay consistent across teams and tools.)_
- Bind requests to record types and validate them with an endpoint filter (FluentValidation or DataAnnotations) before the handler runs. _(Invalid input never reaches business logic.)_
- Use AsNoTracking for reads, project to response records with Select, and pass CancellationToken to every async EF call. _(Smaller queries and requests that stop work when the client goes away.)_

### Errors
- Every async action has loading, empty, error and success states, matching the experience skill. _(Unhandled states are where users get stuck.)_
- Register AddProblemDetails and UseExceptionHandler; return TypedResults so OpenAPI shows every status. _(Clients get consistent errors and accurate docs.)_

### Security
- Secrets never live in the repository; read them from the environment or a secret store. _(A leaked key outlives the commit that removed it.)_
- Validate every input on the server, even when the client already did. _(Clients can be bypassed.)_
- Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. _(Cheap protection against the most common attacks.)_
- Call RequireAuthorization on the root group and use policies for roles; AllowAnonymous is explicit and reviewed. _(New endpoints fail closed.)_

### Accessibility
- Use native elements first; add ARIA only when no native element fits. _(Native controls bring keyboard and screen-reader support for free.)_

## Do
- Bind options classes with ValidateOnStart for configuration
- Use IHttpClientFactory with timeouts and resilience handlers for outbound calls
- Apply the built-in rate limiter to write and auth endpoints

## Don't
- Block on async code with .Result or .Wait()
- Expose EF entities as response bodies
- Keep secrets in appsettings.json; use environment variables or a secret store

## Quality gates
| Gate | Tool | Threshold | When |
|---|---|---|---|
| Lint and types | dotnet build -warnaserror + .NET analyzers + dotnet format | 0 warnings, 0 errors | Every pull request |
| Unit and component tests | The stack’s test runner | All pass; every design-skill component state covered | Every pull request |
| Performance budget | k6 or NBomber load test against the preview environment | p95 ≤ 200ms and p99 ≤ 500ms at target RPS; error rate < 0.1% | Every pull request touching an endpoint or query |
| Dependency and secret scan | Dependency audit + secret scanner | No high or critical findings; no secrets | Every pull request and nightly |
| Preview deploy | Hosting preview environment | A working preview link on the pull request | Every pull request |

## Workflow
- Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

**Review checklist**
- Correctness: does it do what the issue asks, including edge cases?
- Readability: could a new teammate change it safely?
- Architecture: is it in the right place, with the right boundaries?
- Security: inputs, secrets, permissions, dependencies
- Performance: budgets, queries, bundle size
- Tests fail when the code is broken (flip a condition and re-run)
- One approving review; two for auth policies, migrations or data deletion
- Reviewer checks the generated OpenAPI diff

**Definition of done**
- Acceptance criteria met and demoed on the preview link
- Tests added for new behaviour and every state
- Accessibility and performance gates green
- Analytics events named from the experience skill
- Docs or changelog updated when behaviour changes
- Every endpoint returns TypedResults for each status it can produce
- Integration test covers success, 400 validation and 403 forbidden

**Release**
- Small pull requests (aim for under 400 changed lines)
- CI green before review
- Squash-merge to main; main is always deployable
- Every release has a written rollback path
- Merge to main publishes an image; EF migration bundle runs as a release step before rollout
- Migrations stay compatible with the previous release

**Incidents**
- Roll back by redeploying the previous image tag
- Blameless note within 48 hours

## Overrides of the engineering core
- Journey tests: Replaced by WebApplicationFactory integration tests plus an OpenAPI contract diff — No UI in this stack; the consumer-facing journey is the API contract.
- Accessibility: Not applicable — No UI in this stack; accessibility is owned by the clients that call it.
- components: Not applicable — No design-skill components or tokens in an API service.
- Performance budget: Replaced by server latency targets: p95 ≤ 200ms, p99 ≤ 500ms — Web Vitals and bundle size do not apply to an API.
- Lint and types: Stricter: warnings are errors — The C# compiler and analyzers catch nullability and async misuse as warnings.

## Examples
### Endpoint group (`src/Api/Features/Orders/OrderEndpoints.cs`)

```csharp
using System.Security.Claims;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.EntityFrameworkCore;

namespace Api.Features.Orders;

public static class OrderEndpoints
{
    public record OrderResponse(Guid Id, string Status, long TotalMinor);

    public static RouteGroupBuilder MapOrders(this RouteGroupBuilder group)
    {
        group.MapGet("/{id:guid}", GetOrder);
        return group;
    }

    static async Task<Results<Ok<OrderResponse>, NotFound>> GetOrder(
        Guid id, ClaimsPrincipal user, AppDbContext db, CancellationToken ct)
    {
        var userId = Guid.Parse(user.FindFirstValue(ClaimTypes.NameIdentifier)!);
        var order = await db.Orders.AsNoTracking()
            .Where(o => o.Id == id && o.OwnerId == userId)
            .Select(o => new OrderResponse(o.Id, o.Status, o.TotalMinor))
            .FirstOrDefaultAsync(ct);
        return order is null ? TypedResults.NotFound() : TypedResults.Ok(order);
    }
}
```

## Further reading
- [ASP.NET Core documentation](https://learn.microsoft.com/en-us/aspnet/core/) — Minimal APIs, middleware, authentication and testing.
- [OWASP Top Ten](https://owasp.org/www-project-top-ten/) — The attack classes every endpoint review should check against.
- [OpenTelemetry documentation](https://opentelemetry.io/docs/) — Instrumenting traces, metrics and logs so latency budgets can be measured.
Files in this package (4)
  • AGENTS.md 6 KB
  • README.md 2 KB
  • SKILL.md 10 KB
  • rules/aspnet-core-api-engineering.mdc 4 KB

Versions

The database has no other skills named aspnet-core-api-engineering.

Database snapshot: 13.11.2026 · package version a36fe517a9d6 (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

  • 100csharp-aspnet-core-web-api
    Use this skill when building cross-platform, high-throughput REST APIs and minimal APIs using C# and ASP.NET Core.
  • 100go-http-service-engineering
    Engineering skill: Go HTTP service — how to build and ship a api / service with net/http + chi, Go, go test. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.
  • 100aspnet-core
    ASP.NET Core framework guardrails, patterns, and best practices for AI-assisted development. Use when working with ASP.NET Core projects, or when the user mentions ASP.NET Core. Provides Minimal APIs, EF Core, authentication, middleware, and deployment guidelines.
  • 96aspnet-rest-apis
    Guidelines for building REST APIs with ASP.NET Triggers on: **/*.cs, **/*.json
  • 100nestjs-service-engineering
    Engineering skill: NestJS service — how to build and ship a api / service with NestJS, TypeScript, Jest. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.
  • 100xunit
    Expert xUnit.net testing assistance covering .NET Fact/Theory tests, constructor fixtures, and output capture. Use when writing C# unit tests, testing ASP.NET Core applications, or running `dotnet test`.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.