ASP.NET Core Templates: A Complete Guide to Project Scaffolding and Startup

When you start a new web project in .NET, asp net core templates are the first tool you reach for. These scaffolding blueprints generate a fully wired-up project skeleton — middleware, dependency injection, routing, and configuration all pre-configured — so you spend the first hour writing business logic rather than boilerplate. Whether you are building a REST API, a Razor Pages site, a Blazor app, or a gRPC service, there is an official template that gets you past the blank-screen problem in under sixty seconds.

Templates in ASP.NET Core are distributed through the .NET template engine, a cross-platform CLI tool that ships with every .NET SDK installation. Running dotnet new list in any terminal reveals dozens of available templates, each identified by a short name like webapi, mvc, or blazorserver. Microsoft curates a rich set of official templates, and the broader community contributes thousands more through NuGet, giving teams the flexibility to encode their own conventions into reusable starting points.

Understanding the anatomy of a template helps you choose the right one and avoid fighting the framework later. Each template bundles a specific combination of NuGet packages, middleware registrations, folder structures, and configuration files. The webapi template, for example, configures JSON serialization, disables Razor views, and adds OpenAPI (Swagger) support by default in .NET 6 and later. The mvc template wires up view engines, tag helpers, and antiforgery tokens. Choosing the wrong template means spending time stripping out features you do not need or manually wiring ones you do.

Template versioning is closely tied to the .NET SDK version installed on your machine. When Microsoft releases .NET 8, the bundled templates reflect the new minimal hosting model, nullable reference types, and implicit usings patterns introduced in that cycle. If your team targets .NET 6 LTS but your SDK is .NET 8, you need to pass the -f net6.0 flag or install the SDK version that ships with the target framework templates. Mismatched versions are one of the most common sources of confusion for developers new to the ecosystem.

Custom organization templates are where the real productivity gains hide. Enterprise teams often encode standards — logging configuration, health-check endpoints, OpenTelemetry setup, authentication middleware — into a single internal template distributed via an internal NuGet feed. New developers joining the team run one dotnet new command and receive a production-ready skeleton that already passes the first CI pipeline check. This approach reduces onboarding time, eliminates configuration drift between microservices, and ensures that every project starts with the same security posture.

The template engine also supports template parameters, which let you toggle features at creation time. The official webapi template accepts flags like --auth Individual to scaffold ASP.NET Core Identity, or --use-program-main to generate a traditional Main method instead of top-level statements. These parameters make a single template behave like a family of related templates, dramatically reducing the number of templates you need to maintain. Understanding which parameters exist — and what they generate — is a core skill for any developer working seriously with ASP.NET Core.

This guide walks through every major built-in template, explains how to install third-party and custom templates, covers template parameters in depth, and shows you how to author and distribute your own organizational template. By the end you will have a clear mental model of the template system and the practical skills to streamline project creation across your entire team.

Template parameters are arguably the most underused feature of the .NET template engine. When you run dotnet new webapi --help, the CLI prints a full list of flags that control what gets generated. The --auth flag is the most impactful: passing --auth Individual scaffolds a complete ASP.NET Core Identity setup with SQLite by default, including user registration, login, password hashing, and EF Core migrations. Passing --auth IndividualB2C instead wires up Azure AD B2C authentication. These options would take hours to configure manually and are generated correctly in seconds.

The --no-https flag is another common parameter, useful in containerized environments where TLS termination happens at the ingress layer rather than in the application itself. Removing HTTPS from the generated project eliminates the developer certificate dependency and the HTTP-to-HTTPS redirect middleware, which can cause unexpected behavior inside Docker networks where requests arrive on HTTP internally. Teams running Kubernetes with an NGINX or Traefik ingress almost always use this flag for internal services.

Framework targeting is controlled by the -f or --framework parameter. When you have both .NET 6 and .NET 8 SDKs installed, dotnet new webapi -f net6.0 generates a project with a <TargetFramework>net6.0</TargetFramework> entry in the .csproj and uses the implicit usings and nullable reference type settings from .NET 6. This is critical for teams maintaining long-term support services on an older runtime while developing new features on the latest SDK.

Top-level statements versus the traditional Program class with a Main method is controlled by --use-program-main. Top-level statements, introduced in C# 9 and the default since .NET 6 templates, reduce boilerplate to a minimum. However, some teams — especially those with large codebases and junior developers — prefer the explicit Main entry point because it is more familiar and easier to attach a debugger to programmatically. Passing this flag does not affect runtime behavior; it is purely a code style preference.

The --language parameter lets you scaffold in F# or Visual Basic instead of C#. The dotnet new webapi --language F# command generates an idiomatic F# project with a Program.fs file and functional-style route handlers. F# templates are less common in enterprise settings but are popular in data processing and financial services domains where the type system's discriminated unions and computation expressions provide strong correctness guarantees.

Output path and project name parameters — -o and -n respectively — control where the project is created and what namespace is used throughout the generated files. Running dotnet new webapi -n MyCompany.Orders.Api -o ./src/Orders generates a project in ./src/Orders with namespaces like MyCompany.Orders.Api.Controllers already filled in. This eliminates the tedious find-and-replace step that developers often perform after accepting a generic WebApplication1 default name.

Dry-run mode (--dry-run) previews exactly which files would be created without writing anything to disk. This is especially useful when evaluating an unfamiliar template for the first time. You can see the full file list, the parameter defaults that would be applied, and the output directory structure before committing. Combining dry-run with --verbosity diagnostic dumps the complete template metadata, letting you inspect every available parameter even if the documentation is sparse.

Creating a custom ASP.NET Core template begins with building a normal project that represents the ideal starting point for your team. Configure everything you want every project to have — Serilog structured logging with a console and file sink, OpenTelemetry tracing with an OTLP exporter, a health-check endpoint at /healthz, global exception handling middleware, and your organization's standard NuGet package references. This project is your template source, and everything in it will be copied into each new project your team generates.

The key file that transforms a regular project into a template is .template.config/template.json. This JSON file tells the template engine the template's short name (used in dotnet new <shortName>), its human-readable name, a default project name, and the template's author and tags. The sourceName field specifies a placeholder string — typically something like MyCompany.Template — that the engine replaces with the -n argument value in every file name and file content. This is how namespaces, assembly names, and class names get customized at generation time.

Template parameters are defined in the symbols section of template.json. Each symbol has a type (parameter, computed, or derived), a data type (bool, string, choice), a default value, and a description. Boolean parameters are the most common: you might define an IncludeHealthChecks parameter that defaults to true, then wrap the health-check registration code in a conditional block using the template engine's #if / #endif preprocessor syntax. When a developer passes --IncludeHealthChecks false, the health-check code is simply excluded from the generated output.

File exclusion is handled via the sources and modifiers sections of template.json. You can specify that certain files are only included when a particular parameter is true, or that certain directories are always excluded (like a bin or obj folder). This is especially useful for templates that include optional integrations like Entity Framework Core — the Data folder with your DbContext and migration configuration only appears in the generated project when the developer opts into database support at scaffold time.

Distributing your custom template is straightforward. Package it as a NuGet package (the package must contain the .template.config directory at the root) and push it to your internal feed — Azure Artifacts, GitHub Packages, and JFrog Artifactory all work. Developers install the template with dotnet new install MyCompany.Templates, pointing the NuGet client at your internal feed. Updates to the template package are picked up by running the same install command with the new version number. Teams on a strict governance model can pin template versions in their developer environment setup scripts to ensure consistency across a large engineering organization.

Testing your template before distribution is important and often overlooked. The simplest test strategy is to run dotnet new install . from the template source directory, which installs the template from the local filesystem. Then generate a few projects with different parameter combinations and run dotnet build and dotnet test on each.

Automating these tests in a CI pipeline for the template repository itself — treating the template as a product with its own release pipeline — is a mark of a mature engineering organization and prevents broken templates from reaching developers at the worst possible moment, which is always the beginning of a new project.

Template inheritance and composition are emerging patterns in the ecosystem. Tools like Nuke and Cake build systems sometimes ship their own templates that build on top of the standard ASP.NET Core templates, adding build automation scripts and deployment targets. The template engine does not natively support inheritance, but you can achieve composition by defining multiple templates in a single NuGet package — one for the API project, one for a test project, and one solution-level template that generates both and wires them into a .sln file with a single command.

Integrating ASP.NET Core templates into team CI/CD workflows transforms them from a convenience into a governance mechanism. When every service starts from the same internal template, your CI pipeline can make strong assumptions: the health-check endpoint exists at a known path, structured logs arrive in a known format, and OpenTelemetry spans use consistent attribute names. This predictability reduces the per-service configuration burden on the platform engineering team and lets them build reusable pipeline components that work across all services without custom exceptions.

A practical CI integration pattern is to add a template validation step to the template repository's own pipeline. On every pull request that modifies the template source, a workflow generates a sample project from the updated template, runs dotnet build, executes the generated unit tests, and runs a static analysis pass with dotnet format --verify-no-changes. If any of these steps fail, the PR is blocked. This ensures that the template source is always in a releasable state and that generated projects compile and pass tests out of the box.

Solution-level templates (dotnet new sln plus project templates in a single invocation) are particularly valuable for microservice architectures where each service follows a multi-project layout: an API project, a domain library, an infrastructure library, and a test project.

Nesting these into a solution template means a developer runs one command and receives a four-project solution with all project references already configured, a shared Directory.Build.props file enforcing consistent SDK settings, and a .editorconfig file with your team's style rules. The alternative — manually running four dotnet new commands and three dotnet sln add commands — takes significantly longer and introduces opportunities for inconsistency.

Template parameters can drive not just code generation but also infrastructure configuration. A common pattern is to include a docker-compose.yml and Dockerfile in the template, with the service name and port number derived from the template's -n argument via the sourceName substitution. When a developer generates a service named MyCompany.Orders.Api, the Dockerfile's ENTRYPOINT already references the correct assembly name and the docker-compose.yml already maps the correct internal port. This eliminates the container configuration step that otherwise requires developers to manually edit generated files.

The relationship between templates and the broader developer experience platform is evolving rapidly. Microsoft's Dev Containers specification and the devcontainer.json configuration file can be included in a template, ensuring that every generated project has a fully configured VS Code or Codespace environment with the correct .NET SDK version, recommended extensions, and port forwarding rules.

Developers who open the generated project in a Dev Container get a ready-to-run environment in under two minutes, regardless of what is installed on their local machine. This pattern is especially powerful for onboarding new team members or for contractors who need to contribute without the overhead of a full local environment setup.

Monitoring and observability standards embedded in templates pay dividends across the entire service lifecycle. When your template includes OpenTelemetry with pre-configured resource attributes (service.name, service.version, deployment.environment), every service your team generates automatically participates in your distributed tracing infrastructure. The platform team can build Grafana dashboards and alerting rules that work uniformly across all services because the span and metric attribute names are consistent. This is a force multiplier: the template investment compounds in value with each new service that inherits the standard observability configuration.

For teams working with asp net core templates at scale, maintaining a template changelog is as important as maintaining the template itself. When you update the template to upgrade a NuGet package, change a default configuration value, or add a new middleware, document the change with a clear migration note for existing projects.

Developers who generated services six months ago need to know whether they should manually apply the update to their running service. A simple CHANGELOG.md in the template repository, combined with a version bump in the NuGet package, gives teams the information they need to make informed update decisions without guessing what changed.

Getting the most out of ASP.NET Core templates in daily development starts with building a personal reference for the flags and parameter combinations you use most often. Keep a team wiki page or a shell alias file that documents your organization's standard dotnet new invocations — the exact command with all flags that generates the canonical starting point for each project type. Developers who internalize these commands stop reaching for GUI wizards and create consistent projects from muscle memory. The ten minutes spent documenting the command pays back on every future project creation.

Explore the dotnet new install ecosystem before building a custom template. The FastEndpoints project ships a template that scaffolds a Vertical Slice Architecture API. The Clean Architecture template from Jason Taylor generates a solution with Domain, Application, Infrastructure, and Web layers fully separated. ABP Framework provides enterprise templates with multi-tenancy, auditing, and modular architecture baked in. Evaluating these templates — even if you ultimately build your own — teaches you patterns for template authoring and exposes architectural ideas you can incorporate into your organization's standard.

Keep your template source in version control alongside the rest of your platform code, not as a one-off artifact. Treat template pull requests with the same rigor as application code: require code review, run automated generation tests, and tag releases semantically. A 1.0.0 template tag should mean developers can reliably install version 1.0.0 of your template and get a project that passes CI. A 1.1.0 tag adds new features without breaking existing generated projects. A 2.0.0 tag signals a breaking change — perhaps a shift from .NET 6 to .NET 8 patterns — that requires a migration guide.

Use dotnet new --update-check and dotnet new --update-apply to keep installed templates current. These commands query the NuGet source for newer versions of all installed template packages and optionally apply updates. In a team environment where templates are distributed via an internal feed, these commands let developers stay synchronized with the platform team's latest standards without needing to remember which version they have installed or check a dashboard. Consider adding dotnet new --update-apply to your team's developer environment setup script so it runs automatically when a developer opens their laptop.

When you encounter a generated file that does not quite match your needs, resist the urge to immediately modify the output. Instead, ask whether the mismatch reflects a missing template parameter, a missing template variant, or a genuine per-project customization. If the same manual change appears in five generated projects, it belongs in the template. If it appears in every project of a certain type, it belongs in a template parameter with a sensible default. Keeping generated code close to the template output reduces drift and makes future template upgrades easier to apply to existing projects.

Testing the generated project immediately after scaffolding — before writing a single line of business logic — is a discipline that saves significant debugging time. Run dotnet build, then dotnet run and verify the application starts without errors. For API projects, open the Swagger UI and confirm the documentation renders. For Blazor projects, navigate to the home route and verify the component renders in the browser. This smoke test takes under two minutes and catches SDK mismatches, missing NuGet restore issues, and port conflicts before they become entangled with your actual application code.

Finally, treat the ASP.NET Core template system as a living standard rather than a one-time configuration. Revisit your organizational templates at each major .NET release — .NET 9, .NET 10 — and evaluate whether new SDK features like enhanced AOT compilation support, new Kestrel configuration options, or updated OpenAPI generation patterns should be incorporated. The teams that maintain disciplined template practices consistently ship new services faster and with fewer early-stage configuration bugs than teams that treat project creation as an afterthought. Templates are technical infrastructure, and investing in them returns value with every project your organization starts.