.NET - Understanding .NET CLI

Understanding .NET CLI

Introduction

The .NET CLI (Command-Line Interface) is a powerful and flexible tool that enables developers to create, build, run, test, and publish .NET applications directly from the command line. Whether you're working on Windows, macOS, or Linux, the .NET CLI allows you to streamline your development workflow without relying solely on Visual Studio or any graphical user interface.

This comprehensive guide will help you understand how the .NET CLI works, how to install it, and how to use it effectively for various types of .NET projects such as console applications, web APIs, libraries, and more.

What is .NET CLI?

The .NET CLI is a cross-platform toolchain for developing .NET applications. It is available with the .NET SDK and enables command-line operations for managing your entire development lifecycle, including project creation, code compilation, testing, and deployment.

Key Benefits of .NET CLI

• Cross-platform support (Windows, macOS, Linux)
• Lightweight and ideal for CI/CD pipelines
• Scriptable in build and deployment environments
• Enables faster prototyping and automation
• Minimal dependencies – doesn't require a full IDE

Installing .NET CLI

To use the .NET CLI, you need to install the .NET SDK, which includes the CLI tool.

Install .NET SDK on Windows (via winget)

winget install Microsoft.DotNet.SDK.7

Install on Ubuntu (Linux)

sudo apt-get update
sudo apt-get install -y dotnet-sdk-7.0

Verify Installation

dotnet --version
dotnet --info

Basic Structure of .NET CLI Command

Every .NET CLI command follows this general structure:

dotnet <command> [arguments] [options]

Example:

dotnet new console -n HelloWorldApp

Commonly Used .NET CLI Commands

1. dotnet new – Creating a New Project

Use this command to create new projects from templates.

dotnet new console -n MyApp
dotnet new webapi -n MyWebApi
dotnet new classlib -n MyLibrary
dotnet new mvc -n MyMvcApp

List Available Templates

dotnet new --list

2. dotnet build – Compiling the Project

This command builds the source code into binaries.

cd MyApp
dotnet build

3. dotnet run – Running the Application

Execute the compiled application from the source code.

dotnet run

4. dotnet publish – Packaging for Deployment

This command creates a self-contained or framework-dependent deployment.

dotnet publish -c Release -o ./publish

5. dotnet test – Running Unit Tests

Run test projects and get test results.

dotnet new xunit -n MyTests
cd MyTests
dotnet test

6. dotnet add – Adding Project References or Packages

Add NuGet packages or project references to a project.

dotnet add package Newtonsoft.Json
dotnet add reference ../MyLibrary/MyLibrary.csproj

7. dotnet restore – Restore Dependencies

Restores NuGet dependencies specified in the project file.

dotnet restore

8. dotnet clean – Clean Output

Deletes all build artifacts from the project directory.

dotnet clean

Creating a Console App with .NET CLI – Step-by-Step

Step 1: Create the Project

dotnet new console -n MyConsoleApp
cd MyConsoleApp

Step 2: View the Default Code

File: Program.cs

using System;

Console.WriteLine("Hello, CLI World!");

Step 3: Build the App

dotnet build

Step 4: Run the App

dotnet run

Creating a Web API Project Using CLI

Step 1: Create the Web API

dotnet new webapi -n MyWebApi
cd MyWebApi

Step 2: Run the Web API

dotnet run

Access your API at https://localhost:5001

Customizing CLI Behavior with global.json

The global.json file allows you to define the .NET SDK version used by your project.

Example global.json

{
  "sdk": {
    "version": "7.0.100"
  }
}

Understanding Project Structure Created by CLI

For Console App:

• Program.cs – Entry point of the application
• MyConsoleApp.csproj – Project file (defines dependencies, SDK, target framework)
• obj/ – Temporary object files created during build
• bin/ – Compiled output binaries

Using CLI for Multi-Project Solutions

Create a Solution File

dotnet new sln -n MySolution

Add Projects to Solution

dotnet sln add MyApp/MyApp.csproj
dotnet sln add MyLibrary/MyLibrary.csproj

Useful .NET CLI Options and Flags

--output <path>     Specify output directory
--framework <TFM>   Target framework (e.g., net6.0, net7.0)
--configuration     Debug or Release
--verbosity         Quiet, Minimal, Normal, Detailed
--no-restore        Skips implicit restore

Integrating CLI into CI/CD Pipelines

The .NET CLI is ideal for automation in continuous integration and delivery systems like GitHub Actions, Azure DevOps, Jenkins, and GitLab CI.

Sample GitHub Actions Workflow

name: Build and Test

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET
      uses: actions/setup-dotnet@v2
      with:
        dotnet-version: '7.0.x'
    - name: Install dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --no-restore
    - name: Test
      run: dotnet test --no-build

Common Errors and Troubleshooting

Command Not Found

Ensure the .NET SDK path is correctly set in your environment variables.

Version Mismatch

Check the version with dotnet --info and adjust with global.json.

Failed Restore

Use dotnet restore --verbosity detailed to troubleshoot dependency issues.

The .NET CLI is a foundational tool for every .NET developer. It gives you complete control over your development workflow and enables rapid development, automation, and cross-platform compatibility. Whether you're building a console app, a web API, or a cloud-native microservice, mastering the .NET CLI will enhance your productivity and make your development more efficient.

Start using the CLI today and incorporate it into your daily workflow, automation scripts, and DevOps pipelines to take full advantage of the .NET ecosystem.