Introduction
CLI (Command Line Interface) is new cross-platform tool for developing .NET Core applications. It is also referred to as a foundational tool because it is a primary layer on which other tools like IDE (Integrated Development Environments) build the application and run it.
CLI tools are available in DEB packages for Ubuntu and MSI bundles for Windows. This installer will install the tool and setup the environment required to run CLI tool. There is a possibility of multiple versions of CLI tools installed on a single machine.
All CLI commands are run from command prompt. The CLI command mainly contains three parts -
- The driver
- Command
- Command Argument
Driver
The verb "dotnet" is used as driver. The following two are the primary responsibilities for the driver.
- Executing IL (Intermediate Language) code
- Executing the Command
The driver is responsible to find out the version of the tool that we want to use. We can specify the version of the tool in "sdkVersion" property of "global.json" file. If the specified version of CLI tool is not available, driver uses the latest version of the tools that are available. The driver will start to execute the command once the tool version is found.
Command
The command is the action which needs to be performed by the driver. For example, "dotnet new" will create new project for us.
Arguments
The arguments are passed with the command. The arguments are the helping hand of the command and they provide required user input to the command. For example, "dotnet run --project /myprojects/project.json" runs project under specified folder.
Built-in supported Commands
Following commands are installed with default installation.
- new
- restore
- run
- build
- test
- publish
- pack
CLI tool provides the way to import more commands on the basis of need in project. We can add our own command as well.
“dotnet” command
The dotnet is a generic driver for the CLI tool and it is used to run the command-line commands. The dotnet is itself used as command; and with this command, it has the following options.
Options |
Description |
--version |
Display the current version of the CLI tool |
-v or --verbose |
Enables verbose output |
--info |
Display more details about the CLI tool like name and version of the OS, SHA-1 information etc. |
--help or-h |
Display short help and list down current supported command |
Example
I have run the following commands in command window
>dotnet --version
>dotnet --info
>dotnet –v
>dotnet --help
Outputs
"dotnet new" command
It is used for creating new .NET core project. It provides convenient way to initialize a valid .NET Core project and sample source code. When we run this command, two main files will be created - Program.cs and Project.json. We can edit these files as per our requirement.
Syntax
dotnet new [arguments/options]
Options |
Description |
-l Or --lang |
Create specified language project in current directory. Currently it able to create C# and F# project
|
-tor --type |
Create specified type of project in current directory. The supported values are console, web, lib and xunittest |
Examples
I have run the following commands in command window.
>dotnet new
>dotnet new -l F#
>dotnet new - t web
Output
"dotnet restore" command
This command is use to restore the dependencies to the project. It uses NuGet to restore dependencies which are specified in project.json file. Dependencies restorations are done parallelly.
The configuration file "NuGet.config" provides the feeds where packages are located. When we installed CLI tools, by default one feed is present. We can specify more feeds by creating our own NuGet.config file in the project directory.
Syntax
dotnet restore [arguments/options]
Options |
Description |
-s Or –source [Source] |
Used to specify a source during the restore operation. This will overrides all sources specified by in nuget.config files. |
--packages [DIR] |
Specified the directory to restored packages placed in. |
--disable-parallel |
Using this command we can disables restoring multiple projects in parallel. |
-f Or --fallbacksource [FEED] |
It used to specify a fallback source which can be use in restore operation if main source is failing to restore |
--configfile [FILE] |
Specify the configuration file NuGet.config that is used to perform restore operation. |
--verbosity [LEVEL] |
Specify which level of logging to use. Available options are Debug, Verbose, Information, Minimal, Warning and Error. |
Example
I have run the following commands in command window.
>dotnet restore -s “D:\packages”
>dotnet restore --packages “Mypackages”
Output
"dotnet build" command
It builds a project and its dependencies. It builds multiple source files from the project and its dependencies into binary and binary is in IL (Intermediate Language) and it has a DLL extension. This command requires lock file to be present in current directory, it means that we must run "dotnet restore" command prior to building a command.
Syntax
>dotnet build [arguments/options]
Options |
Description |
-o Or --output [DIR] |
Build binaries are placed into specified directory. |
-b Or --build-base-path [DIR] |
Temporary outputs are created in specified directory. |
-f Or --framework [FRAMEWORK] |
Build compiles for the specific folder. |
-c Or --configuration [Debug|Release] |
Define the build configuration. Default value of configuration is "Debug". |
-r Or --runtime [RUNTIME_IDENTIFIER] |
Define the target runtime to build. |
--version-suffix [VERSION_SUFFIX] |
It defines what would be replaced with the version field in to the project.json file. |
--build-profile |
It defines the incremental safety check which user needs to turn on automatically incremental compilation. |
--no-incremental |
This will mark the build as unsafe for incremental build. It turns off incremental compilation and forces rebuild of project dependency graph |
--no-dependencies |
Only build the root project and ignore the build reference project. |
Example
I have run the following commands in command window
>dotnet build
>dotnet build -c release
>dotnet build --no-dependencies
Output
"dotnet run" command
This command is used to run our application from the source code. The primary responsibilities of this command are to compile source code, generate output program and run this program. This command depends on "dotnet build" command to build source code. The build command writes the output files in to "bin" folder. It also creates this folder if it does not exist. The "obj" folder is used to write temporary files.
Syntax
dotnet run [arguments/options]
Options |
Description |
-f Or --framework [framework identifier] |
Run the application under specified framework |
-c Or --configuration [Debug|Release] |
Use the specified configuration when publishing application. The default value of configuration is "debug" |
-p Or --project [Path] |
This command runs project specified in Path argument. It by default takes current directory if path is not specified. |
Example
I have run the following commands in command window
>dotnet run
>dotnet run -c release
>dotnet run -p “C:\CoreAppTest”
Output
"dotnet test" command
It runs unit test case under the configured test runner. Unit tests are class library type projects which have dependencies of unit test frameworks like xUnit or NUnit. The project.json file must contain the information about the test runner.
Following is sample project.json file.
Options |
Description |
- [project] |
It specifies the path of the project. By default it looks into current directory. |
-c Or --configuration[Debug|Release] |
Use the specified configuration when test application. The default value of configuration is "release" |
-o Or --output [DIR] |
Binaries are found in specified directory. |
-b Or --build-base-path [DIR] |
Temporary outputs placed in specified folder. |
-f Or --framework[FRAMEWORK] |
Specify the version of the framework used for test binaries. |
-r Or --runtime [RUNTIME_IDENTIFIER] |
Define the target runtime to test. |
--no-build |
It does not build project prior to running test. |
--parentProcessId |
It used by IDE to specify process ID. |
--port |
It used by IDE to define a port number for listen for a connection |
"dotnet publish" command
This command compiles the application and publishes the application with the project dependencies (specified in project.json file) and puts it into specified folder.
Options |
Description |
- [project] |
It specifies the path of the project. By default it looks into current directory. It first tries to find out path from project.json file via [project] node. It will through exception, if project.json file not found |
-c Or --configuration [Debug|Release] |
Use the specified configuration when publishing application. The default value of configuration is "debug" |
-o Or --output [DIR] |
Binaries are found in to specified directory. Default path: ./bin/[configuration]/[framework]/ for portable applications ./bin/[configuration]/[framework]/[runtime] for self-contained applications. |
-b Or --build-base-path [DIR] |
Temporary outputs placed in specified folder. |
-f Or --framework [FRAMEWORK] |
Specify the version of the framework used for publishing the application |
-r Or --runtime [RUNTIME_IDENTIFIER] |
Define the target runtime to publish the application. |
--version-suffix [VERSION_SUFFIX] |
It defines what would be replaced with the version field in to the project.json file. |
Example
I have run the following commands in command window,
>dotnet publish
>dotnet publish -c release
Output
"dotnet pack" command
It packs our code into the NuGet package. This command builds our project and creates NuGet packages so as a result of this; we have two packages with nupkg extension. One contains the code and the other contains debug symbols. NuGet dependencies of the project are packed with "nuspec" files and all dependencies are installed first when this package is installed.
Options |
Description |
- [project] |
It can be either path of project directory or project.json file. Default it will look in to current directory. |
-c Or --configuration [Debug|Release] |
Use the specified configuration when building the application. The default value of configuration is "debug". |
-o Or --output [DIR] |
Create packages in the specified directory |
--build-base-path [DIR] |
Temporary outputs placed in specified folder. |
--no-build |
It will skip build the application while creating pack. |
--version-suffix [VERSION_SUFFIX] |
It defines what would be replaced with the version field in to the project.json file. |
Example
I have run the following commands in command window.
>dotnet pack
Output
Summary
The .NET Core is now supporting CLI. Using CLI, we can perform various tasks, like create application, build application, publish the application from command prompt.The higher-level tools like IDE are also using this Command Line Interface internally, so we can get the same behavior as with IDE in command prompt.