.NET CLI Documentation

Introduction to the .NET CLI

The .NET Command Line Interface (CLI) is a powerful, cross-platform toolset for developing, building, running, and publishing .NET applications. It allows you to interact with your .NET projects and solutions from the terminal or command prompt, providing a consistent experience across Windows, macOS, and Linux.

With the .NET CLI, you can:

• Create new projects and solutions.
• Restore dependencies.
• Build projects.
• Run applications.
• Publish applications for deployment.
• Execute tests.
• Manage project references.
• And much more.

Getting Started

To get started with the .NET CLI, ensure you have the .NET SDK installed on your machine. You can download it from the official dotnet.microsoft.com/download website.

Once installed, you can verify the installation by opening your terminal and running:

dotnet --version

To create a new console application, navigate to your desired directory and run:

dotnet new console -o MyConsoleApp

This will create a new directory named MyConsoleApp containing a basic console project structure.

Common Commands

dotnet new

Creates a new .NET project or solution from a template.

Common templates include:

• console: A .NET console application.
• classlib: A .NET class library.
• web: An ASP.NET Core web application.
• webapi: An ASP.NET Core web API project.
• mstest: A .NET unit test project using MSTest.
• xunit: A .NET unit test project using xUnit.
• nunit: A .NET unit test project using NUnit.
• sln: A .NET solution file.

Example: Create a new ASP.NET Core MVC project:

dotnet new mvc -o MyMvcApp -n MyWebApp

To list available templates, use:

dotnet new --list

dotnet build

Compiles a .NET project.

Example: Build the current project in Release configuration:

dotnet build --configuration Release

dotnet run

Compiles and runs a .NET project.

Example: Run the current project:

dotnet run

dotnet publish

Publishes a .NET project for deployment.

Example: Publish a self-contained Windows x64 application:

dotnet publish --runtime win-x64 --configuration Release --self-contained true

dotnet test

Runs unit tests for a .NET project.

Example: Run tests and output results to a specific logger:

dotnet test --logger "console;verbosity=detailed"

dotnet add

Adds a reference to a project or package.

Example: Add a NuGet package:

dotnet add MyProject.csproj package Newtonsoft.Json

dotnet remove

Removes a reference to a project or package.

Example: Remove a NuGet package:

dotnet remove MyProject.csproj package Newtonsoft.Json

dotnet restore

Restores the .NET project's dependencies.

This command is usually run automatically by other commands like build and run, but can be run explicitly.

dotnet restore

dotnet list

Lists projects or packages in a project or solution.

Example: List all NuGet packages in the current project:

dotnet list package

Command Structure

The general structure of a .NET CLI command is:

dotnet [<COMMAND>] [<ARGUMENTS>] [--options]

• dotnet: The executable for the .NET CLI.
• <COMMAND>: The action you want to perform (e.g., new, build, run).
• <ARGUMENTS>: Positional arguments that specify the target of the command (e.g., project file, template name).
• --options: Flags or switches that modify the command's behavior (e.g., --configuration Release).

Options and Arguments

Commands can take positional arguments and named options. Positional arguments are typically required and their meaning depends on the command.

Options, denoted by double hyphens (--) or single hyphens (-) for short forms, modify the command's behavior. For example:

• --configuration or -c: Specifies the build configuration (e.g., Debug, Release).
• --output or -o: Specifies the output directory for generated files.
• --force: Overwrites files that already exist.

Many commands also accept global options that apply to all `dotnet` commands, such as:

• --help or -h: Displays help information for a command.
• --version or -v: Displays the .NET CLI version.
• --verbose: Enables verbose logging.

To see all available options for a specific command, use the --help flag:

dotnet new --help

Global Options

These options can be used with any dotnet command:

• --help, -h: Shows help for the command.
• --info: Prints detailed information about the .NET installation.
• --list-runtimes: Lists installed .NET runtimes.
• --list-sdks: Lists installed .NET SDKs.
• --verbosity, -v: Sets the verbosity level for the command (q, m, n, d, diag).

Example: Get detailed information about the .NET installation:

dotnet --info

More Examples

Create a new web API project in a specific directory:

dotnet new webapi -o src/MyApi -n MyAwesomeApi

Restore dependencies for a solution file, build it in Release configuration, and then publish it to a specific folder:

dotnet restore MySolution.sln
dotnet build MySolution.sln --configuration Release
dotnet publish MySolution.sln --configuration Release --output ./publish

Troubleshooting

• Command not found: Ensure the .NET SDK is installed and its path is correctly configured in your system's environment variables.
• Dependency errors: Run dotnet restore to ensure all project dependencies are downloaded and restored correctly. Check your NuGet sources if you are using private feeds.
• Build failures: Examine the compiler errors carefully. They often point to syntax issues or missing types/libraries. Ensure your project file (.csproj) is valid.
• Publishing issues: Verify the target runtime (--runtime) and self-contained (--self-contained) settings are correct for your deployment environment.