C# Handbook

C# (said "C sharp") is a statically typed, object-oriented language that runs on .NET, Microsoft's free, open-source, cross-platform runtime. It was designed at Microsoft by Anders Hejlsberg and released in 2000; today it runs the same on Windows, macOS and Linux, and ships a new major version every November alongside .NET.

The reason to learn it is simple: one language covers an unusually wide range of real jobs. The same syntax you learn in Module 01 is what a backend developer writes in an ASP.NET Core API, what a game developer writes in Unity, and what an enterprise team writes for internal tools on Azure.

To write C# you need the .NET SDK (Software Development Kit). It contains the C# compiler, the runtime, the standard library and the dotnet command-line tool you will use for everything: creating projects, building, running, testing and adding packages. The runtime alone (without "SDK") can only run finished apps — install the SDK.

# with Homebrew
brew install --cask dotnet-sdk

# check it worked
dotnet --version

# with winget (built into Windows 10 and 11)
winget install Microsoft.DotNet.SDK.10

# open a NEW terminal, then check
dotnet --version

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

dotnet --version

On other distributions, the official installers and the dotnet-install script are listed on the .NET download page (dot.net).

dotnet --version prints the SDK version, such as 10.0.100. If the terminal says "command not found", close it and open a new one so it picks up the updated PATH.

Since .NET 10 you can run a single C# file directly — no project file needed. Create a file called app.cs, put one line in it, and run it:

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

Hello, World!

dotnet run app.cs

The first run takes a few seconds because it compiles the file; later runs of an unchanged file are much faster because the build is cached.

Console.WriteLine prints text followed by a new line. Console is a class from the System namespace, WriteLine is a method on it, the text in double quotes is a string, and the ; ends the statement. Every statement in C# ends with a semicolon.

A real project: dotnet new console

Single-file apps are perfect for learning and scripts. Real applications live in a project — a folder with a .csproj file that lists the target framework and any NuGet packages. Create one with a template:

dotnet new console -o HelloApp
cd HelloApp
dotnet run

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

The project file the template generates. Program.cs sits next to it; the build writes to bin/ and obj/ — never commit those two folders to git.

Console.WriteLine("Hello, World!")
Console.WriteLine("Welcome to C#");

Program.cs(1,35): error CS1002: ; expected

The build failed. Fix the build errors and run again.

Console.WriteLine("Hello, World!");
Console.WriteLine("Welcome to C#");

You can write C# in any text editor and run it with dotnet, but a proper IDE gives you IntelliSense (autocomplete that knows every type), red squiggles for compiler errors as you type, a debugger with breakpoints, and refactoring tools. There are three serious choices:

C# is not compiled straight to machine code, and it is not interpreted line by line either. It goes through two stages, and knowing them explains a lot of things you will see later — the .dll files in bin/, why the first call to a method is slightly slower, and why C# and F# code can call each other.

1. 1
   1. The C# compiler (Roslyn) checks and compiles

   It reads your .cs files, checks every type, and reports errors like CS1002. If everything is valid it produces an assembly — a .dll file containing IL (Intermediate Language), a CPU-independent bytecode, plus metadata describing every type and method.

2. 2
   2. The CLR loads the assembly

   The CLR (Common Language Runtime) is the engine that runs .NET code. It loads your assembly and the standard library, checks the IL is safe, and sets up the garbage-collected memory your objects will live in.

3. 3
   3. The JIT turns IL into machine code

   The first time each method is called, the JIT (just-in-time) compiler translates its IL into native instructions for the actual CPU — x64 or ARM64. Later calls reuse that native code, and hot methods are recompiled with more optimisations as the program runs.

4. 4
   4. The garbage collector cleans up

   You create objects with new but never free them yourself. The GC finds objects nothing refers to any more and reclaims their memory automatically.

.NET SDK

The developer kit: compiler, runtime, standard library and the dotnet CLI.

CLR

Common Language Runtime — the engine that loads assemblies, JIT-compiles IL and manages memory.

IL

Intermediate Language — the CPU-independent bytecode the C# compiler produces.

JIT

Just-in-time compiler — turns a method's IL into native machine code the first time it runs.

Assembly

A compiled .dll or .exe containing IL and metadata.

BCL

Base Class Library — the standard library: Console, string, List<T>, files, networking and more.

NuGet

The package manager for .NET; dotnet add package installs from nuget.org.

Garbage collector

The part of the CLR that frees memory for objects nothing references any more.

The one-line app.cs uses top-level statements: code written directly in the file, which the compiler wraps in a hidden Main method for you. Older tutorials (and many real codebases) show the full form instead. Both compile to the same thing:

using System;

namespace HelloApp;

class Program
{
    static void Main(string[] args)
    {
        // Main is where the program starts
        Console.WriteLine("Hello from Main");
        Console.WriteLine($"Arguments passed: {args.Length}");
    }
}

Hello from Main
Arguments passed: 0

• using System; imports a namespace so you can write Console instead of System.Console. Modern projects turn on implicit usings, which import the common namespaces (System, System.Collections.Generic, System.Linq, System.IO…) automatically — that is why the one-liner needed no using.
• namespace HelloApp; groups your types under a name so they do not clash with anyone else's. The semicolon form applies to the whole file.
• class Program — all C# code lives inside a type. Top-level statements hide this; it is still there after compilation.
• static void Main(string[] args) — the entry point. args holds command-line arguments.
• // starts a comment to the end of the line; /* … */ spans lines; /// is an XML documentation comment that IDEs show on hover.

With top-level statements, your program's code comes first and any classes, records or other types you declare go after it. This is the style every example in this handbook uses:

/* Top-level statements run first, in order.
   Types are declared after them. */
var greeter = new Greeter("Ada");
greeter.SayHello();
Console.WriteLine(Greeter.Count);

/// <summary>Prints a greeting for one person.</summary>
class Greeter
{
    public static int Count = 0;
    private readonly string _name;

    public Greeter(string name)
    {
        _name = name;
        Count++;
    }

    public void SayHello() => Console.WriteLine($"Hello, {_name}!");
}

Hello, Ada!
1

console.WriteLine("Hello, World!");

Program.cs(1,1): error CS0103: The name 'console' does not exist in the current context

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

Seventeen modules, each its own page. The rail on the left lists them; the bar at the top and the pill at the bottom-left track how far you are. A lesson ticks itself when you reach its end, and the tick survives closing the tab — no account needed.

• Examples are complete programs with the exact output they print. C# does not run in a browser, so nothing executes on this page — instead, every example was compiled and run with the real .NET SDK when the page was built, and the output shown is what it actually printed. Copy an example into app.cs, run dotnet run app.cs, and you will see the same thing. Then do its "Your turn" task.
• Error cards are real compiler diagnostics (CSxxxx) and real runtime exceptions, copied from actually running the broken code. Module 11 collects the fifteen every beginner hits.
• Traces step through a program line by line, showing what each variable holds — use them for loops, recursion and virtual dispatch.
• Interview questions appear where the topic is taught and are collected in Module 15, tiered junior / mid / senior.
• The handbook ends with a certification exam (Module 16 → exam): 25 questions, 70% to pass. Then the ATS resume checker with a real job posting.

An AI assistant can write a working C# class in seconds. That is exactly why you should type the examples yourself while learning: the goal is not the code, it is the model in your head of what the compiler checks, what lives on the stack and the heap, and which method actually runs — the model an interviewer is testing when they ask you to explain code on a whiteboard.

Ready? Module 01 starts with variables, the built-in types, and the difference between value types and reference types — the idea the rest of C# is built on.