Setting Up Your Machine for .NET Development

If you’re brand new to .NET, the first step is getting your computer ready.

This guide walks you through installing .NET SDK and Visual Studio Code (VS Code) on Windows, macOS, and Linux. By the end, you’ll run your first Hello World program — the classic test that proves your setup works.

👉 This page is meant to be a reference. I’ll link back to it in other tutorials, so you always have one place to check the setup steps.

---

What You’ll Learn

• Understand .NET version choices (LTS vs Current).
• Install the .NET SDK (the core tools you need).
• Verify your installation with dotnet --version and dotnet --info.
• Create and run a simple Hello World app.
• Set up VS Code as your editor. And how to debug your application.
• Troubleshoot common installation issues.

---

System Requirements

Before you begin, make sure your system meets these requirements:

• OS: Windows 10+, macOS 11+, or modern Linux distribution
• RAM: 4GB minimum, 8GB recommended
• Disk Space: ~1-2GB for .NET SDK
• Architecture: x64, ARM64, or x86

---

Step 1: Install the .NET SDK

The .NET SDK gives you the compiler, runtime, and tools. You only need to install it once.

• Download from dotnet.microsoft.com/download.
• Choose the SDK (not just the runtime).
• Install like any other app on your OS.

The .NET download page showing SDK options for different platforms

In this guide we will select .NET 9.0 (the most recent release). However, if you prefer the LTS version you can select .NET 8.

.NET 9 (Current Release):

• Latest features and performance improvements
• Supported until May 2026 (when .NET 10 releases)
• Recommended for learning and new projects

.NET 8 (LTS - Long Term Support):

• Supported until November 2026
• Stable, conservative choice
• Good for enterprise applications requiring longer support

Windows

1. Download the Windows installer (.exe) for the .NET 9.0 SDK.
2. Run the installer, accept defaults.

The windows installer for .NET 9

3. Close and reopen your Command Prompt or PowerShell (important for PATH updates).
4. Verify the installation:

dotnet --version

You should see a version number like 9.0.205.

dotnet --info

This shows detailed information about your SDK installation, runtime versions, and operating system.

Terminal output showing the installed .NET SDK version

macOS

1. Download the .pkg installer for macOS (Intel or Apple Silicon) for .NET 9.0 SDK.

   Selecting the correct .NET 9 installer for your Mac (Intel or Apple Silicon)

2. Run the installer.

   The .NET SDK installer running on macOS

3. Close and reopen your Terminal.

4. Verify:

   dotnet --version
   dotnet --info
   

   Terminal on macOS showing .NET 9 installation

Note for Apple Silicon (M1/M2/M3): Some older NuGet packages may require Rosetta 2. Install if needed: softwareupdate --install-rosetta

Linux

Linux comes in many distributions (Ubuntu, Fedora, Arch, openSUSE, RHEL, and more), each with its own package manager and installation method. This guide shows installation on Ubuntu/Debian-based systems as they’re the most common for beginners.

For other Linux distributions (Fedora, CentOS, RHEL, Alpine, SLES, openSUSE, etc.), please refer to the official Microsoft .NET installation guide for Linux, which provides specific instructions for your distribution.

Ubuntu/Debian Installation:

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

dotnet --version
dotnet --info

Installing .NET SDK on Ubuntu/Debian using apt-get

---

Step 2: Install Visual Studio Code

VS Code is a lightweight, cross-platform editor — perfect for .NET beginners.

1. Download from code.visualstudio.com.
2. Install for your platform (Windows .exe, macOS .dmg, Linux .deb/.rpm).
3. Launch VS Code.

Inside VS Code:

• Open the Extensions view (Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS).
• Search for C# Dev Kit and click Install.
• This gives you IntelliSense, debugging, and project templates.

VS Code

C# Dev Kit extension in VS Code Extensions marketplace

Note: The C# Dev Kit extension will also install the C# extension automatically.

Alternative IDEs (Optional)

While this guide uses VS Code, other options include:

• Visual Studio (Windows/Mac): Full-featured IDE with built-in .NET support
• JetBrains Rider: Premium cross-platform .NET IDE
• Command-line editors: vim, nano, emacs with OmniSharp

For beginners, VS Code is recommended due to its simplicity and cross-platform consistency.

---

Step 3: Create Your First Project

Pick a folder where you want to work (e.g., Documents/Projects or ~/projects).

Run these commands in your terminal or VS Code’s built-in terminal (Ctrl+`` or Cmd+``):

dotnet new console -o HelloWorld
cd HelloWorld
dotnet run

Expected output:

The template "Console App" was created successfully.

Processing post-creation actions...
Restoring C:\...\HelloWorld\HelloWorld.csproj:
  Determining projects to restore...
  Restored C:\...\HelloWorld\HelloWorld.csproj (in 156 ms).
Restore succeeded.

Hello, World!

Creating and running your first .NET console application

That’s it — your machine is officially ready for .NET development! 🎉

What just happened:

• dotnet new console -o HelloWorld created a new console application
• cd HelloWorld navigated into the project folder
• dotnet run compiled and executed the program

---

Step 4: Open in VS Code

In VS Code, open the HelloWorld folder:

• File → Open Folder → select the HelloWorld directory

Program.cs file open in VS Code

First Time Debugging

1. Open Program.cs — you’ll see the single line of code: Console.WriteLine("Hello, World!");
2. Click to the left of the line number to set a breakpoint (red dot appears)

Setting a breakpoint in VS Code by clicking left of the line number

3. Press F5 to start debugging
4. If prompted, select C# as the debugger
5. VS Code will generate .vscode/launch.json automatically
6. The program will pause at your breakpoint
7. Use the debug toolbar to step through code (F10), continue (F5), or stop (Shift+F5)

What you should see:

• IntelliSense suggestions as you type
• Syntax highlighting
• Debug console showing output
• Variables panel showing current values

VS Code debugging interface showing breakpoint, variables panel, and debug toolbar

---

Understanding the dotnet CLI

You’ve just used several dotnet commands. Here are the most common ones you’ll use:

Command	Purpose
dotnet --version	Check installed SDK version
dotnet --info	Show detailed SDK and runtime information
dotnet new list	See available project templates
dotnet new console -o ProjectName	Create a new console app
dotnet run	Build and run your app
dotnet build	Compile without running
dotnet add package <name>	Install NuGet packages
dotnet restore	Restore project dependencies
dotnet test	Run unit tests
dotnet clean	Remove build artifacts

You’ll use these throughout your .NET journey.

---

Troubleshooting

“dotnet command not found” after installation

Windows:

• Restart your terminal or PowerShell after installation
• If still not working, log out and log back in
• Verify PATH: Open PowerShell and run $env:PATH -split ';' | Select-String dotnet

macOS/Linux:

• Close and reopen your terminal
• Or reload your shell: source ~/.bashrc (bash) or source ~/.zshrc (zsh)
• Verify PATH: echo $PATH | grep dotnet
• Try running the full path: /usr/local/share/dotnet/dotnet --version

VS Code can’t find .NET SDK

1. Reload VS Code window: Ctrl+Shift+P (or Cmd+Shift+P) → type “Reload Window”
2. Verify dotnet --version works in VS Code’s integrated terminal
3. Check that C# Dev Kit extension is installed and enabled
4. Restart VS Code completely

Permission errors on Linux

If you see permission denied errors:

sudo chown -R $USER:$USER ~/.dotnet

First dotnet run is slow

The very first time you run a .NET app, it needs to:

• Download NuGet packages
• Restore dependencies
• Compile the project

This is normal and only happens once per project.

F5 debugging doesn’t work

1. Make sure you’re in the project folder (containing the .csproj file)
2. Install the C# Dev Kit extension
3. Select C# as the debugger when prompted
4. Check the Output panel (Ctrl+Shift+U) for error messages

---

Wrapping Up

By now you’ve:

• Understood the difference between .NET 9 (Current) and .NET 8 (LTS)
• Installed the .NET 9 SDK on Windows, macOS, or Linux
• Installed VS Code and the C# Dev Kit extension
• Verified your install with dotnet --version and dotnet --info
• Created and run a Hello World console app
• Learned essential dotnet CLI commands
• Know how to troubleshoot common issues

You’re ready for any .NET tutorial — whether it’s building web APIs, desktop apps, or AI integrations.

---

Additional Resources

• Official .NET Learning Path
• C# Documentation
• VS Code .NET Tutorial
• .NET CLI Reference