.NET Core Application Template

A reusable, production-oriented .NET application template designed to provide a secure, maintainable, and extensible baseline for building ASP.NET Core applications.

This repository provides a working application baseline with common infrastructure concerns already organized, including middleware ordering, structured logging, forwarded headers, security headers, rate limiting, centralized error handling, authentication and authorization foundations, EF Core data access patterns, GitHub Actions validation, DocFX documentation, and local dotnet new template scaffold support.

Current Release

Current release: Release 2.2.0

Tag: v2.2.0

Project Goals

The goal of this project is to provide a clean ASP.NET Core starting point that can be reused across future applications while keeping common application infrastructure consistent and easy to maintain.

The template focuses on:

• Production-oriented ASP.NET Core startup and middleware organization.
• Secure-by-default application configuration.
• Structured application and request logging.
• Centralized exception and status code handling.
• Browser and API-friendly error responses.
• Reverse proxy and forwarded header support.
• Baseline rate limiting and health checks.
• Authentication-ready and authorization-ready structure.
• EF Core data access patterns.
• Automated build, test, coverage, template smoke-test, and documentation workflows.
• Local and package-based dotnet new template scaffold support.

Who This Template Is For

This template is intended for developers and teams who want a production-oriented ASP.NET Core starting point with common infrastructure concerns already organized.

It is best suited for:

• Small-to-medium internal applications.
• Line-of-business web applications.
• Prototypes that may grow into production systems.
• Teams that want consistent startup, configuration, logging, security, error handling, and data access patterns.
• Developers who want a practical baseline without adopting a large application framework.

The template is especially useful when an application needs more structure than the default dotnet new webapp output but does not yet need a full enterprise framework.

When This Template May Not Be the Right Fit

This template may not be the best fit for:

• Very small throwaway applications.
• Static sites or applications with no server-side infrastructure needs.
• Highly specialized microservice frameworks.
• Teams that already standardize on a larger opinionated platform or internal enterprise template.
• Applications that need domain-driven layering from the first commit.

The project intentionally provides a secure and maintainable baseline. It does not try to replace every architectural style or framework.

How This Differs From dotnet new webapp

The default ASP.NET Core templates are intentionally minimal. This repository starts further along the production-readiness path by organizing concerns that many real applications eventually need:

• Centralized middleware ordering.
• Structured Serilog request and application logging.
• Forwarded header support for reverse proxy deployments.
• Security header configuration.
• Rate limiting setup.
• Centralized exception and status code handling.
• Problem Details responses.
• Authentication and authorization foundations.
• EF Core provider structure.
• CI validation, template package smoke testing, and documentation publishing.
• Repository governance files for public review and release readiness.

Application Preview

The starter application includes a simple default Razor Pages landing page that highlights the template's production-oriented infrastructure focus.

Quick Start from Source

Clone the repository:

git clone https://github.com/cdcavell/NetCoreApplicationTemplate.git
cd NetCoreApplicationTemplate

Restore dependencies:

dotnet restore

Build the solution:

dotnet build --configuration Release

Run tests:

dotnet test --configuration Release

Run the web application from source:

dotnet run --project src/ProjectTemplate.Web

Run with Docker Compose:

docker compose up --build

The Docker-hosted application is available at:

http://localhost:8080

Docker health endpoints are available at:

http://localhost:8080/health
http://localhost:8080/health/ready
http://localhost:8080/health/live

Template Scaffold Status

This repository includes a dotnet new template scaffold through .template.config/template.json and a package project at NetCoreApplicationTemplate.Template.csproj.

The scaffolded consumer output intentionally includes:

• Source projects under src/.
• Baseline tests under tests/.
• Docker support files.
• LICENSE.txt.
• ASSETS-LICENSES.md.
• A consumer-oriented README.md generated from .template.content/README.md.

The scaffolded consumer output intentionally excludes repository-maintainer content such as .github/, DocFX documentation source, ADRs, release-management files, citation metadata, contribution policy, security policy, and repository badges.

Install from NuGet

Install the published template package:

dotnet new install NetCoreApplicationTemplate::2.2.0

Pack and Install Locally

Pack the template package:

dotnet pack ./NetCoreApplicationTemplate.Template.csproj --configuration Release --output ./artifacts/template-package

Install the generated package:

dotnet new install ./artifacts/template-package/NetCoreApplicationTemplate.2.2.0.nupkg

Generate a consumer project:

dotnet new netcoreapp-template -n ContosoSecurityPortal

Build and test the generated output:

cd ContosoSecurityPortal
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release

Generate a non-default scaffold with authentication disabled and SQL Server selected as the data provider:

dotnet new netcoreapp-template `
  --name ContosoNoAuthSqlServer `
  --authProvider none `
  --dbProvider sqlserver

Generate a scaffold with authentication and EF Core data access disabled:

dotnet new netcoreapp-template `
  --name ContosoNoAuthNoDataAccess `
  --authProvider none `
  --dbProvider none

Build and test either non-default generated output, for example:

cd ContosoNoAuthSqlServer
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release

cd ContosoNoAuthNoDataAccess
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release

The non-default scaffold preserves the template's core guardrails, including structured logging, centralized error handling, health checks, security headers, rate limiting, and safe defaults.

Update the installed template by installing a newer package version:

dotnet new install NetCoreApplicationTemplate::2.2.0

Uninstall the template package:

dotnet new uninstall NetCoreApplicationTemplate

Local Repository Install

For local development, the template can also be installed from the repository root:

dotnet new install .\
dotnet new netcoreapp-template -n ContosoSecurityPortal

Package-based install remains the preferred validation path because it more closely matches consumer distribution.

Documentation

Detailed documentation is maintained in the docs folder and published with DocFX.

• Documentation source
• Published documentation
• Architecture Decision Records
• Generated API reference is available through the published documentation navigation.

Documentation areas include:

• Getting Started
• Release Readiness and Compatibility
  • v1.0 Migration Guide
  • Public Surface
  • Production Deployment Checklist
  • Runtime Readiness
  • Build Quality and Reproducibility
  • Container Release Publishing
  • Template Packaging
• Application Basics
  • Project Structure
  • Optional Application and Domain Layers
  • Configuration
  • Deployment Notes
  • Docker Development
• Middleware Pipeline
  • Middleware Pipeline
  • Error Handling
  • Security Headers
  • Forwarded Headers
  • Rate Limiting
  • Health Checks
• API Versioning
• Observability
  • Logging
  • Telemetry
• Authentication and Authorization
  • Authentication
  • Production Authentication Hardening
  • Authorization
• Data Access
• GitHub Workflow

Repository Governance

Repository-level guidance is maintained in root-level files:

• Contributing
• Security Policy
• Changelog
• Third-Party Asset Notices

Pull requests targeting main require passing CI and Code Owner review for owned paths; stale approvals are dismissed when new reviewable commits are pushed.

Repository Structure

/
├── .github/
│   ├── workflows/
│   │   └── GitHub Actions CI and documentation publishing workflows
│   ├── ISSUE_TEMPLATE/
│   │   └── Issue templates
│   ├── dependabot.yml
│   └── pull_request_template.md
│
├── .template.config/
│   └── dotnet new template metadata
│
├── .template.content/
│   └── consumer scaffold content
│
├── docs/
│   ├── adr/
│   │   └── Architecture decision records
│   ├── articles/
│   │   └── DocFX conceptual documentation
│   ├── images/
│   │   └── Documentation and README images
│   └── docfx.json
│
├── scripts/
│   └── Utility scripts for setup, build, or maintenance
│
├── src/
│   ├── ProjectTemplate.Infrastructure/
│   └── ProjectTemplate.Web/
│
├── tests/
│   └── ProjectTemplate.Web.Tests/
│
├── .dockerignore
├── .editorconfig
├── .gitattributes
├── CHANGELOG.md
├── CITATION.cff
├── CONTRIBUTING.md
├── Dockerfile
├── docker-compose.yml
├── LICENSE.txt
├── NetCoreApplicationTemplate.slnx
├── NetCoreApplicationTemplate.Template.csproj
├── PACKAGE-README.md
├── README.md
└── SECURITY.md

Local Documentation Build

Restore local tools:

dotnet tool restore

Build the DocFX site:

dotnet tool run docfx -- docs/docfx.json

Serve the generated site locally:

dotnet tool run docfx -- serve docs/_site

GitHub Actions

The repository currently includes workflows for:

• Restoring dependencies.
• Building the solution in Release configuration.
• Verifying formatting.
• Running tests.
• Generating test result and coverage artifacts.
• Enforcing a 75% minimum line coverage threshold in CI.
• Failing CI when coverage regresses below the threshold.
• Packing the template package.
• Installing the generated .nupkg into a clean SDK environment.
• Scaffolding a consumer project with dotnet new netcoreapp-template.
• Validating expected consumer files and excluded maintainer files.
• Building and testing scaffolded output on Linux, Windows, and macOS.
• Running CodeQL analysis.
• Building and publishing DocFX documentation to GitHub Pages.

Template smoke testing runs on pull requests, supported branch pushes, manual workflow dispatch, and release-style version tags matching v*.*.*.

See GitHub Workflow, Template Packaging, and ADR-0003 for details.

Versioning

This project follows Semantic Versioning using the format:

MAJOR.MINOR.PATCH

Version numbers are centrally managed through project build metadata so assemblies, future packages, and releases can share a consistent version identity.

See ADR-0003: Record Release Surface and Distribution Strategy for the release-surface decision.

Citation

If you use this repository, please cite it using the metadata in CITATION.cff or one of the following:

• Author ORCID: 0009-0002-2113-0245
• Zenodo Concept DOI: 10.5281/zenodo.20373042
• Suggested plain-text citation:

Cavell, Christopher D. NetCoreApplicationTemplate. Version 2.2.0. Zenodo. MIT License. https://doi.org/10.5281/zenodo.20373042

Roadmap

The project is a reusable .NET application template with a stable 2.2.0 package baseline. Future work may include additional provider modules, expanded examples, optional template parameters, and continued hardening of the documented release surface.

See Template Packaging for the current packaging direction.

License

This project is licensed under the MIT License.

See LICENSE.txt for full license details.

Third-party assets, libraries, templates, icons, fonts, images, or other externally sourced materials used by this project are documented in ASSETS-LICENSES.md.