Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

aspnet-core-api-engineering

/aspnet-core-api-engineering

Pomaga budować, testować i wdrażać API w ASP.NET Core i C# z testami xUnit.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

Co robi i kiedy

Pomaga budować, testować i wdrażać API w ASP.NET Core i C# z testami xUnit.

Oryginalny opis (EN)

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.

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 171 linii, 1 388 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (4)
  • AGENTS.md 6 KB
  • README.md 2 KB
  • SKILL.md 10 KB
  • rules/aspnet-core-api-engineering.mdc 4 KB

Wersje

W bazie nie ma innych skilli o nazwie aspnet-core-api-engineering.

Migawka bazy z 13.11.2026 · wersja paczki a36fe517a9d6 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100csharp-aspnet-core-web-api
    Pomaga budować szybkie, wieloplatformowe REST API i minimalne API w C# na ASP.NET Core.
  • 100go-http-service-engineering
    Pomaga budować i wdrażać usługi HTTP w Go na net/http i chi, z testami i wydaniem.
  • 100aspnet-core
    Dostarcza zasady i dobre praktyki dla projektów ASP.NET Core: Minimal APIs, EF Core, uwierzytelnianie, middleware i wdrażanie.
  • 96aspnet-rest-apis
    Podaje zasady budowania REST API w ASP.NET dla plików C# i JSON.
  • 100nestjs-service-engineering
    Pomaga budować, testować i wdrażać usługę API w NestJS, TypeScript i Jest, także przy zamianie specyfikacji designu w kod.
  • 100xunit
    Wspiera testowanie w xUnit.net dla .NET: testy Fact i Theory, fixtury konstruktora, przechwytywanie wyjścia, testy aplikacji ASP.NET Core i dotnet test.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.