An option-driven template specification for teams building .NET APIs, backend services, integrations, and background workers with consistent engineering defaults.
Status: The template contract and its supported generation paths are implemented and validated. Production broker adapters, durable outbox dispatch, and Hangfire storage are optional reference extensions, not template release blockers.
The project aims to reduce repeated setup decisions while keeping generated services proportional to their needs. Consumers select capabilities explicitly, and compatibility rules prevent invalid or misleading combinations.
This repository owns the concrete .NET template contract: supported options, generated structure, framework choices, compatibility rules, tests, packaging, and upgrade behavior. It must turn engineering standards into executable defaults and verifiable generated output.
It does not own general software-engineering principles, pattern catalogs, or technology-neutral guidance. A rule belongs here only when it changes the generated .NET project or its automated validation.
The planned template covers:
- ASP.NET Core REST APIs using Controllers or Minimal APIs
- Internal and database-backed services
- Simple, layered, and modular-monolith structures
- HTTP and messaging integrations
- Background processing and container packaging
It does not target desktop or client UI frameworks, Razor Pages, MVC UI, games, Azure Functions, Kubernetes platform provisioning, or legacy .NET Framework applications.
dotnet-service is the template short name. It identifies the platform and workload without coupling generated projects to a business domain or API-only architecture.
The maintained template option reference defines values, defaults, compatibility rules, and validation status.
Install the local template, then generate only the capabilities the service needs:
dotnet new install ./template/content
dotnet new dotnet-service -n OrderService --api-style controllers --data-provider efcore --database-provider postgresqldotnet new dotnet-service -n LookupService --api-style minimal --data-provider none --database-provider noneDatabase-enabled projects require ConnectionStrings__ServiceDatabase. See Data and Migrations before creating a migration or changing transaction behavior.
- Install the template package with
dotnet new install. - Run
dotnet new dotnet-servicewith the capabilities required by the service. - The template validates option compatibility, evaluates computed conditions, and includes only the matching source files and configuration.
- The generated project is restored, built, tested, and maintained like a normal .NET application.
The template makes creation-time decisions. It is not a framework, runtime, deployment platform, or application host.
The output is a standalone .NET application source tree. Depending on the selected options, it can contain API endpoints, persistence, authentication, integrations, messaging contracts, background jobs, caching, observability, container files, and CI configuration.
Capabilities that are not selected are excluded rather than left as disabled scaffolding. The generated project does not reference this repository and does not require the template to build or run.
Changes intended for future applications should be implemented in template/content and delivered through the template contract:
- Add or update the implementation in the generated source tree.
- For optional behavior, define the option and compatibility rules, then conditionally include its files and package references.
- Add generation, build, and behavior tests for enabled and disabled cases.
- Update the option reference and generated-project documentation in the same change.
Existing generated applications do not receive the change automatically. Teams adopt applicable improvements through their normal application change and review process.
Yes, but installation after generation is an application change, not a template operation. A team can add the required packages, source files, configuration, and tests manually, or generate a temporary project with the desired options and selectively merge the relevant changes.
Regenerating over an existing application is not an upgrade mechanism because it can overwrite application-owned decisions. Use the migration strategy when adopting newer template capabilities.
The template repository is the upstream blueprint; the generated application is an independently owned snapshot. After generation:
- application teams own business code, configuration, migrations, deployment, and dependency updates;
- template changes affect newly generated applications only; and
- reusable improvements can flow back into the template when they are broadly applicable and preserve its option contract.
This boundary lets generated services evolve independently without coupling their build or release lifecycle to the template repository.
- Adopt and operate the template
- Template options
- Production readiness decisions
- Data and migrations
- Enterprise capabilities
- Migration strategy
- Deprecation policy
The foundation stage is complete when:
- the template can be installed and discovered through
dotnet new list; - every documented option maps to deterministic generated output;
- invalid combinations fail with actionable messages;
- supported combinations build and test successfully;
- generated projects contain only the capabilities selected by the consumer; and
- example commands are verified in automated tests.
The template release is validated independently from optional end-to-end infrastructure reference implementations:
- M6: representative messaging, reliability, jobs, and cache combinations are generation- and build-tested. Real RabbitMQ, Azure Service Bus, Kafka, outbox-delivery, and Hangfire infrastructure samples are optional extensions.
- M7: CI now builds and runs .NET 8 and .NET 10 containers, probes liveness with OpenTelemetry enabled, verifies Swagger is closed in Production, and gates CodeQL and Trivy findings.
- M8: generated-service and container smoke tests are automated; external link checks remain CI-owned.
Licensed under the MIT License. See LICENSE.