ASP.NET Core

Pathrule3 Rules • 4 Memories • 1 Skill

ASP.NET Core makes HTTP APIs concise, but correctness still depends on middleware order, dependency-injection lifetimes, configuration validation, cancellation, error contracts, and data boundaries. This bundle covers Minimal APIs and controllers without forcing one architecture, and aligns runtime behavior with focused tests. Unlike Spring Boot, it follows the .NET hosting, middleware, options, DI, and Entity Framework Core conventions.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

Web/

Middleware order is an explicit security and behavior contract

Minimal APIs and controllers are HTTP adapters

Problem Details is the public error contract

Infrastructure/

Options bind to typed contracts and validate at startup

Dependency lifetimes match ownership and concurrency

EF Core migrations are reviewed deployment artifacts

Application/

Cancellation and async flow reach every owned dependency

tests/

review-aspnet-core-service

Rules

Middleware order is an explicit security and behavior contract/src/WebhighstrictException handling, forwarding, HTTPS, static files, routing, CORS, authentication, authorization, rate limits, endpoints, and fallbacks are ordered deliberately.

1	ASP.NET Core middleware runs in registration order on the request path and unwinds in reverse on the response path, so ordering changes behavior. Keep the production pipeline readable in one composition root or clearly ordered extensions, and document why middleware that depends on routing, identity, endpoint metadata, or response handling sits where it does. Do not rely on template defaults after adding custom requirements.
2
3	- Place authentication before authorization and position CORS, forwarded headers, exception handling, rate limiting, static files, and endpoint-aware middleware according to their data dependencies.
4	- Avoid terminal middleware before endpoints unless it intentionally owns the remaining path.
5	- Keep development-only diagnostics out of production and produce safe errors through the approved handler.
6	- Add integration tests for protected endpoints, preflight requests, forwarded scheme, errors, static files, and unknown routes.
7
8	Verification: Trace representative requests through the actual configured pipeline and confirm each middleware sees the context and endpoint metadata it requires.

Options bind to typed contracts and validate at startup/src/InfrastructurehighstrictRequired configuration is grouped in typed options with constraints, dependency checks, safe defaults, and eager validation before traffic or jobs begin.

1	Scattered IConfiguration string lookups hide missing values, parse failures, security assumptions, and override behavior until a deep request executes. Bind each owned configuration section to a typed options class, validate required fields, ranges, formats, cross-field invariants, and referenced resources, and fail startup with actionable non-secret messages for configuration that must be valid for the deployment.
2
3	- Keep secret values in approved external inputs and prevent option logging, validation errors, or diagnostics from printing them.
4	- Use named options only when variants have clear owners and consumers; avoid a global settings bag.
5	- Decide which options may reload safely and which require immutable startup state or coordinated restart.
6	- Test representative production sources and precedence, including absent, malformed, conflicting, and environment-specific values.
7
8	Verification: Boot the application with each required value missing or invalid and confirm failure happens before the listener or background consumer becomes ready.

Dependency lifetimes match ownership and concurrency/src/InfrastructurehighstrictSingleton, scoped, and transient registrations reflect state ownership, thread safety, disposal, and request or operation boundaries without captive dependencies.

1	The container cannot make a stateful service thread-safe or extend a disposed scope correctly. Use singleton only for thread-safe state that truly spans the application, scoped for one request or explicit operation scope, and transient for lightweight independent instances. Never capture a scoped dependency in a singleton, hosted service, or conventional middleware constructor.
2
3	- Resolve scoped services inside an explicit scope for background work and dispose the scope after the operation.
4	- Inject scoped dependencies into middleware Invoke or InvokeAsync, or use factory-based middleware when constructor injection needs request scope.
5	- Treat DbContext as an operation-scoped unit of work and avoid concurrent use across tasks.
6	- Enable scope and build validation in development and tests, then add concurrency and disposal tests for custom factories.
7
8	Verification: Start the real container, execute concurrent requests and background iterations, and confirm no captive dependency, cross-request state, concurrent context use, or disposal leak appears.

Memories

Minimal APIs and controllers are HTTP adapters/src/WebChoose the endpoint style from binding and extensibility needs, but keep validation, authorization, application flow, and response contracts explicit in both.

1	Minimal APIs provide a concise route-handler model and controllers provide established conventions and extensibility. Neither choice justifies placing persistence queries, transactions, provider calls, or domain branching directly in an HTTP adapter. Bind and validate request contracts, derive identity and tenant from server context, authorize the action, call one application operation, and map typed outcomes to stable responses.
2
3	Use route groups, endpoint filters, conventions, or controller filters only for concerns whose ordering and scope remain obvious. Keep persistence entities out of public serialization and generate OpenAPI from the same contracts tested by clients. See /src/Application for the use-case boundary and /tests for focused adapter tests.

Cancellation and async flow reach every owned dependency/src/ApplicationRequest cancellation propagates through application services, EF Core, HTTP calls, queues, and long-running work without hiding failures or abandoning unsafe effects.

1	ASP.NET Core exposes request cancellation, but it only saves resources when every owned asynchronous boundary accepts and observes the CancellationToken. Pass it through application operations, EF Core queries and saves, HTTP client calls, stream copies, locks, delays, and queue or workflow submission where cancellation is safe. Avoid Task.Run around ordinary async I/O and never use async void for request work.
2
3	Define the commit point after which client disconnect cannot cancel a durable required effect, and use an outbox or background workflow for work that must survive the request. Distinguish cancellation from timeout and unexpected failure in telemetry without returning internal detail. Test cancellation before and after the commit point. See /src/Infrastructure for lifetime and resource cleanup.

Problem Details is the public error contract/src/WebExpected failures map to stable types, statuses, codes, field errors, and correlation references while unexpected exceptions stay internal.

1	Clients need a predictable error shape, not exception class names or environment-dependent text. Use Problem Details or an equivalent consistent contract with stable type or code, HTTP status, safe title, optional field-level validation errors, and a correlation reference. Map domain conflicts, missing resources, authorization denials, rate limits, and dependency failures through one reviewed policy.
2
3	Do not expose stack traces, SQL, connection details, provider payloads, secrets, or existence information that authorization intends to hide. Log unexpected exceptions once at the authoritative boundary with trace correlation and return a generic public result. Keep status and retry semantics consistent across Minimal APIs and controllers. See /tests for contract coverage.

EF Core migrations are reviewed deployment artifacts/src/InfrastructureSchema changes, generated migrations, rollout order, data backfill, compatibility window, locks, and rollback are designed with application deployment.

1	A generated EF Core migration is a starting artifact, not proof that a production database change is safe. Review operations, provider-specific SQL, defaults, indexes, constraints, data size, lock behavior, transaction limits, and reversibility. Separate large backfills from schema deployment and keep old and new application versions compatible during the rollout window.
2
3	Generate migrations from the intended model and verify no unrelated drift appears. Apply them through one controlled deployment identity rather than every web instance racing at startup. Test on production-like data volume, record migration history evidence, and use roll-forward recovery when rollback would lose accepted data. See /src/Application for behavior compatibility and /tests for integration coverage.

Skills

review-aspnet-core-service/testsReview an ASP.NET Core service across hosting, middleware, endpoints, DI, options, cancellation, EF Core, errors, security, and test scope.

1	---
2	name: review-aspnet-core-service
3	description: Review an ASP.NET Core service for runtime ordering, lifetime safety, validated contracts, and deployment behavior.
4	---
5
6	# Review ASP.NET Core Service
7
8	1. Trace application startup, configuration sources, typed options validation, service registrations, hosted services, middleware order, endpoint mapping, readiness, and shutdown.
9	2. Follow representative public and protected requests through binding, validation, identity, tenant, authorization, application operation, DbContext transaction, external effects, cancellation, and Problem Details.
10	3. Inspect singleton, scoped, transient, middleware, HttpClient, DbContext, stream, and background-work ownership for concurrency, captive dependencies, disposal, and retry behavior.
11	4. Review EF Core model changes and migrations for drift, locks, backfill, compatibility, deployment ordering, failure recovery, and production-like evidence.
12	5. Run focused unit and adapter tests plus real-container integration cases for pipeline ordering, configuration failure, authorization, errors, cancellation, concurrency, and database behavior.
13
14	Record failed boundaries and rerun the smallest test that proves each correction before completing the review.

Why this pattern

Agents register services with unsafe lifetimes, place middleware in the wrong order, discover invalid production options after startup, or mix HTTP, business, and EF Core work in one handler.

Built for .NET teams building HTTP APIs, web applications, background services, and data-backed systems with ASP.NET Core.

Keeps your assistant from:

Authorization, CORS, error, or endpoint behavior changing because middleware order drifted
Scoped services such as DbContext being captured by singleton or conventional middleware instances
Production requests reaching features whose required options were never validated

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25