dotnet new templates for .NET 10, and ek, a tool that generates and updates projects from them.
Release 0.8 has one template: ek-api, a hardened ASP.NET Core HTTP API that fixes the
security, testing and secrets gaps that come up again and again in project reviews.
dotnet new install Erkmangelis.Templates.0.8.0.nupkg
dotnet new ek-api -n RideSense --auth identity --db postgres --agents claudeOr with the tool, which asks what you need, offers presets and rejects unsupported combinations:
dotnet tool install --global Erkmangelis.Ek --add-source <folder with Erkmangelis.Ek.0.8.0.nupkg>
ek new RideSense --preset saas-api
ek update # later, inside the project: merge a newer template version's changesNew here? Follow docs/getting-started.md. The tool: docs/cli.md. Why it is built this way, release by release: docs/learning.
| Option | Values | Default | Adds |
|---|---|---|---|
--auth |
none, identity, external, oidc |
none |
identity: ASP.NET Core Identity accounts with bearer tokens or same-site cookie sessions with antiforgery, lockout, email confirmation and reset, authenticator-app MFA, passkeys. external: the same accounts plus Google, Apple and Microsoft sign-in, linked only on a provider-verified email. oidc: no local accounts; the API trusts access tokens from one OpenID Connect provider, with a development Keycloak and an enterprise SSO (SAML) recipe. Every mode adds roles and permissions, admin endpoints, hashed and scoped API keys, user profiles and an owner-only policy on the example feature, and turns PostgreSQL on when --db is none. |
--db |
none, postgres, sqlserver, sqlite |
none |
EF Core with migrations, record metadata, soft delete, audit history, a migration bundle, compose and a backup script. postgres: PostgreSQL 18 through Npgsql. sqlserver: SQL Server 2022 (Express by default; you accept its licence in .env; amd64 only). sqlite: one file on a volume, no database server. PostgreSQL and SQL Server tests use Testcontainers. A Dapper recipe covers hand-written SQL for hot read paths. |
--email |
none, smtp |
none |
Templated confirmation and reset emails through SMTP (MailKit), Mailpit for local testing. With none, emails are only logged, in development. |
--jobs |
none, hosted, hangfire |
none |
Background jobs: queued jobs (IJob<TArgs> through IJobQueue) and cron-scheduled recurring jobs, bounded retries with backoff, failed-job listing and requeue for admins, idempotent job effects (JobIdempotency) and distributed locks (PostgreSQL advisory locks, SQL Server app locks, lock files with SQLite). hosted: an in-process queue and cron schedules on hosted services; queued jobs are lost on restart. hangfire: Hangfire (LGPL-3.0) storing jobs in the database, so they survive restarts, with a dashboard behind the jobs.manage permission; turns PostgreSQL on when --db is none. Every choice has the scoped background loop for housekeeping. |
--storage |
none, s3 |
none |
Private files on any S3-compatible storage (RustFS in compose, Cloudflare R2 or Amazon S3 in production): uploads through the API, signed upload and download links, and resumable tus uploads; size limits, type checks by file signature, optional ClamAV scanning, SHA-256, WebP thumbnails (SkiaSharp), owner-only access and a cleanup loop for temporary, unfinished, refused and orphaned files. Turns PostgreSQL on when --db is none. |
--documents |
false, true |
false |
CSV and Excel export and import of notes (MiniExcel, Apache-2.0) with formula cells defused, and a PDF report (PdfPig, Apache-2.0, with an embedded Liberation Sans font). |
--realtime |
false, true |
false |
Changes pushed to connected clients over SignalR (/v1/realtime/hub), server-sent events (/v1/realtime/events) and raw WebSockets (/v1/realtime/ws, JSON frames with a version handshake), per user with --auth, with an origin check against cross-site WebSocket hijacking and a bounded queue per connection. |
--notifications |
false, true |
false |
An in-app inbox with read status, per-user channel preferences, and delivery in the background by email (with --email smtp), mobile push (Firebase Cloud Messaging and Apple Push Notification service, called over HTTP) and SMS (Twilio), with retries and dead-device cleanup. Means local accounts when --auth is none. |
--webhooks |
false, true |
false |
Standard Webhooks in both directions: incoming with signature and timestamp checks, duplicate detection and queued handlers; outgoing subscriptions to API events with signed deliveries, retries, a delivery log and SSRF-safe sending. Turns PostgreSQL on when --db is none. |
--cache |
none, memory, redis |
none |
HybridCache (MIT) for values, with stampede protection and tags, plus output caching for same-for-everyone responses; the notes read path is the example, with removal after every save. memory: each instance's memory. redis: Redis as a shared second level (Valkey 9 in compose, Aspire and tests), with a readiness check. |
--monitoring |
false, true |
false |
A monitoring compose profile: an OpenTelemetry Collector, Prometheus scraping /metrics on a separate port, Alertmanager with four tested alert rules, Tempo for traces, Loki for logs and Grafana with the data sources and an API dashboard provisioned. |
--worker |
false, true |
false |
A worker project and image that runs the jobs while the API only queues them. Means --jobs hangfire. |
--aspire |
false, true |
false |
A .NET Aspire AppHost (MIT) that starts the database, the API and the worker for local development, with the Aspire dashboard. |
--agents |
none, shared, claude |
shared |
AGENTS.md written for the chosen options; claude adds a CLAUDE.md that imports it. |
Every --auth mode but none, --jobs hangfire, --storage s3, --notifications and --webhooks need a
database, so with --db none they generate the PostgreSQL output; --notifications means --auth identity
when --auth is none; --worker means --jobs hangfire. Every project gets outbound HTTP clients with
timeouts, retries, a circuit breaker and a host allowlist (Microsoft.Extensions.Http.Resilience). These rules live in
catalog/modules.json: ek applies them and rejects a combination that
breaks one, with the reason. Presets (minimal, saas-api, api-worker alias ek-worker,
sso-api, single-box, realtime) live in catalog/presets.json.
Every combination the catalog's rules accept is supported, and CI tests a set chosen from the
catalog by ek matrix: every preset, plus combinations that cover every pair of option values that
can occur together (20 in all, instead of the hundreds of possible combinations). For each, CI runs
the acceptance test (scripts/acceptance.sh):
- generates the project outside the source tree from the packed
.nupkg, - checks that no template markers and nothing from unselected options are left behind,
- restores, builds with warnings as errors and runs the format check,
- runs all generated tests, including ownership, forbidden-access, mass-assignment, API key scope,
no-secrets-in-logs and (with
--auth external) unverified-email takeover tests, - checks that a deliberate style violation fails the build,
- starts it with
docker composeand expects 200 from/health/ready, and with--email smtpand local accounts, that registering sends a confirmation email to the bundled Mailpit, and with--jobs(or--worker) and no sign-in, that a background job imports notes in the containers, and with--storage s3and no sign-in, that a file uploads to the bundled storage and downloads again through the API and a signed link, - with compose, also scans the history for secrets (gitleaks), runs the k6 load test against the
containers, and with
--monitoringchecks that Grafana shows the API's metrics, traces and logs.
It also fails on any package with a known vulnerability.
CI also generates projects with released versions (0.1.0, 0.3.0, 0.4.0, 0.5.0, 0.6.0 and 0.7.0), commits a file of
the team's own, runs ek update to the current version and runs the same acceptance test on the
result, and builds the API and worker images for amd64 and arm64.
Snapshot tests (tests/Erkmangelis.Templates.Tests) pin the
generated files for each combination, so every change to the output shows up in review. Tool tests
(tests/Erkmangelis.Ek.Tests) check the catalog against the template's
symbols, that ek new and plain dotnet new give identical output for every preset, and the update
merge. --agents only adds or removes AGENTS.md and CLAUDE.md, which a snapshot test checks.
- .NET 10 LTS pinned in
global.json, central package versions, recommended analyzers and naming rules enforced in the build - Typed options validated on start; secrets only in user secrets or environment variables
- ProblemDetails for every error, with a trace id; built-in validation
- OpenAPI with the Scalar UI (Development by default),
/v1routes, paging - Per-caller rate limiting, CORS and forwarded headers from settings, HTTPS redirect, HSTS, security headers
- JSON logs with trace ids, OpenTelemetry traces and metrics (OTLP), live and ready health checks
- Problem responses in the caller's language (English and Turkish resources,
Accept-Language) - Feature flags from configuration (Microsoft.FeatureManagement, MIT), with targeting when there is sign-in
TimeProvider, graceful shutdown- Unit and integration tests (xUnit v3,
WebApplicationFactory) - A multi-arch Docker image (amd64 and arm64), Docker Compose, and a Raspberry Pi or VPS recipe with HTTPS through a Cloudflare Tunnel
- CI with a k6 load test against the container, container publishing with signed provenance, and Dependabot
- Security scanning: vulnerable packages, secrets in the history (gitleaks) and CodeQL
No default dependency needs a commercial licence: no MediatR, no AutoMapper, no Hangfire Pro.
dotnet test tests/Erkmangelis.Templates.Tests # snapshot tests
dotnet test tests/Erkmangelis.Ek.Tests # tool tests
dotnet run --project src/Erkmangelis.Ek -- new # the tool, from source
scripts/acceptance.sh --auth identity --db postgres --email smtp --jobs hangfire --worker true --agents claude --composeTemplate sources live in templates/ek-api. Conditional code uses the template
engine's #if (UsePostgres)-style symbols defined in
template.json. After an intended change to the
output, run the snapshot tests and accept the new output with scripts/accept-snapshots.sh, then review the snapshot diff.
Migrations ship pre-generated in templates/ek-api/.migrations, one set per sign-in mode. After a
change to the EF model, run scripts/add-migration.sh <Name> to add a migration to every set from
the current template; running it again with the newest migration's name replaces that migration.
A new option also needs an entry in catalog/modules.json, a line in the
template's template-origin.json and a regenerated spec schema; the
tool tests say which one is missing. See docs/cli.md.
Releases: push a v* tag. The release workflow packs the template and the ek tool, attests their
build provenance and attaches both .nupkg files to a GitHub release. See CHANGELOG.md.
Security baseline: docs/asvs-l1.md maps OWASP ASVS Level 1 to what the template covers and what each project still owns.