dotnet new

dotnet new <template> [-n|--name <name>] [-o|--output <dir>] [-f|--framework <tfm>] [--dry-run] [--force] [template options]

dotnet new instantiates a template: a folder of files plus a .template.config/template.json that says which tokens to replace and which options exist. The SDK ships the common templates; others come from NuGet template packages installed with dotnet new install. Nothing is compiled or restored; it only writes files.

Names, folders and frameworks

-n Orders.Api sets the project file name and root namespace. For project templates (those with preferNameDirectory, such as webapi, classlib and console) -n without -o also creates a folder of that name; item templates such as sln and gitignore write into the current folder, so dotnet new sln -n Shop creates Shop.slnx right there. -o src/Orders.Api alone takes the name from the folder. Use -o in scripts so the folder layout is explicit. -f defaults to the SDK's own framework, so an SDK picked up from a newer machine can create net11.0 projects in a net10.0 solution; pin the SDK with global.json or pass -f net10.0.

Templates a back-end team uses

Short name	Creates	Options worth knowing
webapi	Minimal API with built-in OpenAPI and an .http file	--use-controllers, --auth, --no-https, --no-openapi
webapiaot	Native AOT minimal API with source-generated JSON	Slim builder, no MVC
web	Empty ASP.NET Core app	Smallest starting point
worker	Generic host with a BackgroundService	No Kestrel
sln	Solution file	.slnx on the .NET 10 SDK; --format sln for the old format
gitignore, editorconfig, globaljson, buildprops, tool-manifest	Repository files	globaljson --sdk-version 10.0.402

dotnet new <template> --help lists that template's options, dotnet new list shows what is installed and dotnet new search queries NuGet.org.

Team templates

A company template is a normal project plus template.json. sourceName is the string that is replaced by -n everywhere: file names, namespaces and project references. symbols declare options such as --database, and conditional comments in files (//#if (database == "postgres")) keep or drop code. Pack it with PackageType=Template, publish it to the internal feed and install it with dotnet new install Contoso.Templates::2.3.0. Pin the version so every new service starts from the same baseline.

Failure modes

• Running dotnet new webapi in the repository root scatters Program.cs and appsettings.json next to the solution. Always pass -o.
• Re-running a template over an existing project fails; --force overwrites your edited files without a merge. Use --dry-run first.
• Templates are a snapshot. Fixes in a newer template never reach services created earlier, so shared settings belong in Directory.Build.props, not only in the template.
• Older build agents and tools that do not read .slnx fail on a new solution; keep them on a current SDK rather than creating .sln files forever.

# A new Orders service in an existing repository, every choice explicit.
cd ~/src/shop

# Pin the SDK first so -f defaults to net10.0 for everyone.
dotnet new globaljson --sdk-version 10.0.402 --roll-forward latestFeature

dotnet new sln -n Shop                              # Shop.slnx on the .NET 10 SDK
dotnet new webapi -o src/Orders.Api --dry-run       # see what would be written
dotnet new webapi -o src/Orders.Api                 # minimal API + OpenAPI + Orders.Api.http
dotnet new classlib -o src/Orders.Domain
dotnet new worker -o src/Orders.Worker              # queue consumer, no HTTP

dotnet new buildprops                               # Directory.Build.props at the root
dotnet new tool-manifest                            # .config/dotnet-tools.json

dotnet sln add src/Orders.Api src/Orders.Domain src/Orders.Worker

# What else is available, and the options of one template
dotnet new list
dotnet new webapi --help

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Platform Team",
  "classifications": ["Web", "API"],
  "identity": "Contoso.Templates.OrdersService",
  "name": "Contoso HTTP service",
  "shortName": "contoso-api",
  "sourceName": "Contoso.Service",
  "preferNameDirectory": true,
  "tags": { "language": "C#", "type": "project" },
  "symbols": {
    "database": {
      "type": "parameter",
      "datatype": "choice",
      "choices": [
        { "choice": "postgres", "description": "Npgsql + EF Core" },
        { "choice": "none", "description": "No database" }
      ],
      "defaultValue": "postgres"
    }
  }
}

var builder = WebApplication.CreateBuilder(args);

// Built-in OpenAPI document (Microsoft.AspNetCore.OpenApi), served at /openapi/v1.json.
builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.MapGet("/orders/{id:int}", (int id) =>
        TypedResults.Ok(new OrderSummary(id, "ORD-" + id.ToString("D6"), 129.90m)))
    .WithName("GetOrder");

app.Run();

public sealed record OrderSummary(int Id, string Number, decimal Total);

# The template pack project has <PackageType>Template</PackageType>
# and includes the template folders as content.
dotnet pack templates/Contoso.Templates.csproj -c Release -o artifacts

# Try it locally from the folder before publishing it.
dotnet new install ./templates/content/OrdersService
dotnet new contoso-api -n Orders.Api -o src/Orders.Api --database postgres

# Everyone else installs a pinned version from the internal feed.
dotnet new install Contoso.Templates::2.3.0
dotnet new uninstall Contoso.Templates