Fundamentals

Every example in this handbook is a top-level statements program: the statements at the top of Program.cs run in order, from the first line to the last, and the compiler wraps them in a hidden Main method for you (Getting Started shows the long form). The two methods you will use constantly are Console.WriteLine, which prints and then moves to a new line, and Console.Write, which prints and stays on the same line.

// A single-line comment: the compiler ignores it
Console.WriteLine("Order summary");
Console.Write("Items: ");      // no newline after this
Console.WriteLine(3);
Console.WriteLine();           // an empty line

/* A block comment can
   span several lines */
Console.WriteLine("Total: " + 42.5);
Console.WriteLine("Tab\tseparated and a \"quote\"");

Order summary
Items: 3

Total: 42.5
Tab	separated and a "quote"

Console.ReadLine() reads one line the user typed and returns it as a string, without the Enter key. It returns null when there is no more input (for example, when input is piped from a file that has ended), so the type is string?. The program below reads two lines; the input it was run with is shown under the code.

Console.Write("Name: ");
string? name = Console.ReadLine();

Console.Write("Age: ");
string? ageText = Console.ReadLine();
int age = int.Parse(ageText ?? "0");   // text -> number

Console.WriteLine();
Console.WriteLine($"Hello, {name}. Next year you will be {age + 1}.");

Name: Age: 
Hello, Ada. Next year you will be 37.

A variable is a named, typed storage slot. C# is statically typed: the type is fixed when the variable is declared and the compiler checks every assignment against it. You can write the type out (int count = 0;) or let the compiler infer it with var (var count = 0;). var is still static typing — the compiler works out int from the right-hand side and the variable is an int forever.

int count = 3;
var price = 19.99;          // inferred: double
var name = "Keyboard";      // inferred: string
bool inStock = true;

count = count + 2;          // variables can change
Console.WriteLine($"{count} x {name} at {price}, in stock: {inStock}");

const double TaxRate = 0.18; // fixed at compile time
Console.WriteLine($"Tax on one: {price * TaxRate:F2}");

Console.WriteLine(price.GetType());
Console.WriteLine(name.GetType());

5 x Keyboard at 19.99, in stock: True
Tax on one: 3.60
System.Double
System.String

• Names start with a letter or _, are case-sensitive, and use camelCase for locals and PascalCase for constants, types and methods.
• var needs an initial value (the compiler must see one to infer the type) and only works for local variables, not fields.
• const values are baked into the compiled code and must be known at compile time: numbers, strings, bool, char. For a value computed at runtime that must not change after setup, a class uses a readonly field (Module 05).

int total;
if (args.Length > 0) total = 10;
Console.WriteLine(total);

Program.cs(3,19): error CS0165: Use of unassigned local variable 'total'

int total = 0;
if (args.Length > 0) total = 10;
Console.WriteLine(total);

C# has a small set of built-in value types. A value type holds its data directly, so copying one copies the value. string is a reference type (the variable points at text stored elsewhere), but it behaves like a value in everyday code because strings cannot be changed — Module 03 covers why.

Console.WriteLine($"int:  {int.MinValue} .. {int.MaxValue}");
Console.WriteLine($"long max: {long.MaxValue}");

long population = 8_100_000_000;   // _ separates digits for reading
Console.WriteLine(population);

char grade = 'B';
Console.WriteLine(grade + 1);          // char is a number underneath
Console.WriteLine((char)(grade + 1));  // cast back to a char

string city = "Pune";
Console.WriteLine($"{city} has {city.Length} letters, first is {city[0]}");

int:  -2147483648 .. 2147483647
long max: 9223372036854775807
8100000000
67
C
Pune has 4 letters, first is P

double versus decimal: why money is decimal

double stores numbers in binary, and most decimal fractions — 0.1, 0.2 — have no exact binary form, just as 1/3 has no exact decimal form. The tiny error is fine for a physics simulation and wrong for an invoice. decimal stores base-10 digits, so 0.1 is exactly 0.1. It is slower and uses more memory, which matters only in tight numeric loops.

double d = 0.1 + 0.2;
decimal m = 0.1m + 0.2m;

Console.WriteLine(d);
Console.WriteLine(m);
Console.WriteLine(d == 0.3);
Console.WriteLine(m == 0.3m);

// adding one paisa a hundred thousand times
double dTotal = 0;
decimal mTotal = 0;
for (int i = 0; i < 100_000; i++) { dTotal += 0.01; mTotal += 0.01m; }
Console.WriteLine(dTotal);
Console.WriteLine(mTotal);

0.30000000000000004
0.3
False
True
999.9999999992356
1000.00

C# converts between numeric types implicitly only when no information can be lost: int to long, int to double. Going the other way you must write an explicit cast — (int)price — which tells the compiler "I know this may lose data". A cast from double to int truncates toward zero; it does not round.

int items = 7;
long big = items;          // implicit: int fits in long
double ratio = items;      // implicit: int fits in double
Console.WriteLine($"{big} {ratio}");

double price = 9.99;
int whole = (int)price;    // explicit: drops the fraction
Console.WriteLine(whole);
Console.WriteLine((int)-9.99);

Console.WriteLine(Math.Round(9.99));
Console.WriteLine(Math.Round(2.5));    // banker's rounding: to even
Console.WriteLine(Math.Round(2.5, MidpointRounding.AwayFromZero));

7 7
9
-9
10
2
3

double price = 9.99;
int whole = price;
Console.WriteLine(whole);

Program.cs(2,13): error CS0266: Cannot implicitly convert type 'double' to 'int'. An explicit conversion exists (are you missing a cast?)

double price = 9.99;
int whole = (int)price;               // 9
int rounded = (int)Math.Round(price); // 10
Console.WriteLine($"{whole} {rounded}");

Text to numbers

A cast cannot turn text into a number — (int)"42" does not compile. Use int.Parse when the text must be valid (it throws if not), int.TryParse when it might not be (user input, files, network data), and Convert.ToInt32 when converting between many types, including null (which it turns into 0). Every numeric type has the same trio: double.Parse, decimal.TryParse and so on.

using System.Globalization;

int a = int.Parse("42");
Console.WriteLine(a + 1);

foreach (string text in new[] { "17", "12a", "" })
{
    if (int.TryParse(text, out int n))
        Console.WriteLine($"'{text}' -> {n}");
    else
        Console.WriteLine($"'{text}' is not a number");
}

// Parse decimals with a fixed culture so "." always means the decimal point
decimal amount = decimal.Parse("1499.50", CultureInfo.InvariantCulture);
Console.WriteLine(amount * 2);

Console.WriteLine(Convert.ToInt32("99"));
Console.WriteLine(Convert.ToInt32(9.5));   // Convert rounds (to even)
Console.WriteLine(Convert.ToInt32(null as string));
Console.WriteLine(Convert.ToBoolean("true"));
Console.WriteLine(42.ToString() + "!");

43
'17' -> 17
'12a' is not a number
'' is not a number
2999.00
99
10
0
True
42!

int age = "42";
Console.WriteLine(age);

Program.cs(1,11): error CS0029: Cannot implicitly convert type 'string' to 'int'

int age = 42;
int parsed = int.Parse("42");
Console.WriteLine(age + parsed);

string input = "12a";
int n = int.Parse(input);
Console.WriteLine(n * 2);

Unhandled exception. System.FormatException: The input string '12a' was not in a correct format.
   at System.Number.ThrowFormatException[TChar](ReadOnlySpan`1 value)
   at System.Int32.Parse(String s)
   at Program.<Main>$(String[] args) in Program.cs:line 2

string input = "12a";
if (int.TryParse(input, out int n))
    Console.WriteLine(n * 2);
else
    Console.WriteLine($"'{input}' is not a whole number");

The arithmetic operators are + - * / %. The one that surprises everyone: when both operands are integers, / does integer division and throws the fraction away. Make either side a double or decimal to get a fractional result. % is the remainder, and its sign follows the left operand.

Console.WriteLine(7 / 2);        // int / int -> int
Console.WriteLine(7 / 2.0);      // int / double -> double
Console.WriteLine((double)7 / 2);
Console.WriteLine(-7 / 2);       // truncates toward zero

Console.WriteLine(7 % 3);
Console.WriteLine(-7 % 3);       // sign of the left side
Console.WriteLine(10 % 2 == 0 ? "even" : "odd");

int minutes = 135;
Console.WriteLine($"{minutes / 60}h {minutes % 60}m");

int score = 10;
score += 5;   // score = score + 5
score *= 2;   // score = score * 2
score -= 1;
score /= 3;
Console.WriteLine(score);

3
3.5
3.5
-3
1
-1
even
2h 15m
9

++ adds one and -- subtracts one. Written before the variable (++i) the expression gives the new value; written after (i++) it gives the old value and then increments. On a line of its own the two are identical — the difference only shows when the result is used inside a bigger expression.

An int has 32 bits. Add 1 to int.MaxValue and the result does not fit, so by default C# wraps around to int.MinValue without any error — the bits simply roll over, like a car odometer. This is fast, and it is almost never what you want. Wrap an expression in checked(...) (or a block in checked { }) and overflow throws an OverflowException instead.

int max = int.MaxValue;
int wrapped = max + 1;          // unchecked by default
Console.WriteLine(wrapped);

long safe = (long)max + 1;      // widen first, then add
Console.WriteLine(safe);

try
{
    int boom = checked(max + 1);
    Console.WriteLine(boom);
}
catch (OverflowException)
{
    Console.WriteLine("checked caught the overflow");
}

byte b = 250;
b += 10;                        // byte also wraps: 260 - 256
Console.WriteLine(b);

-2147483648
2147483648
checked caught the overflow
4

int max = int.MaxValue;
int next = checked(max + 1);
Console.WriteLine(next);

Unhandled exception. System.OverflowException: Arithmetic operation resulted in an overflow.
   at Program.<Main>$(String[] args) in Program.cs:line 2

int max = int.MaxValue;
long next = (long)max + 1;
Console.WriteLine(next);

Prefix a string with $ and anything inside { } is evaluated and inserted. After the expression you can add a format specifier after a colon ({price:F2}) and an alignment after a comma ({name,-10} pads to 10 characters, left-aligned; a positive number right-aligns). This replaces most string concatenation with +.

string item = "Mouse";
decimal price = 749.5m;
int qty = 3;
double ratio = 0.4567;

Console.WriteLine($"{qty} x {item} = {price * qty}");
Console.WriteLine($"Two decimals: {price:F2}");
Console.WriteLine($"Percent: {ratio:P1}");
Console.WriteLine($"Padded: [{qty:D4}]");
Console.WriteLine($"Hex: {255:X}");
Console.WriteLine($"Maths inside: {qty * 2 + 1}");
Console.WriteLine($"Braces: {{literal}}");

// alignment: a small table
Console.WriteLine($"{"Item",-8}|{"Price",8}");
Console.WriteLine($"{item,-8}|{price,8:F2}");
Console.WriteLine($"{"Cable",-8}|{99m,8:F2}");

3 x Mouse = 2248.5
Two decimals: 749.50
Percent: 45.7%
Padded: [0003]
Hex: FF
Maths inside: 7
Braces: {literal}
Item    |   Price
Mouse   |  749.50
Cable   |   99.00

An int always holds a number; it can never be null. Sometimes "no value" is a real answer — a customer who has not given their age, a sensor that has not reported. Add ? to any value type to get a nullable value type: int? holds either an int or null. HasValue tells you which, and the null-coalescing operator ?? supplies a fallback.

int? age = null;
Console.WriteLine(age.HasValue);
Console.WriteLine(age ?? -1);          // fallback when null

age = 36;
Console.WriteLine(age.HasValue);
Console.WriteLine(age.Value + 1);

int? missing = null;
Console.WriteLine(missing + 5 == null); // null in, null out

int? retries = null;
retries ??= 3;                          // assign only if null
Console.WriteLine(retries);

if (age is int years)                   // test and unwrap in one step
    Console.WriteLine($"{years} years");

False
-1
True
37
True
3
36 years

int stock = null;
Console.WriteLine(stock);

Program.cs(1,13): error CS0037: Cannot convert null to 'int' because it is a non-nullable value type

int? stock = null;
Console.WriteLine(stock ?? 0);

int? discount = null;
int value = discount.Value;
Console.WriteLine(value);

Program.cs(2,13): warning CS8629: Nullable value type may be null.
Unhandled exception. System.InvalidOperationException: Nullable object must have a value.
   at System.Nullable`1.get_Value()
   at Program.<Main>$(String[] args) in Program.cs:line 2

int? discount = null;
int value = discount ?? 0;
Console.WriteLine(value);

Top-level statements

Code written directly in Program.cs; the compiler wraps it in a hidden Main method.

var

Asks the compiler to infer a local variable's type from its initial value. Still statically typed.

Value type

A type whose variable holds the data itself (int, double, bool, char, structs); copying copies the value.

decimal

A 128-bit base-10 number type that represents values like 0.1 exactly; the standard for money.

Explicit cast

A conversion written as (int)x that may lose data; required when no implicit conversion exists.

TryParse

Converts text to a number and returns false instead of throwing when the text is invalid.

Integer division

Division of two integers, which discards the fractional part: 7 / 2 is 3.

checked

Makes integer overflow throw OverflowException instead of silently wrapping around.

Nullable value type

T? for a value type T, such as int?: holds a value or null.

Null-coalescing operator

a ?? b evaluates to a unless it is null, otherwise b.