dotnet command

  • 10 minutes to read

This article applies to: ✔️ .NET Core 2.1 SDK and later versions

Name

dotnet - The generic driver for the .NET Core CLI.

Synopsis

To get information about the available commands and the environment:

dotnet [--version] [--info] [--list-runtimes] [--list-sdks]

dotnet -h|--help

To run a command (requires SDK installation):

dotnet <COMMAND> [-d|--diagnostics] [-h|--help] [--verbosity <LEVEL>]
    [command-options] [arguments]

To run an application:

dotnet [--additionalprobingpath <PATH>] [--additional-deps <PATH>]
    [--fx-version <VERSION>]  [--roll-forward <SETTING>]
    <PATH_TO_APPLICATION> [arguments]

dotnet exec [--additionalprobingpath] [--additional-deps <PATH>]
    [--fx-version <VERSION>]  [--roll-forward <SETTING>]
    <PATH_TO_APPLICATION> [arguments]

--roll-forward is available since .NET Core 3.x. Use --roll-forward-on-no-candidate-fx for .NET Core 2.x.

Description

The dotnet command has two functions:

  • It provides commands for working with .NET Core projects.

    For example, dotnet build builds a project. Each command defines its own options and arguments. All commands support the --help option for printing out brief documentation about how to use the command.

  • It runs .NET Core applications.

    You specify the path to an application .dll file to run the application. To run the application means to find and execute the entry point, which in the case of console apps is the Main method. For example, dotnet myapp.dll runs the myapp application. See .NET Core application deployment to learn about deployment options.

Options

Different options are available for dotnet by itself, for running a command, and for running an application.

Options for dotnet by itself

The following options are for dotnet by itself. For example, dotnet --info. They print out information about the environment.

  • --info

    Prints out detailed information about a .NET Core installation and the machine environment, such as the current operating system, and commit SHA of the .NET Core version.

  • --version

    Prints out the version of the .NET Core SDK in use.

  • --list-runtimes

    Prints out a list of the installed .NET Core runtimes. An x86 version of the SDK lists only x86 runtimes, and an x64 version of the SDK lists only x64 runtimes.

  • --list-sdks

    Prints out a list of the installed .NET Core SDKs.

  • -h|--help

    Prints out a list of available commands.

SDK options for running a command

The following options are for dotnet with a command. For example, dotnet build --help.

  • -d|--diagnostics

    Enables diagnostic output.

  • -v|--verbosity <LEVEL>

    Sets the verbosity level of the command. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]. Not supported in every command. See specific command page to determine if this option is available.

  • -h|--help

    Prints out documentation for a given command, such as dotnet build --help.

  • command options

    Each command defines options specific to that command. See specific command page for a list of available options.

Runtime options

The following options are available when dotnet runs an application. For example, dotnet myapp.dll --roll-forward Major.

  • --additionalprobingpath <PATH>

    Path containing probing policy and assemblies to probe.

  • --additional-deps <PATH>

    Path to an additional .deps.json file. A deps.json file contains a list of dependencies, compilation dependencies, and version information used to address assembly conflicts. For more information, see Runtime Configuration Files on GitHub.

  • --depsfile <PATH_TO_DEPSFILE>

    Path to the deps.json file. A deps.json file is a configuration file that contains information about dependencies necessary to run the application. This file is generated by the .NET Core SDK.

  • --runtimeconfig

    Path to a runtimeconfig.json file. A runtimeconfig.json file is a configuration file that contains run-time settings. For more information, see .NET Core run-time configuration settings.

  • --roll-forward <SETTING> Available starting with .NET Core SDK 3.0.

    Controls how roll forward is applied to the app. The SETTING can be one of the following values. If not specified, Minor is the default.

    • LatestPatch - Roll forward to the highest patch version. This disables minor version roll forward.
    • Minor - Roll forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the LatestPatch policy is used.
    • Major - Roll forward to lowest higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the Minor policy is used.
    • LatestMinor - Roll forward to highest minor version, even if requested minor version is present. Intended for component hosting scenarios.
    • LatestMajor - Roll forward to highest major and highest minor version, even if requested major is present. Intended for component hosting scenarios.
    • Disable - Don't roll forward. Only bind to specified version. This policy isn't recommended for general use because it disables the ability to roll forward to the latest patches. This value is only recommended for testing.

    With the exception of Disable, all settings will use the highest available patch version.

    Roll forward behavior can also be configured in a project file property, a run-time configuration file property, and an environment variable. For more information, see Major-version runtime roll forward.

  • --roll-forward-on-no-candidate-fx <N> Available in .NET Core 2.x SDK.

    Defines behavior when the required shared framework is not available. N can be:

    • 0 - Disable even minor version roll forward.
    • 1 - Roll forward on minor version, but not on major version. This is the default behavior.
    • 2 - Roll forward on minor and major versions.

    For more information, see Roll forward.

    Starting with .NET Core 3.0, this option is superseded by --roll-forward, and that option should be used instead.

  • --fx-version <VERSION>

    Version of the .NET Core runtime to use to run the application.

    This option overrides the version of the first framework reference in the application's .runtimeconfig.json file. This means it only works as expected if there's just one framework reference. If the application has more than one framework reference, using this option may cause errors.

dotnet commands

General

Command Function
dotnet build Builds a .NET Core application.
dotnet build-server Interacts with servers started by a build.
dotnet clean Clean build outputs.
dotnet help Shows more detailed documentation online for the command.
dotnet migrate Migrates a valid Preview 2 project to a .NET Core SDK 1.0 project.
dotnet msbuild Provides access to the MSBuild command line.
dotnet new Initializes a C# or F# project for a given template.
dotnet pack Creates a NuGet package of your code.
dotnet publish Publishes a .NET framework-dependent or self-contained application.
dotnet restore Restores the dependencies for a given application.
dotnet run Runs the application from source.
dotnet sln Options to add, remove, and list projects in a solution file.
dotnet store Stores assemblies in the runtime package store.
dotnet test Runs tests using a test runner.

Project references

Command Function
dotnet add reference Adds a project reference.
dotnet list reference Lists project references.
dotnet remove reference Removes a project reference.

NuGet packages

Command Function
dotnet add package Adds a NuGet package.
dotnet remove package Removes a NuGet package.

NuGet commands

Command Function
dotnet nuget delete Deletes or unlists a package from the server.
dotnet nuget push Pushes a package to the server and publishes it.
dotnet nuget locals Clears or lists local NuGet resources such as http-request cache, temporary cache, or machine-wide global packages folder.
dotnet nuget add source Adds a NuGet source.
dotnet nuget disable source Disables a NuGet source.
dotnet nuget enable source Enables a NuGet source.
dotnet nuget list source Lists all configured NuGet sources.
dotnet nuget remove source Removes a NuGet source.
dotnet nuget update source Updates a NuGet source.

Global, tool-path, and local tools commands

Tools are console applications that are installed from NuGet packages and are invoked from the command prompt. You can write tools yourself or install tools written by third parties. Tools are also known as global tools, tool-path tools, and local tools. For more information, see .NET Core tools overview. Global and tool-path tools are available starting with .NET Core SDK 2.1. Local tools are available starting with .NET Core SDK 3.0.

Command Function
dotnet tool install Installs a tool on your machine.
dotnet tool list Lists all global, tool-path, or local tools currently installed on your machine.
dotnet tool uninstall Uninstalls a tool from your machine.
dotnet tool update Updates a tool that is installed on your machine.

Additional tools

Starting with .NET Core SDK 2.1.300, a number of tools that were available only on a per project basis using DotnetCliToolReference are now available as part of the .NET Core SDK. These tools are listed in the following table:

Tool Function
dev-certs Creates and manages development certificates.
ef Entity Framework Core command-line tools.
sql-cache SQL Server cache command-line tools.
user-secrets Manages development user secrets.
watch Starts a file watcher that runs a command when files change.

For more information about each tool, type dotnet <tool-name> --help.

Examples

Create a new .NET Core console application:

dotnet new console

Build a project and its dependencies in a given directory:

dotnet build

Run an application:

dotnet myapp.dll

Environment variables

  • DOTNET_ROOT, DOTNET_ROOT(x86)

    Specifies the location of the .NET Core runtimes, if they are not installed in the default location. The default location on Windows is C:\Program Files\dotnet. The default location on Linux and macOS is /usr/share/dotnet. This environment variable is used only when running apps via generated executables (apphosts). DOTNET_ROOT(x86) is used instead when running a 32-bit executable on a 64-bit OS.

  • DOTNET_PACKAGES

    The global packages folder. If not set, it defaults to ~/.nuget/packages on Unix or %userprofile%\.nuget\packages on Windows.

  • DOTNET_SERVICING

    Specifies the location of the servicing index to use by the shared host when loading the runtime.

  • DOTNET_NOLOGO

    Specifies whether .NET Core welcome and telemetry messages are displayed on first run. Set to true to mute these messages (values true, 1, or yes accepted) or set to false to allow (values false, 0, or no accepted). If not set, the default is false and the messages will be displayed on first run. This flag has no effect on telemetry (see DOTNET_CLI_TELEMETRY_OPTOUT for opting out of sending telemetry).

  • DOTNET_CLI_TELEMETRY_OPTOUT

    Specifies whether data about the .NET Core tools usage is collected and sent to Microsoft. Set to true to opt-out of the telemetry feature (values true, 1, or yes accepted). Otherwise, set to false to opt into the telemetry features (values false, 0, or no accepted). If not set, the default is false and the telemetry feature is active.

  • DOTNET_MULTILEVEL_LOOKUP

    Specifies whether .NET Core runtime, shared framework, or SDK are resolved from the global location. If not set, it defaults to 1 (logical true). Set to 0 (logical false) to not resolve from the global location and have isolated .NET Core installations. For more information about multi-level lookup, see Multi-level SharedFX Lookup.

  • DOTNET_ROLL_FORWARD Available starting with .NET Core 3.x.

    Determines roll forward behavior. For more information, see the --roll-forward option earlier in this article.

  • DOTNET_ROLL_FORWARD_TO_PRERELEASE Available starting with .NET Core 3.x.

    If set to 1 (enabled), enables rolling forward to a pre-release version from a release version. By default (0 - disabled), when a release version of .NET Core runtime is requested, roll-forward will only consider installed release versions.

    For more information, see Roll forward.

  • DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX Available in .NET Core 2.x.

    Disables minor version roll forward, if set to 0. For more information, see Roll forward.

    This setting is superseded in .NET Core 3.0 by DOTNET_ROLL_FORWARD. The new settings should be used instead.

  • DOTNET_CLI_UI_LANGUAGE

    Sets the language of the CLI UI using a locale value such as en-us. The supported values are the same as for Visual Studio. For more information, see the section on changing the installer language in the Visual Studio installation documentation. The .NET resource manager rules apply, so you don't have to pick an exact match—you can also pick descendants in the CultureInfo tree. For example, if you set it to fr-CA, the CLI will find and use the fr translations. If you set it to a language that is not supported, the CLI falls back to English.

  • DOTNET_DISABLE_GUI_ERRORS

    For GUI-enabled generated executables - disables dialog popup, which normally shows for certain classes of errors. It only writes to stderr and exits in those cases.

  • DOTNET_ADDITIONAL_DEPS

    Equivalent to CLI option --additional-deps.

  • DOTNET_RUNTIME_ID

    Overrides the detected RID.

  • DOTNET_SHARED_STORE

    Location of the "shared store" which assembly resolution falls back to in some cases.

  • DOTNET_STARTUP_HOOKS

    List of assemblies to load and execute startup hooks from.

  • DOTNET_BUNDLE_EXTRACT_BASE_DIR Available starting with .NET Core 3.x.

    Specifies a directory to which a single-file application is extracted before it is executed.

    For more information, see Single-file executables.

  • COREHOST_TRACE, COREHOST_TRACEFILE, COREHOST_TRACE_VERBOSITY

    Controls diagnostics tracing from the hosting components, such as dotnet.exe, hostfxr, and hostpolicy.

    • COREHOST_TRACE=[0/1] - default is 0 - tracing disabled. If set to 1, diagnostics tracing is enabled.
    • COREHOST_TRACEFILE=<file path> - only has effect if tracing is enabled via COREHOST_TRACE=1. When set, the tracing information is written to the specified file, otherwise the tracing information is written to stderr. Available starting with .NET Core 3.x.
    • COREHOST_TRACE_VERBOSITY=[1/2/3/4] - default is 4. The setting is used only when tracing is enabled via COREHOST_TRACE=1. Available starting with .NET Core 3.x.
      • 4 - all tracing information is written
      • 3 - only informational, warning and error messages are written
      • 2 - only warning and error messages are written
      • 1 - only error messages are written

    The typical way to get detailed trace information about application startup is to set COREHOST_TRACE=1 and COREHOST_TRACEFILE=host_trace.txt and then run the application. A new file host_trace.txt will be created in the current directory with the detailed information.

See also