C# Reference ยท .NET, Tools and Concepts
The dotnet CLI
Reference for the dotnet command-line tool: create, restore, build, run, test and publish projects, add packages, run single-file programs and pass arguments.
The dotnet command is the front door to everything in the .NET SDK. It creates projects from templates, downloads NuGet packages, compiles, runs tests, formats code and produces the files you deploy. The same commands work in a terminal on Windows, macOS and Linux, and every IDE (Visual Studio, Rider, VS Code) calls them under the hood.
A typical session from an empty folder looks like this:
dotnet new console -o Hello cd Hello dotnet run
The runner on this site has no dotnet command and no shell for C#, so the command lines below are read-only. The runnable examples show how a program receives what you type after -- and how it can ask which runtime it runs on.
Try it
dotnet run -- one two passes one and two to your program. In top-level statements they arrive as the predefined array args. In the editor there are none, so this example supplies its own list to show the usual parsing pattern.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
The general form is dotnet [command] [arguments] [options]. Arguments for your own program go after a lone --.
dotnet new console -n Tool # create a project from a template dotnet add package Humanizer # add a NuGet package reference dotnet restore # download packages dotnet build -c Release # compile dotnet run -- --name Ada # build if needed, then run dotnet test # run unit tests dotnet publish -c Release -o out # produce files to deploy
Common commands
| Command | Description |
|---|---|
dotnet new <template> |
Creates a project or file. dotnet new list shows templates such as console, classlib, web, webapi, worker, xunit, sln, gitignore, editorconfig. |
dotnet restore |
Downloads the packages listed in the project. Run automatically by build and run. |
dotnet build |
Compiles the project and its references. Default configuration is Debug; use -c Release for optimized output. |
dotnet run |
Builds and starts the project. --project <path> chooses a project; -- <args> passes arguments to the program. |
dotnet test |
Builds the test project and runs its tests through the test host. |
dotnet publish |
Creates a folder with everything needed to run. Options include -r <runtime-id>, --self-contained, -p:PublishSingleFile=true, -p:PublishAot=true. |
dotnet add package / remove package |
Edits PackageReference items. |
dotnet add reference |
Adds a ProjectReference. |
dotnet list package |
Lists packages; --outdated, --vulnerable and --include-transitive are the useful switches. |
dotnet format |
Applies code style and analyzer fixes from your .editorconfig. |
dotnet watch |
Re-runs or hot-reloads the app when files change. |
dotnet tool install |
Installs a .NET tool (-g for global, or a local manifest with dotnet new tool-manifest). |
dotnet --info, --list-sdks, --list-runtimes |
Show what is installed. |
Single-file programs
Since .NET 10 you can run one .cs file without a project:
dotnet run hello.cs
Special #: lines at the top of the file replace the project file, for example #:package [email protected] or #:property LangVersion=preview. This is exactly the shape of a program in this site's editors, except that we cannot download packages.
Exit codes: dotnet returns the exit code of the command. A build with errors returns non-zero, and a program that returns a number from Main (or from top-level statements) passes that number on.
Usage notes
buildandrunrestore first. You rarely calldotnet restoreby hand, except in a build pipeline that wants a separate, cacheable step.- Debug versus Release.
Debugkeeps extra information and skips optimization.Releaseturns optimizations on and removesDebug.Assertcalls. Always measure and deployRelease. - The
--separator. Everything before it is fordotnet, everything after is for your program. Without it,dotnet run --helpshows the help ofdotnet run, not of your app. - Several SDKs can be installed side by side. A
global.jsonfile in a folder pins the SDK version used there, which keeps a team on the same compiler. - Framework-dependent versus self-contained. The default publish needs the runtime installed on the target machine and is small.
--self-containedbundles the runtime, which is larger but needs nothing installed. Native AOT goes further and compiles to a native executable (Native AOT and trimming). - Runtime identifiers.
-r win-x64,linux-x64,linux-arm64,osx-arm64select the target operating system and processor for self-contained publishing. - Environment variables.
DOTNET_ENVIRONMENTandASPNETCORE_ENVIRONMENTchooseDevelopmentorProductionfor hosts.DOTNET_CLI_TELEMETRY_OPTOUT=1switches off usage telemetry. - Tools are programs too.
dotnet-ef,dotnet-formatanddotnet-outdatedare installed as .NET tools and called asdotnet ef,dotnet outdated.