C# / .NET Setup Guide - CodeSwordsman

Set up .NET: install the SDK and pin versions, manage global tools, switch NuGet sources, scaffold from templates, debug and fix common errors.

.NET 8 LTSUpdated 2026-10-2928 commands

Install & Version Management

Install the .NET 8 SDK on Windows, including the runtime and dotnet CLI

winget install Microsoft.DotNet.SDK.8

Install the SDK with Homebrew on macOS or the official repo on Ubuntu

# macOS
brew install --cask dotnet-sdk
# Ubuntu / Debian
sudo apt update && sudo apt install -y dotnet-sdk-8.0

List installed SDKs and runtimes; the key command when versions mismatch

dotnet --list-sdks
dotnet --list-runtimes

Write a global.json in the repo root to pin the SDK version for the team

dotnet new globaljson --sdk-version 8.0.301 --force

List installed workloads and add ones such as MAUI or Blazor WebAssembly

dotnet workload list
dotnet workload install maui

Mirrors & Proxy

Add a China NuGet mirror to prefer during restores

dotnet nuget add source https://mirrors.huaweicloud.com/repository/nuget/v3/index.json -n huaweicloud

Show enabled sources and their order

dotnet nuget list source

Disable the official source on slow networks to avoid restore timeouts, then re-enable when needed

dotnet nuget disable source nuget.org

Add a private corporate feed with stored credentials, mind the plaintext trade-off

dotnet nuget add source https://nuget.example.com/v3/index.json -n corp -u user -p password --store-password-in-clear-text

Route dotnet restore through a proxy on Windows; use export on macOS/Linux

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890

Environment Variables

Check which install directory the dotnet command actually resolves to

# Windows
where dotnet
# macOS / Linux
which -a dotnet

Some IDEs and self-hosted apps rely on DOTNET_ROOT to find the runtime

# Windows PowerShell
[Environment]::SetEnvironmentVariable("DOTNET_ROOT", "C:\Program Files\dotnet", "Machine")
# macOS / Linux
echo 'export DOTNET_ROOT=/usr/share/dotnet' >> ~/.zshrc

Set the ASP.NET Core environment; use Development locally

# Windows
setx ASPNETCORE_ENVIRONMENT Development
# macOS / Linux
export ASPNETCORE_ENVIRONMENT=Development

Set DOTNET_CLI_TELEMETRY_OPTOUT=1 to disable CLI telemetry

echo %DOTNET_CLI_TELEMETRY_OPTOUT%

Create & Verify

Show SDK, runtime, RID and config paths in one place

dotnet --info

Scaffold a Web API project and run it; browse the URL printed in the terminal

dotnet new webapi -o demo --use-controllers
cd demo
dotnet run

Create a console project to verify the basic toolchain works

dotnet new console -o hello
cd hello
dotnet run

Publish for a target platform; self-contained output is much larger

dotnet build -c Release
dotnet publish -c Release -r linux-x64 --self-contained false

Run every test project in the solution

dotnet test

IDE & Plugins

Install the C# extension and the official dev kit with debugging, tests and hot reload

code --install-extension ms-dotnettools.csharp
code --install-extension ms-dotnettools.csdevkit

Install Visual Studio Community on Windows; Rider is the usual macOS alternative

winget install Microsoft.VisualStudio.2022.Community

Install global CLI tools such as the EF Core migrations tool

dotnet tool install -g dotnet-ef
dotnet tool list -g

Troubleshooting

When SDK or runtime versions mismatch, check what is actually installed first

dotnet --list-sdks
dotnet --list-runtimes

Disable incremental builds and log verbosely to locate the compile failure

dotnet build --no-incremental -v n

Clear all local NuGet caches and restore again when packages are corrupt

dotnet nuget locals all --clear

Repair workloads when a broken install breaks templates or builds

dotnet workload repair

Regenerate and trust the dev certificate when browsers warn about the local HTTPS cert

dotnet dev-certs https --trust

Find the process holding the default port when startup fails

netstat -ano | findstr :5000

Related tools

JSON to Entity JSON Formatter