Learn C#

Where C# is used

Web backends and APIs

ASP.NET Core is the framework for building web servers and HTTP APIs in C#, and it runs on Linux, macOS and Windows.

Windows desktop software

Windows Forms, WPF and WinUI are the C#-first ways to build desktop applications for Windows.

Games with Unity

The Unity engine's scripting language is C#, so the gameplay code in Unity games, from small hobby projects to large releases, is written in it.

Cross-platform mobile and desktop apps

.NET MAUI builds Android, iOS, macOS and Windows apps from a single C# codebase.

Business and cloud services

Background workers, message processors and internal services are commonly C#, particularly in organisations that already run on Microsoft's cloud, Azure.

Your first C# program

Saved as Program.cs. You can paste it straight into the playground to see it run.

using System;

string city = "Pune";
int readers = 3;

Console.WriteLine("Hello from C#.");
Console.WriteLine($"{city} has {readers} readers today.");
Console.WriteLine($"Doubled, that is {readers * 2}.");

What it prints

Hello from C#.
Pune has 3 readers today.
Doubled, that is 6.

1. Line 1 brings the System namespace into scope, which is where Console lives. New console projects switch on implicit usings that already include System, so this line is often unnecessary, but it is harmless and it makes the program work whatever the project settings are.
2. Lines 3 and 4 declare two variables with explicit types: string for text and int for a whole number. Every statement ends with a semicolon, and the compiler will refuse to store text in readers or a number in city.
3. There is no class and no Main method in this file. Since C# 9 a program can be written as top-level statements: the compiler wraps these lines in the entry point for you. Older tutorials show the class Program { static void Main() { ... } } form, which still works and is what you will see inside larger projects.
4. Line 6 prints a line. Console.WriteLine writes its argument followed by a newline.
5. Lines 7 and 8 use string interpolation. The $ before the opening quote lets you put expressions in braces, so {city} is replaced by the variable's value and {readers * 2} is calculated first and then dropped into the sentence.

Try it in the C# playground →

Run C# on your own computer

C# needs the .NET SDK, a single free download that includes the compiler, the runtime and the dotnet command-line tool. Once it is installed, creating and running a program is two commands.

1. 1

   Install the .NET SDK

   Download the current SDK from dotnet.microsoft.com for Windows, macOS or Linux and run the installer; on Linux the download page also lists package-manager commands for the main distributions. Choose the SDK rather than the runtime on its own: the runtime only runs programs, the SDK also builds them. Any version that is still in support works for everything on this site.

2. 2

   Check it works

   Open a terminal and ask for the version. If the command is not found on Windows, close the terminal and open a new one so it picks up the updated PATH.

   Shell

   dotnet --version

3. 3

   Create a project

   This makes a folder called Hello containing Hello.csproj, which describes the project, and Program.cs, which already holds a one-line hello-world. Replace the contents of Program.cs with the program above.

   Shell

   dotnet new console -n Hello

4. 4

   Run it

   Run this inside the Hello folder. The first run compiles the project and takes a moment; later runs are quicker. dotnet run rebuilds whenever the source has changed, so it is the only command you need in the edit-and-run loop.

   Shell

   dotnet run

5. 5

   Or run a single file (.NET 10 SDK and later)

   Newer SDKs can run a lone .cs file without a project: save the program as hello.cs and run it directly. This is the quickest way to try a snippet; the project form is still what you will use for anything larger than one file.

   Shell

   dotnet run hello.cs

6. 6

   Use an editor that understands C#

   Visual Studio on Windows and VS Code with the C# Dev Kit extension on any platform are Microsoft's own editors for C#. Both show type errors as you type, which in a statically typed language is most of the point.

A learning order for C#

Stages, not a timetable. Each one exists because the next would not make sense without it, and how long each takes depends on how much you write.

1. Stage 1. Output, types and variables

   • Console.WriteLine and Console.ReadLine
   • int, double, string and bool
   • var and type inference
   • string interpolation
   • arithmetic and integer division

   C# insists on knowing the type of every value, so the first job is learning what the basic types are and how the compiler tells you when you mix them up. Type errors at this stage are friendly and precise.

2. Stage 2. Control flow and methods

   • if / else and switch
   • comparison and logical operators
   • for, foreach and while
   • break and continue
   • methods with parameters and return values

   Loops and conditions work as they do in any language, but foreach and methods with typed parameters are where C# starts to feel like itself. Methods come early because a top-level program gets unwieldy fast.

3. Stage 3. Collections and LINQ

   • arrays
   • List<T>
   • Dictionary<TKey, TValue>
   • generics in plain terms
   • LINQ: Where, Select and OrderBy

   Generics are why List<int> and List<string> are the same class with different contents, and LINQ lets you filter and reshape a collection in one readable expression. Together they replace most of the hand-written loops from the previous stage.

4. Stage 4. Classes and objects

   • classes, fields and properties
   • constructors
   • methods and this
   • inheritance and interfaces
   • records

   C# is object-oriented at heart: almost everything you write is a class, a struct or a record. Properties, records and interfaces are the parts that differ most from other languages and are worth learning slowly.

5. Stage 5. Null, errors and files

   • nullable reference types and the ? annotation
   • try / catch / finally
   • exceptions and when to throw
   • reading and writing files with System.IO
   • JSON with System.Text.Json

   Null is the classic C# failure and the compiler now helps you avoid it, but only if you understand what its warnings mean. Files and JSON are where programs meet real data.

6. Stage 6. Async, packages and a real project

   • async and await
   • NuGet packages
   • unit tests with dotnet test
   • namespaces and project structure
   • a first ASP.NET Core or console project

   Nearly every real C# program waits on a network or a disk, and async/await is how that is written without blocking. From here the path splits into web, desktop, games or services, each with its own framework to learn.

Mistakes beginners make in C#

Calling a method on something that is null

NullReferenceException, 'Object reference not set to an instance of an object', is the classic C# crash. A variable of a reference type — a string, a List, your own class — can hold nothing at all, and calling anything on it fails at runtime. With nullable reference types switched on, which new projects do by default, the compiler warns beforehand with CS8602, 'Dereference of a possibly null reference'; take those warnings seriously rather than silencing them.

Expecting 7 / 2 to be 3.5

Both operands are int, so the result is the int 3 and the fraction is discarded without any warning. Write 7.0 / 2, or cast one side with (double) a / b, when you want a decimal result.

Storing Console.ReadLine() straight into an int

int age = Console.ReadLine(); stops the build with CS0029, 'Cannot implicitly convert type', because everything typed at the console arrives as text. Convert it with int.Parse, or better int.TryParse, which does not throw an exception when the user types something that is not a number.

Removing items from a List inside a foreach over it

This throws InvalidOperationException, 'Collection was modified; enumeration operation may not execute.' The loop is reading the list while you change it. Loop over a copy, count backwards with a for loop, or use RemoveAll with a condition.

Assuming assignment copies an object

var b = a; where a is a List gives you two names for the same list, so adding to b also changes a. Assigning an int, a double or a struct copies the value instead. No error is raised, which is what makes it confusing; the rule is that classes are shared by reference and structs and primitives are copied.

Strengths and trade-offs

Who C# is for

C# suits a beginner who wants a statically typed language with a strong compiler and a clear route to real applications, especially anyone aiming at Windows software, web backends with ASP.NET Core or games in Unity. It is also a natural next language for someone who knows Python or JavaScript and wants to find out what static types and object-oriented design feel like when the tooling supports them properly. Look elsewhere if you want the smallest possible setup and syntax (Python), if your target is systems-level code with no runtime (C, C++ or Rust), or if you want the language that runs inside the web browser itself (JavaScript).

Questions about learning C#

Do I need Windows to learn C#?

No. The .NET SDK installs on macOS and Linux, and dotnet new, dotnet run and the rest of the command-line tools work identically there. VS Code with the C# Dev Kit gives you a full editor on any platform. The exceptions are the Visual Studio IDE, which is Windows-only, and the Windows-only UI frameworks such as Windows Forms and WPF — but none of those matter until you decide to build a Windows desktop application.

What is the difference between C# and .NET?

C# is the language: the syntax, the types and the rules the compiler enforces. .NET is the platform it runs on: the runtime that manages memory and executes your code, the standard library it calls into, and the SDK you install. Other languages such as F# and Visual Basic also run on .NET, but when people say '.NET developer' they usually mean C# on .NET.

Is C# the same as C or C++?

No, despite the name. C# borrowed the braces-and-semicolons look of C and C++, but it manages memory automatically, has no pointers in ordinary code, and is much closer to Java in how it works. Knowing C helps with reading the syntax; it does not help much with how C# programs are structured.

Which .NET version should I install?

The current long-term-support (LTS) release listed on the download page, unless a course or workplace tells you otherwise. Microsoft releases a new .NET each November and alternates LTS and shorter-support versions; everything on this site works with any version still in support. Avoid anything called '.NET Framework' for new learning: that is the older, Windows-only line, which no longer gets new features.

The primary source

When this guide and the official documentation disagree, the documentation is right and we would like to hear about it.

• C# documentation (Microsoft Learn) ↗
• A tour of the C# language ↗
• Download the .NET SDK ↗