dotnet new and Templates

This section documents MSBuild 18.9, the .NET SDK 10.0.402 (with its dotnet CLI) and NuGet 7.9, as published in the MSBuild, .NET and NuGet documentation on learn.microsoft.com, which is the reference these pages are written and verified against. Material about .NET 11 / NuGet 8.0 is still in preview and is always flagged as such — never presented as baseline.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The C# Reference bibliography lists the reference material consulted while preparing these pages.

dotnet new creates projects, items and repository files from templates. The SDK preinstalls the common ones; others come as NuGet template packages installed per user. This page uses .NET SDK 10.0.402 and the Ledgerline template package (Ledgerline.Templates) from the repository’s local feed. Writing templates is covered on Authoring Templates, and packing them on Tool and Template Packages.

The sub-commands

Command Purpose

dotnet new <short-name> [options]

Instantiate a template.

dotnet new list [filter]

Installed templates (--tag, --language, --type filter them).

dotnet new search <text>

Templates on nuget.org (--package, --author, --tag).

dotnet new details <package>

A template package’s metadata and templates.

dotnet new install <package[@version]> | <path>

Install a template package or a folder (--add-source, --force).

dotnet new uninstall [package]

Uninstall; with no argument, list what is installed and how to remove it.

dotnet new update [--check-only]

Update installed template packages.

Source: dotnet new install, dotnet new list, dotnet new search, dotnet new details, dotnet new uninstall, dotnet new update.

The preinstalled templates

dotnet new list on a clean SDK 10.0.402 (abridged to the non-web templates):

Template Name                                 Short Name                    Language    Tags
--------------------------------------------  ----------------------------  ----------  ----------------------------------
Class Library                                 classlib                      [C#],F#,VB  Common/Library
Console App                                   console                       [C#],F#,VB  Common/Console
dotnet gitattributes file                     gitattributes,.gitattributes              Config
dotnet gitignore file                         gitignore,.gitignore                      Config
Dotnet local tool manifest file               tool-manifest                             Config
EditorConfig file                             editorconfig,.editorconfig                Config
global.json file                              globaljson,global.json                    Config
MCP Server App                                mcpserver                     [C#]        Common/AI/MCP
MSBuild Directory.Build.props file            buildprops                                MSBuild/props
MSBuild Directory.Build.targets file          buildtargets                              MSBuild/props
MSBuild Directory.Packages.props file         packagesprops                             MSBuild/packages/props/CPM
MSTest Test Project                           mstest                        [C#],F#,VB  Test/MSTest/Desktop/Web
NuGet Config                                  nugetconfig,nuget.config                  Config
NUnit Test Project                            nunit                         [C#],F#,VB  Test/NUnit/Desktop/Web
Solution File                                 sln,solution                              Solution
Solution Filter File                          slnf,solutionfilter                       Solution
Worker Service                                worker                        [C#],F#     Common/Worker/Web
WPF Application                               wpf                           [C#],VB     Common/WPF
xUnit Test Project                            xunit                         [C#],F#,VB  Test/xUnit/Desktop/Web

The bracketed language is the default (-lang F# picks another). The full list also has the ASP.NET Core, Blazor, Razor, gRPC and Windows Forms templates. The xunit template is xUnit v2; xUnit v3 templates come from the xunit.v3.templates package (below).

Templates discontinued since the .NET 8 SDK — angular, react, blazorserver, blazorserver-empty and blazorwasm-empty — are no longer preinstalled; the blazor template replaces the Blazor ones.

Source: .NET default templates: Preinstalled templates, Discontinued templates.

Repository files from templates

Eight templates create the files a new repository needs. In an empty folder:

dotnet new globaljson --sdk-version 10.0.402 --roll-forward latestPatch
dotnet new buildprops
dotnet new packagesprops
dotnet new nugetconfig
dotnet new editorconfig
dotnet new gitignore
dotnet new tool-manifest
dotnet new sln -n Books
ls -la
-rw-r--r--  1 root root 18250 Oct 23 19:02 .editorconfig
-rw-r--r--  1 root root  8014 Oct 23 19:02 .gitignore
-rw-r--r--  1 root root    23 Oct 23 19:02 Books.slnx
-rw-r--r--  1 root root   158 Oct 23 19:02 Directory.Build.props
-rw-r--r--  1 root root   293 Oct 23 19:02 Directory.Packages.props
-rw-r--r--  1 root root    51 Oct 23 19:02 dotnet-tools.json
-rw-r--r--  1 root root    79 Oct 23 19:02 global.json
-rw-------  1 root root   280 Oct 23 19:02 nuget.config

What each produced:

  • global.json — {"sdk": {"rollForward": "latestPatch", "version": "10.0.402"}} (Installing and Selecting SDKs).

  • Directory.Build.props — an empty PropertyGroup and a link to the customisation docs (Repository-Wide Configuration).

  • Directory.Packages.props — <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> (Central Package Management).

  • nuget.config — <clear /> plus nuget.org, so machine-wide sources stop applying. It was created with mode 0600, readable only by its owner — because NuGet configuration files can hold credentials.

  • .editorconfig — the .NET defaults for every IDE0xxx/CA style option (18 KB); --empty writes an empty file.

  • dotnet-tools.json — an empty local tool manifest, at the folder root (.NET Tools).

  • Books.slnx — the XML solution format, the default since .NET 10; --format sln gives the classic format (Solutions and .slnx).

Source: .NET default templates: globaljson, buildprops.

Template options, dry runs and implicit restore

Common options for every template are -n/--name (also the output folder), -o/--output, --dry-run, --force and --no-update-check; each template adds its own (dotnet new console -h lists them, under "Template options").

Templates that create projects normally restore right after creating them, through a post-action:

dotnet new console -n Books.Probe
dotnet new classlib -n Books.Core --no-restore
The template "Console App" was created successfully.

Processing post-creation actions...
Restoring ~/newrepo/Books.Probe/Books.Probe.csproj:
  Determining projects to restore...
  Restored ~/newrepo/Books.Probe/Books.Probe.csproj (in 108 ms).
Restore succeeded.


The template "Class Library" was created successfully.

Books.Probe/obj/project.assets.json exists after the first command; Books.Core has no obj folder. Skip the implicit restore when the project will be restored with the rest of a solution anyway, or when its packages come from a feed that needs credentials the template run does not have.

Source: dotnet new: Implicit restore, Template options.

Installing a template package

From nuget.org, search and details show what a package contains before installing it:

dotnet new search --package xunit.v3.templates
dotnet new details xunit.v3.templates
Template Name                   Short Name        Language    Package Name / Owners       Trusted  Downloads
------------------------------  ----------------  ----------  --------------------------  -------  ---------
xUnit.net v3 Extension Project  xunit3-extension  [C#],F#,VB  xunit.v3.templates / xunit     ✓        36k
xUnit.net v3 Test Project       xunit3            [C#],F#,VB  xunit.v3.templates / xunit     ✓        36k

xunit.v3.templates
   Package version: 4.0.2
   Reserved: True
   Details: Includes templates for use with 'dotnet new' for creating xUnit.net v3 unit test projects and extension projects.
   Source Feed: nuget.org [https://api.nuget.org/v3/index.json]

"Reserved" / "Trusted" means the package ID prefix is reserved on nuget.org by a verified owner (nuget.org Accounts, Organizations and API Keys).

Ledgerline's template package is installed from its local feed, by absolute path:

dotnet new install Ledgerline.Templates@1.0.0 --add-source ~/ledgerline/artifacts/feed
dotnet new ledgerline-app -n Books.Cli --Framework net8.0 --dry-run
dotnet new ledgerline-app -n Books.Cli --Framework net8.0
The following template packages will be installed:
   Ledgerline.Templates@1.0.0

Success: Ledgerline.Templates@1.0.0 installed the following templates:
Template Name           Short Name      Language  Tags
----------------------  --------------  --------  ------------------
Ledgerline console app  ledgerline-app  [C#]      Console/Accounting

File actions would have been taken:
  Create: ./Books.Cli.csproj
  Create: ./Program.cs

Failed to check update for Ledgerline.Templates@1.0.0: the package is not available in configured NuGet feeds.

The template "Ledgerline console app" was created successfully.

Three details from the run:

  • @ separates package and version. The older :: form still works but prints "The colon separator "::" has been deprecated in favor of the at symbol "@"".

  • A relative --add-source was rejected. --add-source ./artifacts/feed printed "Warning: Failed to load NuGet source ./artifacts/feed: the source is not valid", and the install only succeeded because the folder’s nuget.config also lists that feed. Pass an absolute path.

  • Update checks. Each instantiation checks for a newer template package and warns when the package’s feed is not configured; --no-update-check turns it off.

dotnet new uninstall without arguments shows each installed package with its source and the exact uninstall command:

Currently installed items:
   Ledgerline.Templates
      Version: 1.0.0
      Details:
         Author: Ledgerline contributors
         Reserved: ✘
         NuGetSource: ~/ledgerline/artifacts/feed
      Templates:
         Ledgerline console app (ledgerline-app) C#
      Uninstall Command:
         dotnet new uninstall Ledgerline.Templates

Template packages are installed per user (under ~/.templateengine), not per repository. A team that depends on a template should document the install command, or use a local tool when the template is only a code generator.

Source: dotnet new install, dotnet new search.

Common mistakes

  • Relying on a template’s implicit restore in CI — restore the solution explicitly.

  • A relative --add-source — rejected; use an absolute path.

  • Expecting dotnet new sln to create .sln — it creates .slnx on SDK 10.

  • Using xunit for new xUnit v3 projects — that template is v2; install xunit.v3.templates.

  • Committing a generated nuget.config without reviewing it — its <clear /> removes every machine-wide source.

References