Command Line Interface (CLI) Tools In .NET Core

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.

This command run project specified in Path argument. It default take current directory if path is not specified.

This command run project specified in Path argument. It default take current directory if path is not specified.

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

It defines what would be replaced with the version field in to the project.json file.

It defines what would be replaced with the version field in to the project.json file.

"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

It defines what would be replaced with the version field in to the project.json file.

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.