Compilation

The C# compiler compiles source code, specified as a set of files with the .cs extension, into an assembly, which is the unit of packaging and deployment in .NET. An assembly can be either an application or a library, the difference being that an application has an entry point (“Main” method), whereas a library does not. The purpose of a library is to be called upon (referenced) by an application or other libraries. The .NET Core runtime (and the .NET Framework) comprise a set of libraries.

To invoke the compiler, you can either use an integrated development environment (IDE) such as Visual Studio or Visual Studio Code, or call it manually from the command line. To manually compile a console application with .NET Core, first download the .NET Core SDK, and then create a new project, as follows:

dotnet new console -o MyFirstProgram
cd MyFirstProgram

This creates a folder called MyFirstProgram, which contains a C# file called Program.cs, which you can then edit. To invoke the compiler, call dotnet build (or dotnet run, which will compile and then run the program). The output will be written to a subdirectory under bindebug, which will include MyFirstProgram.dll (the output assembly) as well as MyFirstProgram.exe (which runs the compiled program directly).

Identifiers and Keywords

Identifiers are names that programmers choose for their classes, methods, variables, and so on. These are the identifiers in our example program, in the order in which they appear:

System   Test   Main   x   Console   WriteLine

An identifier must be a whole word, essentially made up of Unicode characters starting with a letter or underscore. C# identifiers are case-sensitive. By convention, parameters, local variables, and private fields should be in camel case (e.g., myVariable), and all other identifiers should be in Pascal case (e.g., MyMethod).

Keywords are names that mean something special to the compiler. These are the keywords in our example program:

using   class   static   void   int

Most keywords are reserved, which means that you can’t use them as identifiers. Here is the full list of C# reserved keywords:

class class  {...}      // Illegal
class @class {...}      // Legal

Literals, Punctuators, and Operators

Literals are primitive pieces of data lexically embedded into the program. The literals in our example program are 12 and 30. Punctuators help demarcate the structure of the program. The punctuators in our program are {, }, and ;.

The braces group multiple statements into a statement block. The semicolon terminates a (nonblock) statement. Statements can wrap multiple lines:

Console.WriteLine
  (1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10);

An operator transforms and combines expressions. Most operators in C# are denoted with a symbol, such as the multiplication operator, *. Here are the operators in our program:

. ()   *   =

A period denotes a member of something (or a decimal point with numeric literals). The  parentheses, in our example, appear where we declare or call a method; empty parentheses mean that the method accepts no arguments. The equals sign performs assignment (the double equals, ==, performs equality comparison).

Comments

C# offers two different styles of source code documentation: single-line comments and multiline comments. A single-line comment begins with a double forward slash and continues until the end of the line. For example:

int x = 3;   // Comment about assigning 3 to x

A multiline comment begins with /* and ends with */. For example:

int x = 3;   /* This is a comment that
                spans two lines */

Comments can embed XML documentation tags (see “XML Documentation”).

Predefined Type Examples

Predefined types (also called built-in types) are types that are specially supported by the compiler. The int type is a predefined type for representing the set of integers that fit into 32 bits of memory, from −2³¹ to 2³¹−1. We can perform functions such as arithmetic with instances of the int type as follows:

int x = 12 * 30;

Another predefined C# type is string. The string type represents a sequence of characters, such as “.NET” or “http://oreilly.com”. We can work with strings by calling functions on them, as follows:

string message = "Hello world";
string upperMessage = message.ToUpper();
Console.WriteLine (upperMessage);      // HELLO WORLD
 
int x = 2015;
message = message + x.ToString();
Console.WriteLine (message);         // Hello world2015

The predefined bool type has exactly two possible values: true and false. The bool type is commonly used to conditionally branch execution flow with an if statement. For example:

bool simpleVar = false;
if (simpleVar)
  Console.WriteLine ("This will not print");
 
int x = 5000;
bool lessThanAMile = x < 5280;
if (lessThanAMile)
  Console.WriteLine ("This will print");

Custom Type Examples

Just as we can build complex functions from simple functions, we can build complex types from primitive types. In this example, we will define a custom type named UnitConverter—a class that serves as a blueprint for unit conversions:

using System;

public class UnitConverter
{                       
  int ratio;                             // Field

  public UnitConverter (int unitRatio)   // Constructor
  {
    ratio = unitRatio;
  }

  public int Convert (int unit)          // Method
  {
    return unit * ratio;
  }
}                                           

class Test 
{
  static void Main()
  {
    UnitConverter feetToInches = new UnitConverter(12);
    UnitConverter milesToFeet = new UnitConverter(5280);

    Console.Write (feetToInches.Convert(30));   // 360
    Console.Write (feetToInches.Convert(100));  // 1200
    Console.Write (feetToInches.Convert
                    (milesToFeet.Convert(1)));  // 63360
  }
}

public UnitConverter (int unitRatio)   // Constructor
{
  ratio = unitRatio; 
}

public class Panda
{
  public string Name;           // Instance field
  public static int Population; // Static field

  public Panda (string n)       // Constructor
  {
    Name = n;                   // Assign instance field
    Population = Population+1;  // Increment static field
  }
}

Panda p1 = new Panda ("Pan Dee");
Panda p2 = new Panda ("Pan Dah");

Console.WriteLine (p1.Name);      // Pan Dee
Console.WriteLine (p2.Name);      // Pan Dah

Console.WriteLine (Panda.Population);   // 2

Conversions

C# can convert between instances of compatible types. A conversion always creates a new value from an existing one. Conversions can be either implicit or explicit: implicit conversions happen automatically, whereas explicit conversions require a cast. In the following example, we implicitly convert an int to a long type (which has twice the bit-capacity of an int) and explicitly cast an int to a short type (which has half the bit-capacity of an int):

int x = 12345;       // int is a 32-bit integer
long y = x;          // Implicit conversion to 64-bit int
short z = (short)x;  // Explicit conversion to 16-bit int

In general, implicit conversions are allowed when the compiler can guarantee that they will always succeed without loss of information. Otherwise, you must perform an explicit cast to convert between compatible types.

Value Types versus Reference Types

C# types can be divided into value types and reference types.

Value types comprise most built-in types (specifically, all numeric types, the char type, and the bool type) as well as custom struct and enum types. Reference types comprise all class, array, delegate, and interface types.

The fundamental difference between value types and reference types is how they are handled in memory.

Value types

The content of a value type variable or constant is simply a value. For example, the content of the built-in value type int is 32 bits of data.

You can define a custom value type with the struct keyword (see Figure 1):

public struct Point { public int X, Y; }

Figure 1. A value type instance in memory

The assignment of a value type instance always copies the instance. For example:

Point p1 = new Point();
p1.X = 7;

Point p2 = p1;             // Assignment causes copy

Console.WriteLine (p1.X);  // 7
Console.WriteLine (p2.X);  // 7

p1.X = 9;                  // Change p1.X
Console.WriteLine (p1.X);  // 9
Console.WriteLine (p2.X);  // 7

Figure 2 shows that p1 and p2 have independent storage.

Figure 2. Assignment copies a value type instance

Reference types

A reference type is more complex than a value type, having two parts: an object and the reference to that object. The content of a reference type variable or constant is a reference to an object that contains the value. Here is the Point type from our previous example rewritten as a class (see Figure 3):

public class Point { public int X, Y; }

Figure 3. A reference type instance in memory

Assigning a reference type variable copies the reference, not the object instance. This allows multiple variables to refer to the same object—something that’s not ordinarily possible with value types. If we repeat the previous example, but with Point now a class, an operation via p1 affects p2:

Point p1 = new Point();
p1.X = 7;

Point p2 = p1;             // Copies p1 reference

Console.WriteLine (p1.X);  // 7
Console.WriteLine (p2.X);  // 7

p1.X = 9;                  // Change p1.X
Console.WriteLine (p1.X);  // 9
Console.WriteLine (p2.X);  // 9

Figure 4 shows that p1 and p2 are two references that point to the same object.

Figure 4. Assignment copies a reference

Point p = null;
Console.WriteLine (p == null);   // True

Console.WriteLine (p.X);   // NullReferenceException

struct Point {...}
...
Point p = null;  // Compile-time error
int x = null;    // Compile-time error

Predefined Type Taxonomy

The predefined types in C# are:

Value types

• Numeric:

  • Signed integer (sbyte, short, int, long)

  • Unsigned integer (byte, ushort, uint, ulong)

  • Real number (float, double, decimal)

• Logical (bool)

• Character (char)

Reference types

• String (string)

• Object (object)

Predefined types in C# alias .NET Core types in the System namespace. There is only a syntactic difference between these two statements:

int i = 5;
System.Int32 i = 5;

The set of predefined value types excluding decimal are known as primitive types in the Common Language Runtime (CLR). Primitive types are so called because they are supported directly via instructions in compiled code, which usually translates to direct support on the underlying processor.

Numeric Literals

Integral-typed literals can use decimal or hexadecimal notation; hexadecimal is denoted with the 0x prefix (e.g., 0x7f is equivalent to 127). From C# 7, you can also use the 0b prefix for binary literals. Real literals can use decimal or exponential notation such as 1E06.

From C# 7, underscores may be inserted within (or before) a numeric literal to improve readability (e.g., 1_000_000).

Console.Write (       1.0.GetType());  // Double (double)
Console.Write (      1E06.GetType());  // Double (double)
Console.Write (         1.GetType());  // Int32  (int)
Console.Write (0xF0000000.GetType());  // UInt32 (uint)
Console.Write (0x100000000.GetType()); // Int64  (long)

decimal d = 3.5M;   // M = decimal (case-insensitive)

long i = 5;     // Implicit conversion from int to long

float f = 4.5F;       // Won't compile without suffix
decimal d = -1.23M;   // Won't compile without suffix

Numeric Conversions

int x = 12345;       // int is a 32-bit integral type
long y = x;          // Implicit conversion to 64-bit int
short z = (short)x;  // Explicit conversion to 16-bit int

int i1 = 100000001;
float f = i1;      // Magnitude preserved, precision lost
int i2 = (int)f;   // 100000000

Arithmetic Operators

The arithmetic operators (+, -, *, /, %) are defined for all numeric types except the 8- and 16-bit integral types. The % operator evaluates the remainder after division.

Increment and Decrement Operators

The increment and decrement operators (++, --, respectively) increment and decrement numeric types by 1. The operator can either precede or follow the variable, depending on whether you want the variable to be updated before or after the expression is evaluated. For example:

int x = 0;
Console.WriteLine (x++);   // Outputs 0; x is now 1
Console.WriteLine (++x);   // Outputs 2; x is now 2
Console.WriteLine (--x);   // Outputs 1; x is now 1

Specialized Integral Operations

int a = int.MinValue; a--;
Console.WriteLine (a == int.MaxValue); // True

int a = 1000000, b = 1000000;

int c = checked (a * b);   // Checks just the expression

checked                    // Checks all expressions
{                          // in statement block.
   c = a * b;
   ...
}

8- and 16-Bit Integral Types

The 8- and 16-bit integral types are byte, sbyte, short, and ushort. These types lack their own arithmetic operators, so C# implicitly converts them to larger types as required. This can cause a compilation error when trying to assign the result back to a small integral type:

short x = 1, y = 1;
short z = x + y;          // Compile-time error

In this case, x and y are implicitly converted to int so that the addition can be performed. This means that the result is also an int, which cannot be implicitly cast back to a short (because it could cause loss of data). To make this compile, we must add an explicit cast:

short z = (short) (x + y);   // OK

Special Float and Double Values

Unlike integral types, floating-point types have values that certain operations treat specially. These special values are NaN (Not a Number), +∞, −∞, and −0. The float and double classes have constants for NaN, +∞, and −∞ (as well as other values including MaxValue, MinValue, and Epsilon). For example:

Console.Write (double.NegativeInfinity);   // -Infinity

Dividing a nonzero number by zero results in an infinite value:

Console.WriteLine ( 1.0 /  0.0);   //  Infinity
Console.WriteLine (−1.0 /  0.0);   // -Infinity
Console.WriteLine ( 1.0 / −0.0);   // -Infinity
Console.WriteLine (−1.0 / −0.0);   //  Infinity

Dividing zero by zero, or subtracting infinity from infinity, results in a NaN:

Console.Write ( 0.0 / 0.0);                 //  NaN
Console.Write ((1.0 / 0.0) − (1.0 / 0.0));  //  NaN

When you use ==, a NaN value is never equal to another value, even another NaN value. To test whether a value is NaN, you must use the float.IsNaN or double.IsNaN method:

Console.WriteLine (0.0 / 0.0 == double.NaN);    // False
Console.WriteLine (double.IsNaN (0.0 / 0.0));   // True

When you use object.Equals, however, two NaN values are equal:

bool isTrue = object.Equals (0.0/0.0, double.NaN);

double versus decimal

double is useful for scientific computations (such as computing spatial coordinates). decimal is useful for financial computations and values that are “man-made” rather than the result of real-world measurements. Here’s a summary of the differences:

Real Number Rounding Errors

float and double internally represent numbers in base 2. For this reason, most literals with a fractional component (which are in base 10) will not be represented precisely:

float tenth = 0.1f;                     // Not quite 0.1
float one   = 1f;
Console.WriteLine (one - tenth * 10f);  // -1.490116E-08

This is why float and double are bad for financial calculations. In contrast, decimal works in base 10 and so can precisely represent fractional numbers such as 0.1 (whose base-10 representation is nonrecurring).

Equality and Comparison Operators

== and != test for equality and inequality, respectively, of any type, and always return a bool value. Value types typically have a very simple notion of equality:

int x = 1, y = 2, z = 1;
Console.WriteLine (x == y);      // False
Console.WriteLine (x == z);      // True

For reference types, equality, by default, is based on reference, as opposed to the actual value of the underlying object. Therefore, two instances of an object with identical data are not considered equal unless the == operator for that type is specially overloaded to that effect (see “The object Type” and “Operator Overloading”).

The equality and comparison operators, ==, !=, <, >, >=, and <=, work for all numeric types, but should be used with caution with real numbers (see “Real Number Rounding Errors” in the previous section). The comparison operators also work on enum type members, by comparing their underlying integral values.

Conditional Operators

The && and || operators test for and and or conditions, respectively. They are frequently used in conjunction with the ! operator, which expresses not. In the following example, the UseUmbrella method returns true if it’s rainy or sunny (to protect us from the rain or the sun), as long as it’s not also windy (because umbrellas are useless in the wind):

static bool UseUmbrella (bool rainy, bool sunny,
                         bool windy)
{
  return !windy && (rainy || sunny);
}

The && and || operators short-circuit evaluation when possible. In the preceding example, if it is windy, the expression (rainy || sunny) is not even evaluated. Short-circuiting is essential in allowing expressions such as the following to run without throwing a NullReferenceException:

if (sb != null && sb.Length > 0) ...

The & and | operators also test for and and or conditions:

return !windy & (rainy | sunny);

The difference is that they do not short-circuit. For this reason, they are rarely used in place of conditional operators.

The ternary conditional operator (simply called the conditional operator) has the form q ? a : b, where if condition q is true, a is evaluated, else b is evaluated. For example:

static int Max (int a, int b)
{
  return (a > b) ? a : b;
}

The conditional operator is particularly useful in LINQ queries.

String Type

C#’s string type (aliasing the System.String type) represents an immutable (unmodifiable) sequence of Unicode characters. A string literal is specified within double quotes:

string a = "Heat";

string a = "test", b = "test";
Console.Write (a == b);  // True

The escape sequences that are valid for char literals also work within strings:

string a = "Here's a tab:	";

The cost of this is that whenever you need a literal backslash, you must write it twice:

string a1 = "\\server\fileshare\helloworld.cs";

To avoid this problem, C# allows verbatim string literals. A verbatim string literal is prefixed with @ and does not support escape sequences. The following verbatim string is identical to the preceding one:

string a2 = @"\serverfilesharehelloworld.cs";

A verbatim string literal can also span multiple lines. You can include the double-quote character in a verbatim literal by writing it twice.

string s = "a" + "b";

string s = "a" + 5;  // a5

int x = 4;
Console.Write ($"A square has {x} sides");
// Prints: A square has 4 sides

string s = $"15 in hex is {15:X2}";
// Evaluates to "15 in hex is 0F"

int x = 2;
string s = $@"this spans {
x} lines";

Console.Write ("Boston".CompareTo ("Austin"));   // 1
Console.Write ("Boston".CompareTo ("Boston"));   // 0
Console.Write ("Boston".CompareTo ("Chicago"));  // -1

Console.Write ("word"[2]);   // r

Default Element Initialization

Creating an array always preinitializes the elements with default values. The default value for a type is the result of a bitwise zeroing of memory. For example, consider creating an array of integers. Because int is a value type, this allocates 1,000 integers in one contiguous block of memory. The default value for each element will be 0:

int[] a = new int[1000];
Console.Write (a[123]);            // 0

With reference type elements, the default value is null.

An array itself is always a reference type object, regardless of element type. For instance, the following is legal:

int[] a = null;

Indices and Ranges (C# 8)

C# 8 introduces indices and ranges to simplify working with elements or portions of an array.

char[] vowels = new char[] {'a','e','i','o','u'};
char lastElement  = vowels[^1];   // 'u'
char secondToLast = vowels[^2];   // 'o'

Index first = 0;
Index last = ^1;
char firstElement = vowels [first];   // 'a'
char lastElement = vowels [last];     // 'u'

char[] firstTwo =  vowels [..2];    // 'a', 'e'
char[] lastThree = vowels [2..];    // 'i', 'o', 'u'
char[] middleOne = vowels [2..3]    // 'i'

char[] lastTwo = vowels [^2..^0];    // 'o', 'u'

Range firstTwoRange = 0..2;
char[] firstTwo = vowels [firstTwoRange];   // 'a', 'e'

Multidimensional Arrays

Multidimensional arrays come in two varieties: rectangular and jagged. Rectangular arrays represent an n-dimensional block of memory, and jagged arrays are arrays of arrays.

int[,] matrix = new int [3, 3];

for (int i = 0; i < matrix.GetLength(0); i++)
  for (int j = 0; j < matrix.GetLength(1); j++)
    matrix [i, j] = i * 3 + j;

int[,] matrix = new int[,]
{
  {0,1,2},
  {3,4,5},
  {6,7,8}
};

int[][] matrix = new int[3][];

for (int i = 0; i < matrix.Length; i++)
{
  matrix[i] = new int [3];       // Create inner array
  for (int j = 0; j < matrix[i].Length; j++)
    matrix[i][j] = i * 3 + j;
}

int[][] matrix = new int[][]
{
  new int[] {0,1,2},
  new int[] {3,4,5},
  new int[] {6,7,8,9}
};

Simplified Array Initialization Expressions

We’ve already seen how to simplify array initialization expressions by omitting the new keyword and type declaration:

char[] vowels = new char[] {'a','e','i','o','u'};
char[] vowels =            {'a','e','i','o','u'};

Another approach is to omit the type name after the new keyword, and have the compiler infer the array type. This is a useful shortcut when you’re passing arrays as arguments. For example, consider the following method:

void Foo (char[] data) { ... }

We can call this method with an array that we create on the fly, as follows:

Foo ( new char[] {'a','e','i','o','u'} );   // Longhand
Foo ( new[]      {'a','e','i','o','u'} );   // Shortcut

This shortcut is essential in creating arrays of anonymous types, as you’ll see later.

The Stack and the Heap

The stack and the heap are the places where variables reside. Each has very different lifetime semantics.

static int Factorial (int x)
{
  if (x == 0) return 1;
  return x * Factorial (x-1);
}

Definite Assignment

C# enforces a definite assignment policy. In practice, this means that outside of an unsafe context, it’s impossible to access uninitialized memory. Definite assignment has three implications:

• Local variables must be assigned a value before they can be read.

• Function arguments must be supplied when a method is called (unless marked optional—see “Optional parameters”).

• All other variables (such as fields and array elements) are automatically initialized by the runtime.

For example, the following code results in a compile-time error:

static void Main()
{
  int x;
  Console.WriteLine (x);        // Compile-time error
}

However, if x were instead a field of the containing class, this would be legal and would print 0.

Default Values

All type instances have a default value. The default value for the predefined types is the result of a bitwise zeroing of memory, and is null for reference types, 0 for numeric and enum types, '' for the char type, and false for the bool type.

You can obtain the default value for any type by using the default keyword (this is particularly useful with generics, as you’ll see later). The default value in a custom value type (i.e., struct) is the same as the default value for each field defined by the custom type.

Parameters

A method can have a sequence of parameters. Parameters define the set of arguments that must be provided for that method. In this example, the method Foo has a single parameter named p, of type int:

static void Foo (int p)   // p is a parameter
{
  ...
}
static void Main() { Foo (8); }   // 8 is an argument

You can control how parameters are passed with the ref, out, and in modifiers:

static void Foo (int p)
{
  p = p + 1;                // Increment p by 1
  Console.WriteLine (p);    // Write p to screen
}
static void Main()
{
  int x = 8;
  Foo (x);                  // Make a copy of x
  Console.WriteLine (x);    // x will still be 8
}

static void Foo (StringBuilder fooSB)
{
  fooSB.Append ("test");
  fooSB = null;
}
static void Main()
{
  StringBuilder sb = new StringBuilder();
  Foo (sb);
  Console.WriteLine (sb.ToString());    // test
}

static void Foo (ref int p)
{
  p = p + 1;
  Console.WriteLine (p);
}
static void Main()
{
  int x = 8;
  Foo (ref x);             // Pass x by reference
  Console.WriteLine (x);   // x is now 9
}

int.TryParse ("123", out int x);
Console.WriteLine (x);

int x;
int.TryParse ("123", out x);
Console.WriteLine (x);

SomeBigMethod (out _, out _, out int x, out _, out _);
Console.WriteLine (x);

static int Sum (params int[] ints)
{
  int sum = 0;
  for (int i = 0; i < ints.Length; i++) sum += ints[i];
  return sum;
}

Console.WriteLine (Sum (1, 2, 3, 4));    // 10

Console.WriteLine (Sum (new int[] { 1, 2, 3, 4 } ));

void Foo (int x = 23) { Console.WriteLine (x); }

Foo();     // 23

Foo (23);

void Foo (int x = 0, int y = 0)
{
  Console.WriteLine (x + ", " + y);
}
void Test()
{
  Foo(1);    // 1, 0
}

void Foo (int x, int y)
{
  Console.WriteLine (x + ", " + y);
}
void Test()
{
  Foo (x:1, y:2);  // 1, 2
}

Foo (x:1, y:2);
Foo (y:2, x:1);

Foo (1, y:2);

void Bar (int a=0, int b=0, int c=0, int d=0) { ... }

Bar (d:3);

var—Implicitly Typed Local Variables

It is often the case that you declare and initialize a variable in one step. If the compiler is able to infer the type from the initialization expression, you can use the word var in place of the type declaration. For example:

var x = "hello";
var y = new System.Text.StringBuilder();
var z = (float)Math.PI;

This is precisely equivalent to the following:

string x = "hello";
System.Text.StringBuilder y = 
  new System.Text.StringBuilder();
float z = (float)Math.PI;

Because of this direct equivalence, implicitly typed variables are statically typed. For example, the following generates a compile-time error:

var x = 5;
x = "hello";    // Compile-time error; x is of type int

In the section “Anonymous Types”, we describe a scenario in which the use of var is mandatory.

Assignment Expressions

An assignment expression uses the = operator to assign the result of another expression to a variable. For example:

x = x * 5

An assignment expression is not a void expression. It actually carries the assignment value, and so can be incorporated into another expression. In the following example, the expression assigns 2 to x and 10 to y:

y = 5 * (x = 2)

This style of expression can be used to initialize multiple values:

a = b = c = d = 0

The compound assignment operators are syntactic shortcuts that combine assignment with another operator. For example:

x *= 2    // equivalent to x = x * 2
x <<= 1   // equivalent to x = x << 1

(A subtle exception to this rule is with events, which we describe later: the += and -= operators here are treated specially and map to the event’s add and remove accessors, respectively.)

Operator Precedence and Associativity

When an expression contains multiple operators, precedence and associativity determine the order of their evaluation. Operators with higher precedence execute before operators of lower precedence. If the operators have the same precedence, the operator’s associativity determines the order of evaluation.

Operator Table

The following table lists C#’s operators in order of precedence. Operators listed under the same subheading have the same precedence. We explain user-overloadable operators in “Operator Overloading”.

Null-Coalescing Operator

The ?? operator is the null-coalescing operator. It says, “If the operand to the left is non-null, give it to me; otherwise, give me another value.” For example:

string s1 = null;
string s2 = s1 ?? "nothing"; // s2 evaluates to "nothing"

If the left-hand expression is non-null, the righthand expression is never evaluated. The null-coalescing operator also works with nullable value types (see “Nullable (Value) Types”).

Null-Conditional Operator

The ?. operator is the null-conditional or “Elvis” operator, and was introduced in C# 6. It allows you to call methods and access members just like the standard dot operator, except that if the operand on the left is null, the expression evaluates to null instead of throwing a NullReferenceException:

System.Text.StringBuilder sb = null;
string s = sb?.ToString();   // No error; s is null

The last line is equivalent to this:

string s = (sb == null ? null : sb.ToString());

Upon encountering a null, the Elvis operator short-circuits the remainder of the expression. In the following example, s evaluates to null, even with a standard dot operator between ToString() and ToUpper():

System.Text.StringBuilder sb = null;
string s = sb?.ToString().ToUpper();   // No error

Repeated use of Elvis is necessary only if the operand immediately to its left might be null. The following expression is robust to both x being null and x.y being null:

x?.y?.z

and is equivalent to the following (except that x.y is evaluated only once):

x == null ? null 
          : (x.y == null ? null : x.y.z)

The final expression must be capable of accepting a null. The following is illegal because int cannot accept a null:

System.Text.StringBuilder sb = null;
int length = sb?.ToString().Length;   // Illegal

We can fix this with the use of nullable value types (see “Nullable (Value) Types”):

int? length = sb?.ToString().Length;   // OK : int? can be null

You can also use the null-conditional operator to call a void method:

someObject?.SomeVoidMethod();

If someObject is null, this becomes a “no-operation” rather than throwing a NullReferenceException.

The null-conditional operator can be used with the commonly used type members that we describe in “Classes”, including methods, fields, properties, and indexers. It also combines well with the null-coalescing operator:

System.Text.StringBuilder sb = null;
string s = sb?.ToString() ?? "nothing";   // s evaluates to "nothing"

Null-Coalescing Assignment (C# 8)

The ??= operator assigns a variable only if it’s not null. Instead of this:

if (s != null) s = "Hello, world";

you can now write this:

s ??= "Hello, world";

Declaration Statements

A declaration statement declares a new variable, optionally initializing the variable with an expression. A declaration statement ends in a semicolon. You can declare multiple variables of the same type in a comma-separated list. For example:

bool rich = true, famous = false;

A constant declaration is like a variable declaration, except that it cannot be changed after it has been declared, and the initialization must occur with the declaration (more on this in “Constants”):

const double c = 2.99792458E08;

Expression Statements

Expression statements are expressions that are also valid statements. In practice, this means expressions that “do” something; in other words:

• Instantiate an object

• Call a method

Expressions that do none of these are not valid statements:

string s = "foo";
s.Length;          // Illegal statement: does nothing!

When you call a constructor or a method that returns a value, you’re not obliged to use the result. However, unless the constructor or method changes state, the statement is useless:

new StringBuilder();     // Legal, but useless
x.Equals (y);            // Legal, but useless

Selection Statements

Selection statements conditionally control the flow of program execution.

if (5 < 2 * 3)
  Console.WriteLine ("true");       // true

if (5 < 2 * 3)
{
  Console.WriteLine ("true");       // true
  Console.WriteLine ("...")
}

if (2 + 2 == 5)
   Console.WriteLine ("Does not compute");
else
   Console.WriteLine ("False");        // False

if (2 + 2 == 5)
  Console.WriteLine ("Does not compute");
else
  if (2 + 2 == 4)
    Console.WriteLine ("Computes");    // Computes

if (true)
  if (false)
    Console.WriteLine();
  else
    Console.WriteLine ("executes");

if (true)
{
  if (false)
    Console.WriteLine();
  else
    Console.WriteLine ("executes");
}

if (true)
{
  if (false)
    Console.WriteLine();
}
else
  Console.WriteLine ("does not execute");

static void TellMeWhatICanDo (int age)
{
  if (age >= 35)
    Console.WriteLine ("You can be president!");
  else if (age >= 21)
    Console.WriteLine ("You can drink!");
  else if (age >= 18)
    Console.WriteLine ("You can vote!");
  else
    Console.WriteLine ("You can wait!");
}

static void ShowCard (int cardNumber)
{
  switch (cardNumber)
  {
    case 13:
      Console.WriteLine ("King");
      break;
    case 12:
      Console.WriteLine ("Queen");
      break;
    case 11:
      Console.WriteLine ("Jack");
      break;
    default:    // Any other cardNumber
      Console.WriteLine (cardNumber);
      break;
  }
}

switch (cardNumber)
{
  case 13:
  case 12:
  case 11:
    Console.WriteLine ("Face card");
    break;
  default:
    Console.WriteLine ("Plain card");
    break;
}

static void TellMeTheType (object x)
{
  switch (x)
  {
    case int i:
      Console.WriteLine ("It's an int!");
      break;
    case string s:
      Console.WriteLine (s.Length);      // We can use s
      break;
    case bool b when b == true:   // Fires when b is true
      Console.WriteLine ("True");
      break;
    case null:    // You can also switch on null
      Console.WriteLine ("null");
      break;
  }
}

switch (x)
{
  case float f when f > 1000:
  case double d when d > 1000:
  case decimal m when m > 1000:
    Console.WriteLine ("f, d and m are out of scope");
    break;

string cardName = cardNumber switch
{
  13 => "King",
  12 => "Queen",
  11 => "Jack",
  _ => "Pip card"   // equivalent to 'default'
};

int cardNumber = 12; string suite = "spades";
string cardName = (cardNumber, suite) switch
{
  (13, "spades") => "King of spades",
  (13, "clubs") => "King of clubs",
  ...
};

Iteration Statements

C# enables a sequence of statements to execute repeatedly with the while, do-while, for, and foreach statements.

int i = 0;
while (i < 3)
{                         // Braces here are optional
  Console.Write (i++);
}

int i = 0;
do
{
  Console.WriteLine (i++);
}
while (i < 3);

for (init-clause; condition-clause; iteration-clause)
   statement-or-statement-block

for (int i = 0; i < 3; i++)
  Console.WriteLine (i);

for (int i = 0, prevFib = 1, curFib = 1; i < 10; i++)
{
  Console.WriteLine (prevFib);
  int newFib = prevFib + curFib;
  prevFib = curFib; curFib = newFib;
}

for (;;) Console.WriteLine ("interrupt me");

foreach (char c in "beer")
  Console.WriteLine (c + " ");   // b e e r

Jump Statements

The C# jump statements are break, continue, goto, return, and throw. We cover the throw keyword in “try Statements and Exceptions”.

int x = 0;
while (true)
{
  if (x++ > 5) break;      // break from the loop
}
// execution continues here after break
...

for (int i = 0; i < 10; i++)
{
  if ((i % 2) == 0) continue;
  Console.Write (i + " ");      // 1 3 5 7 9
}

int i = 1;
startLoop:
if (i <= 5)
{
  Console.Write (i + " ");   // 1 2 3 4 5
  i++;
  goto startLoop;
}

static decimal AsPercentage (decimal d)
{
  decimal p = d * 100m;
  return p;     // Return to calling method with value
}

The using Directive

The using directive imports a namespace and is a convenient way to refer to types without their fully qualified names. For example, you can refer to Class1 in the preceding example as follows:

using Outer.Middle.Inner;

class Test    // Test is in the global namespace
{
  static void Main()
  {
    Class1 c;    // Don't need fully qualified name
    ...
  }
}

A using directive can be nested within a namespace itself to limit the scope of the directive.

using static

From C# 6, you can import not just a namespace, but a specific type, with the using static directive. All static members of that type can then be used without being qualified with the type name. In the following example, we call the Console class’s static WriteLine method:

using static System.Console;

class Test
{
  static void Main() { WriteLine ("Hello"); }
}

The using static directive imports all accessible static members of the type, including fields, properties, and nested types. You can also apply this directive to enum types (see “Enums”), in which case their members are imported. Should an ambiguity arise between multiple static imports, the C# compiler is unable to infer the correct type from the context, and will generate an error.

Rules Within a Namespace

namespace Outer
{
  class Class1 {}

  namespace Inner
  {
    class Class2 : Class1 {}
  }
}

namespace MyTradingCompany
{
  namespace Common
  {
    class ReportBase {}
  }
  namespace ManagementReporting
  {
    class SalesReport : Common.ReportBase {}
  }
}

namespace Outer.Middle.Inner { class Class1 {} }
namespace Outer.Middle.Inner { class Class2 {} }

global::System.Text.StringBuilder sb;

Aliasing Types and Namespaces

Importing a namespace can result in type-name collision. Rather than importing the whole namespace, you can import just the specific types you need, giving each type an alias. For example:

using PropertyInfo2 = System.Reflection.PropertyInfo;
class Program { PropertyInfo2 p; }

An entire namespace can be aliased, as follows:

using R = System.Reflection;
class Program { R.PropertyInfo p; }

Fields

A field is a variable that is a member of a class or struct. For example:

class Octopus
{
  string name;
  public int Age = 10;
}

A field can have the readonly modifier to prevent it from being modified after construction. A read-only field can be assigned only in its declaration or within the enclosing type’s constructor.

Field initialization is optional. An uninitialized field has a default value (0, , null, false). Field initializers run before constructors in the order in which they appear.

For convenience, you can declare multiple fields of the same type in a comma-separated list. This is a convenient way for all the fields to share the same attributes and field modifiers. For example:

static readonly int legs = 8, eyes = 2;

Constants

A constant is evaluated statically at compile time and the compiler literally substitutes its value whenever used (rather like a macro in C++). A constant can be any of the built-in numeric types: bool, char, string, or an enum type.

A constant is declared with the const keyword and must be initialized with a value. For example:

public class Test
{
  public const string Message = "Hello World";
}

A constant is much more restrictive than a static readonly field—both in the types you can use and in field initialization semantics. A constant also differs from a static readonly field in that the evaluation of the constant occurs at compile time. Constants can also be declared local to a method:

static void Main()
{
  const double twoPI = 2 * System.Math.PI;
  ...
}

Methods

A method performs an action in a series of statements. A method can receive input data from the caller by specifying parameters, and output data back to the caller by specifying a return type. A method can specify a void return type, indicating that it doesn’t return any value to its caller. A method can also output data back to the caller via ref and out parameters.

A method’s signature must be unique within the type. A method’s signature comprises its name and parameter types in order (but not the parameter names, nor the return type).

int Foo (int x) { return x * 2; }

int Foo (int x) => x * 2;

void Foo (int x) => Console.WriteLine (x);

void Foo (int x);
void Foo (double x);
void Foo (int x, float y);
void Foo (float x, int y);

void WriteCubes()
{
  Console.WriteLine (Cube (3));

  int Cube (int value) => value * value * value;
}

Instance Constructors

Constructors run initialization code on a class or struct. A constructor is defined like a method, except that the method name and return type are reduced to the name of the enclosing type:

public class Panda
{
  string name;              // Define field
  public Panda (string n)   // Define constructor
  {
    name = n;               // Initialization code
  }
}
...
Panda p = new Panda ("Petey");   // Call constructor

From C# 7, single-statement constructors can be written as expression-bodied members:

public Panda (string n) => name = n;

A class or struct can overload constructors. One overload can call another, using the this keyword:

public class Wine
{
  public Wine (decimal price) {...}

  public Wine (decimal price, int year) 
               : this (price) {...}
}

When one constructor calls another, the called constructor executes first.

You can pass an expression into another constructor as follows:

public Wine (decimal price, DateTime year)
             : this (price, year.Year) {...}

The expression itself cannot make use of the this reference, for example, to call an instance method. It can, however, call static methods.

Deconstructors

Whereas a constructor typically takes a set of values (as parameters) and assigns them to fields, a deconstructor (C# 7+) does the reverse and assigns fields back to a set of variables. A deconstruction method must be called Deconstruct and have one or more out parameters:

class Rectangle
{
  public readonly float Width, Height;
  
  public Rectangle (float width, float height)
  {
    Width = width; Height = height;
  }
  
  public void Deconstruct (out float width,
                           out float height)
  {
    width = Width; height = Height;
  }
}

To call the deconstructor, you use the following special syntax:

var rect = new Rectangle (3, 4);
(float width, float height) = rect;
Console.WriteLine (width + " " + height);    // 3 4

The second line is the deconstructing call. It creates two local variables and then calls the Deconstruct method. Our deconstructing call is equivalent to the following:

rect.Deconstruct (out var width, out var height);

Deconstructing calls allow implicit typing, so we could shorten our call to:

(var width, var height) = rect;

Or simply:

var (width, height) = rect;

If the variables into which you’re deconstructing are already defined, omit the types altogether; this is called a deconstructing assignment:

(width, height) = rect;

You can offer the caller a range of deconstruction options by overloading the Deconstruct method.

Object Initializers

To simplify object initialization, the accessible fields or properties of an object can be initialized via an object initializer directly after construction. For example, consider the following class:

public class Bunny
{
  public string Name;
  public bool LikesCarrots, LikesHumans;

  public Bunny () {}
  public Bunny (string n) { Name = n; }
}

Using object initializers, you can instantiate Bunny objects as follows:

Bunny b1 = new Bunny {
                       Name="Bo",
                       LikesCarrots = true,
                       LikesHumans = false
                     };

Bunny b2 = new Bunny ("Bo") {
                              LikesCarrots = true,
                              LikesHumans = false
                            };

The this Reference

The this reference refers to the instance itself. In the following example, the Marry method uses this to set the partner’s mate field:

public class Panda
{
  public Panda Mate;

  public void Marry (Panda partner)
  {
    Mate = partner;
    partner.Mate = this;
  }
}

The this reference also disambiguates a local variable or parameter from a field. For example:

public class Test
{
  string name;
  public Test (string name) { this.name = name; }
}

The this reference is valid only within nonstatic members of a class or struct.

Properties

Properties look like fields from the outside, but internally they contain logic, like methods do. For example, you can’t determine by looking at the following code whether CurrentPrice is a field or a property:

Stock msft = new Stock();
msft.CurrentPrice = 30;
msft.CurrentPrice -= 3;
Console.WriteLine (msft.CurrentPrice);

A property is declared like a field, but with a get/set block added. Here’s how to implement CurrentPrice as a property:

public class Stock
{
  decimal currentPrice;  // The private "backing" field

  public decimal CurrentPrice    // The public property
  {
     get { return currentPrice; }
     set { currentPrice = value; }
  }
}

get and set denote property accessors. The get accessor runs when the property is read. It must return a value of the property’s type. The set accessor runs when the property is assigned. It has an implicit parameter named value of the property’s type that you typically assign to a private field (in this case, currentPrice).

Although properties are accessed in the same way as fields, they differ in that they give the implementer complete control over getting and setting its value. This control enables the implementer to choose whatever internal representation is needed, without exposing the internal details to the user of the property. In this example, the set method could throw an exception if value was outside a valid range of values.

A property is read-only if it specifies only a get accessor, and it is write-only if it specifies only a set accessor. Write-only properties are rarely used.

A property typically has a dedicated backing field to store the underlying data. However, it doesn’t need to; it can instead return a value computed from other data.

decimal currentPrice, sharesOwned;

public decimal Worth
{
  get { return currentPrice * sharesOwned; }
}

public decimal Worth => currentPrice * sharesOwned;

public decimal Worth
{
  get => currentPrice * sharesOwned;
  set => sharesOwned = value / currentPrice;
}

public class Stock
{
  public decimal CurrentPrice { get; set; }
}

public decimal CurrentPrice { get; set; } = 123;

public int Maximum { get; } = 999;

private decimal x;
public decimal X
{
  get         { return x;  }
  private set { x = Math.Round (value, 2); }
}

Indexers

Indexers provide a natural syntax for accessing elements in a class or struct that encapsulate a list or dictionary of values. Indexers are similar to properties, but are accessed via an index argument rather than a property name. The string class has an indexer that lets you access each of its char values via an int index:

string s = "hello";
Console.WriteLine (s[0]); // 'h'
Console.WriteLine (s[3]); // 'l'

The syntax for using indexers is like that for using arrays, except that the index argument(s) can be of any type(s). You can call indexers null-conditionally by inserting a question mark before the square bracket (see “Null Operators”):

string s = null;
Console.WriteLine (s?[0]);  // Writes nothing; no error.

class Sentence
{
  string[] words = "The quick brown fox".Split();

  public string this [int wordNum]      // indexer
  { 
    get { return words [wordNum];  }
    set { words [wordNum] = value; }
  }
}

Sentence s = new Sentence();
Console.WriteLine (s[3]);       // fox
s[3] = "kangaroo";
Console.WriteLine (s[3]);       // kangaroo

public string this [int arg1, string arg2]
{
  get { ... }  set { ... }
}

public string this [int wordNum] => words [wordNum];

public string this [Index index] => words [index];
public string[] this [Range range] => words [range];

Sentence s = new Sentence();
Console.WriteLine (s [^1]);         // fox  
string[] firstTwoWords = s [..2];   // (The, quick)

Static Constructors

A static constructor executes once per type, rather than once per instance. A type can define only one static constructor, and it must be parameterless and have the same name as the type:

class Test
{
  static Test() { Console.Write ("Type Initialized"); }
}

The runtime automatically invokes a static constructor just prior to the type being used. Two things trigger this: instantiating the type, and accessing a static member in the type.

Static field initializers run just before the static constructor is called. If a type has no static constructor, static field initializers will execute just prior to the type being used—or anytime earlier at the whim of the runtime.

Static Classes

A class can be marked static, indicating that it must be composed solely of static members and cannot be subclassed. The System.Console and System.Math classes are good examples of static classes.

Finalizers

Finalizers are class-only methods that execute before the garbage collector reclaims the memory for an unreferenced object. The syntax for a finalizer is the name of the class prefixed with the ~ symbol:

class Class1
{
  ~Class1() { ... }
}

C# translates a finalizer into a method that overrides the Finalize method in the object class. We discuss garbage collection and finalizers fully in Chapter 12 of C# 8.0 in a Nutshell.

From C# 7, single-statement finalizers can be written with expression-bodied syntax.

Partial Types and Methods

Partial types allow a type definition to be split—typically across multiple files. A common scenario is for a partial class to be autogenerated from some other source (e.g., a Visual Studio template), and for that class to be augmented with additional hand-authored methods. For example:

// PaymentFormGen.cs - autogenerated
partial class PaymentForm { ... }

// PaymentForm.cs - hand-authored
partial class PaymentForm { ... }

Each participant must have the partial declaration.

Participants cannot have conflicting members. A constructor with the same parameters, for instance, cannot be repeated. Partial types are resolved entirely by the compiler, which means that each participant must be available at compile time and must reside in the same assembly.

A base class can be specified on a single participant or on multiple participants (as long as the base class that you specify is the same). In addition, each participant can independently specify interfaces to implement. We cover base classes and interfaces in “Inheritance” and “Interfaces”.

partial class PaymentForm    // In autogenerated file
{
  partial void ValidatePayment (decimal amount);
}

partial class PaymentForm    // In hand-authored file
{
  partial void ValidatePayment (decimal amount)
  {
    if (amount > 100) Console.Write ("Expensive!");
  }
}

The nameof Operator

The nameof operator (introduced in C# 6) returns the name of any symbol (type, member, variable, and so on) as a string:

int count = 123;
string name = nameof (count);       // name is "count"

Its advantage over simply specifying a string is that of static type checking. Tools such as Visual Studio can understand the symbol reference, so if you rename the symbol in question, all of its references will be renamed, too.

To specify the name of a type member such as a field or property, include the type as well. This works with both static and instance members:

string name = nameof (StringBuilder.Length);

This evaluates to "Length". To return "StringBuilder.Length", you would do this:

nameof(StringBuilder)+"."+nameof(StringBuilder.Length);

Polymorphism

References are polymorphic. This means a variable of type x can refer to an object that subclasses x. For instance, consider the following method:

public static void Display (Asset asset)
{
  System.Console.WriteLine (asset.Name);
}

This method can display both a Stock and a House because they are both Assets. Polymorphism works on the basis that subclasses (Stock and House) have all the features of their base class (Asset). The converse, however, is not true. If Display were rewritten to accept a House, you could not pass in an Asset.

Casting and Reference Conversions

An object reference can be:

• Implicitly upcast to a base class reference

• Explicitly downcast to a subclass reference

Upcasting and downcasting between compatible reference types performs reference conversions: a new reference is created that points to the same object. An upcast always succeeds; a downcast succeeds only if the object is suitably typed.

Stock msft = new Stock();    // From previous example
Asset a = msft;              // Upcast

Console.WriteLine (a == msft);        // True

Console.WriteLine (a.Name);           // OK
Console.WriteLine (a.SharesOwned);    // Compile-time error

Stock msft = new Stock();
Asset a = msft;                      // Upcast
Stock s = (Stock)a;                  // Downcast
Console.WriteLine (s.SharesOwned);   // <No error>
Console.WriteLine (s == a);          // True
Console.WriteLine (s == msft);       // True

House h = new House();
Asset a = h;          // Upcast always succeeds
Stock s = (Stock)a;   // Downcast fails: a is not a Stock

Asset a = new Asset();
Stock s = a as Stock;   // s is null; no exception thrown

if (s != null) Console.WriteLine (s.SharesOwned);

if (a is Stock) Console.Write (((Stock)a).SharesOwned);

if (a is Stock s)
  Console.WriteLine (s.SharesOwned);

if (a is Stock s && s.SharesOwned > 100000)
  Console.WriteLine ("Wealthy");
else
  s = new Stock();   // s is in scope

Console.WriteLine (s.SharesOwned);  // Still in scope

Virtual Function Members

A function marked as virtual can be overridden by subclasses wanting to provide a specialized implementation. Methods, properties, indexers, and events can all be declared virtual:

public class Asset
{
  public string Name;
  public virtual decimal Liability => 0;
}

(Liability => 0 is a shortcut for { get { return 0; } }. See “Expression-bodied properties” for more details on this syntax.) A subclass overrides a virtual method by applying the override modifier:

public class House : Asset
{
  public decimal Mortgage;

  public override decimal Liability => Mortgage;
}

By default, the Liability of an Asset is 0. A Stock does not need to specialize this behavior. However, the House specializes the Liability property to return the value of the Mortgage:

House mansion = new House { Name="Mansion",
                            Mortgage=250000 };
Asset a = mansion;
Console.WriteLine (mansion.Liability);  // 250000
Console.WriteLine (a.Liability);        // 250000

The signatures, return types, and accessibility of the virtual and overridden methods must be identical. An overridden method can call its base class implementation via the base keyword (see “The base Keyword”).

Abstract Classes and Abstract Members

A class declared as abstract can never be instantiated. Instead, only its concrete subclasses can be instantiated.

Abstract classes are able to define abstract members. Abstract members are like virtual members, except they don’t provide a default implementation. That implementation must be provided by the subclass, unless that subclass is also declared abstract:

public abstract class Asset
{
  // Note empty implementation
  public abstract decimal NetValue { get; }
}

Subclasses override abstract members just as though they were virtual.

Hiding Inherited Members

A base class and a subclass can define identical members. For example:

public class A      { public int Counter = 1; }
public class B : A  { public int Counter = 2; }

The Counter field in class B is said to hide the Counter field in class A. Usually, this happens by accident, when a member is added to the base type after an identical member was added to the subtype. For this reason, the compiler generates a warning, and then resolves the ambiguity as follows:

• References to A (at compile time) bind to A.Counter.

• References to B (at compile time) bind to B.Counter.

Occasionally, you want to hide a member deliberately, in which case you can apply the new modifier to the member in the subclass. The new modifier does nothing more than suppress the compiler warning that would otherwise result:

public class A     { public     int Counter = 1; }
public class B : A { public new int Counter = 2; }

The new modifier communicates your intent to the compiler—and other programmers—that the duplicate member is not an accident.

Sealing Functions and Classes

An overridden function member can seal its implementation with the sealed keyword to prevent it from being overridden by further subclasses. In our earlier virtual function member example, we could have sealed House’s implementation of Liability, preventing a class that derives from House from overriding Liability, as follows:

public sealed override decimal Liability { get { ... } }

You can also seal the class itself, implicitly sealing all the virtual functions, by applying the sealed modifier to the class itself.

The base Keyword

The base keyword is similar to the this keyword. It serves two essential purposes: accessing an overridden function member from the subclass, and calling a base class constructor (see the next section).

In this example, House uses the base keyword to access Asset’s implementation of Liability:

public class House : Asset
{
  ...
  public override decimal Liability 
    => base.Liability + Mortgage;
}

With the base keyword, we access Asset’s Liability property nonvirtually. This means that we will always access Asset’s version of this property, regardless of the instance’s actual runtime type.

The same approach works if Liability is hidden rather than overridden. (You can also access hidden members by casting to the base class before invoking the function.)

Constructors and Inheritance

A subclass must declare its own constructors. For example, if we define Baseclass and Subclass as

public class Baseclass
{
  public int X;
  public Baseclass () { }
  public Baseclass (int x) { this.X = x; }
}
public class Subclass : Baseclass { }

the following is illegal:

Subclass s = new Subclass (123);

Subclass must “redefine” any constructors that it wants to expose. In doing so, it can call any of the base class’s constructors with the base keyword:

public class Subclass : Baseclass
{
  public Subclass (int x) : base (x) { ... }
}

The base keyword works rather like the this keyword, except that it calls a constructor in the base class. Base class constructors always execute first; this ensures that base initialization occurs before specialized initialization.

If a constructor in a subclass omits the base keyword, the base type’s parameterless constructor is implicitly called (if the base class has no accessible parameterless constructor, the compiler generates an error).

Overloading and Resolution

Inheritance has an interesting impact on method overloading. Consider the following two overloads:

static void Foo (Asset a) { }
static void Foo (House h) { }

When an overload is called, the most specific type has precedence:

House h = new House (...);
Foo(h);                      // Calls Foo(House)

The particular overload to call is determined statically (at compile time) rather than at runtime. The following code calls Foo(Asset), even though the runtime type of a is House:

Asset a = new House (...);
Foo(a);                      // Calls Foo(Asset)

Boxing and Unboxing

Boxing is the act of casting a value type instance to a reference type instance. The reference type can be either the object class or an interface (see “Interfaces”). In this example, we box an int into an object:

int x = 9;
object obj = x;           // Box the int

Unboxing reverses the operation by casting the object back to the original value type:

int y = (int)obj;         // Unbox the int

Unboxing requires an explicit cast. The runtime checks that the stated value type matches the actual object type, throwing an InvalidCastException if the check fails. For instance, the following throws an exception, because long does not exactly match int:

object obj = 9;       // 9 is inferred to be of type int
long x = (long) obj;  // InvalidCastException

The following succeeds, however:

object obj = 9;
long x = (int) obj;

As does this:

object obj = 3.5;      // 3.5 inferred to be type double
int x = (int) (double) obj;    // x is now 3

In the last example, (double) performs an unboxing and then (int) performs a numeric conversion.

Boxing copies the value type instance into the new object, and unboxing copies the contents of the object back into a value type instance:

int i = 3;
object boxed = i;
i = 5;
Console.WriteLine (boxed);    // 3

Static and Runtime Type Checking

C# checks types both statically (at compile time) and at runtime.

Static type checking enables the compiler to verify the correctness of your program without running it. The following code will fail because the compiler enforces static typing:

int x = "5";

Runtime type checking is performed by the CLR when you downcast via a reference conversion or unboxing:

object y = "5";
int z = (int) y;       // Runtime error, downcast failed

Runtime type checking is possible because each object on the heap internally stores a little type token. You can retrieve this token by calling the GetType method of object.

The GetType Method and typeof Operator

All types in C# are represented at runtime with an instance of System.Type. There are two basic ways to get a System.Type object: call GetType on the instance, or use the typeof operator on a type name. GetType is evaluated at runtime; typeof is evaluated statically at compile time.

System.Type has properties for such things as the type’s name, assembly, base type, and so on. For example:

int x = 3;

Console.Write (x.GetType().Name);               // Int32
Console.Write (typeof(int).Name);               // Int32
Console.Write (x.GetType().FullName);    // System.Int32
Console.Write (x.GetType() == typeof(int));     // True

System.Type also has methods that act as a gateway to the runtime’s reflection model. For detailed information, see Chapter 19 of C# 8.0 in a Nutshell.

Object Member Listing

Her are all the members of object:

public extern Type GetType();
public virtual bool Equals (object obj);
public static bool Equals (object objA, object objB);
public static bool ReferenceEquals (object objA,
                                    object objB);
public virtual int GetHashCode();
public virtual string ToString();
protected virtual void Finalize();
protected extern object MemberwiseClone();

Equals, ReferenceEquals, and GetHashCode

The Equals method in the object class is similar to the == operator except that Equals is virtual, whereas == is static. The following example illustrates the difference:

object x = 3;
object y = 3;
Console.WriteLine (x == y);        // False
Console.WriteLine (x.Equals (y));  // True

Because x and y have been cast to the object type, the compiler statically binds to object’s == operator, which uses reference type semantics to compare two instances. (And because x and y are boxed, they are represented in separate memory locations, and so are unequal.) The virtual Equals method, however, defers to the Int32 type’s Equals method, which uses value type semantics in comparing two values.

The static object.Equals method simply calls the virtual Equals method on the first argument—after checking that the arguments are not null:

object x = null, y = 3;
bool error = x.Equals (y);        // Runtime error!
bool ok = object.Equals (x, y);   // OK (false)

ReferenceEquals forces a reference type equality comparison (this is occasionally useful on reference types for which the == operator has been overloaded to do otherwise).

GetHashCode emits a hash code suitable for use with hashtable-based dictionaries such as System.Collections.Generic.Dictionary and System.Collections.Hashtable.

To customize a type’s equality semantics, you must at a minimum override Equals and GetHashCode. You would also usually overload the == and != operators. For an example of how to do both, see “Operator Overloading”.

The ToString Method

The ToString method returns the default textual representation of a type instance. The ToString method is overridden by all built-in types:

string s1 = 1.ToString();      // s1 is "1"
string s2 = true.ToString();   // s2 is "True"

You can override the ToString method on custom types as follows:

public override string ToString() => "Foo";

Struct Construction Semantics

The construction semantics of a struct are as follows:

• A parameterless constructor that you can’t override implicitly exists. This performs a bitwise-zeroing of its fields.

• When you define a struct constructor (with parameters), you must explicitly assign every field.

• You can’t have field initializers in a struct.

readonly Structs and Functions

From C# 7.2, you can apply the readonly modifier to a struct to enforce that all fields are readonly; this aids in declaring intent as well as allowing the compiler more optimization freedom:

readonly struct Point
{
  public readonly int X, Y;   // X and Y must be readonly
}

If you need to apply readonly at a more granular level, C# 8 assists with a new feature whereby you can apply the readonly modifier to a struct’s functions. This ensures that if the function attempts to modify any field, a compile-time error is generated:

struct Point
{
  public int X, Y;
  public readonly void ResetX() => X = 0;  // Error!
}

If a readonly function calls a non-readonly function, the compiler generates a warning (and defensively copies the struct to avoid the possibility of a mutation).

Friend Assemblies

You can expose internal members to other friend assemblies by adding the System.Runtime.CompilerServices.InternalsVisibleTo assembly attribute, specifying the name of the friend assembly as follows:

[assembly: InternalsVisibleTo ("Friend")]

If the friend assembly is signed with a strong name, you must specify its full 160-byte public key. You can extract this key via a Language Integrated Query (LINQ)—an interactive example is given in LINQPad’s free sample library for C# 8.0 in a Nutshell, under Chapter 3, Access Modifiers.

Accessibility Capping

A type caps the accessibility of its declared members. The most common example of capping is when you have an internal type with public members. For example:

class C { public void Foo() {} }

C’s (default) internal accessibility caps Foo’s accessibility, effectively making Foo internal. A common reason Foo would be marked public is to make for easier refactoring, should C later be changed to public.

Extending an Interface

Interfaces can derive from other interfaces. For instance:

public interface IUndoable             { void Undo(); }
public interface IRedoable : IUndoable { void Redo(); }

IRedoable “inherits” all the members of IUndoable.

Explicit Interface Implementation

Implementing multiple interfaces can sometimes result in a collision between member signatures. You can resolve such collisions by explicitly implementing an interface member. For example:

interface I1 { void Foo(); }
interface I2 { int Foo();  }

public class Widget : I1, I2
{
  public void Foo()   // Implicit implementation
  {
    Console.Write ("Widget's implementation of I1.Foo");
  }

  int I2.Foo()   // Explicit implementation of I2.Foo
  {
    Console.Write ("Widget's implementation of I2.Foo");
    return 42;
  }
}

Because both I1 and I2 have conflicting Foo signatures, Widget explicitly implements I2’s Foo method. This lets the two methods coexist in one class. The only way to call an explicitly implemented member is to cast to its interface:

Widget w = new Widget();
w.Foo();           // Widget's implementation of I1.Foo
((I1)w).Foo();     // Widget's implementation of I1.Foo
((I2)w).Foo();     // Widget's implementation of I2.Foo

Another reason to explicitly implement interface members is to hide members that are highly specialized and distracting to a type’s normal use case. For example, a type that implements ISerializable would typically want to avoid flaunting its ISerializable members unless explicitly cast to that interface.

Implementing Interface Members Virtually

An implicitly implemented interface member is, by default, sealed. It must be marked virtual or abstract in the base class in order to be overridden: calling the interface member through either the base class or the interface then calls the subclass’s implementation.

An explicitly implemented interface member cannot be marked virtual, nor can it be overridden in the usual manner. It can, however, be reimplemented.

Reimplementing an Interface in a Subclass

A subclass can reimplement any interface member already implemented by a base class. Reimplementation hijacks a member implementation (when called through the interface) and works whether or not the member is virtual in the base class.

In the following example, TextBox implements IUndo.Undo explicitly, and so it cannot be marked as virtual. To “override” it, RichTextBox must reimplement IUndo’s Undo method:

public interface IUndoable { void Undo(); }

public class TextBox : IUndoable
{
  void IUndoable.Undo()
    => Console.WriteLine ("TextBox.Undo");
}

public class RichTextBox : TextBox, IUndoable
{
  public new void Undo()
    => Console.WriteLine ("RichTextBox.Undo");
}

Calling the reimplemented member through the interface calls the subclass’s implementation:

RichTextBox r = new RichTextBox();
r.Undo();                 // RichTextBox.Undo
((IUndoable)r).Undo();    // RichTextBox.Undo

In this case, Undo is implemented explicitly. Implicitly implemented members can also be reimplemented, but the effect is nonpervasive in that calling the member through the base class invokes the base implementation.

Default Interface Members (C# 8)

From C# 8, you can add a default implementation to an interface member, making it optional to implement:

interface ILogger
{
  void Log (string text) => Console.WriteLine (text);
}

This is advantageous if you wish to add a member to an interface defined in a popular library without breaking (potentially thousands of) implementations.

Default implementations are always explicit, so if a class implementing ILogger fails to define a Log method, the only way to call it is through the interface:

class Logger : ILogger { }
...
((ILogger)new Logger()).Log ("message");

This prevents a problem of multiple implementation inheritance: if the same default member is added to two interfaces that a class implements, there is never an ambiguity as to which member is called.

Interfaces can also now define static members (including fields), which can be accessed from code inside default implementations:

interface ILogger
{
  void Log (string text) => 
    Console.WriteLine (Prefix + text);

  static string Prefix = ""; 
}

Because interface members are implicitly public, you can also access static members from the outside:

ILogger.Prefix = "File log: ";

You can restrict this by adding an accessibility modifier to the static interface member (such as private, protected, or internal).

Instance fields are (still) prohibited. This is in line with the principle of interfaces, which is to define behavior, not state.

Enum Conversions

You can convert an enum instance to and from its underlying integral value with an explicit cast:

int i = (int) BorderSide.Left;
BorderSide side = (BorderSide) i;
bool leftOrRight = (int) side <= 2;

You can also explicitly cast one enum type to another; the translation then uses the members’ underlying integral values.

The numeric literal 0 is treated specially in that it does not require an explicit cast:

BorderSide b = 0;    // No cast required
if (b == 0) ...

In this particular example, BorderSide has no member with an integer value of 0. This does not generate an error: a limitation of enums is that the compiler and CLR do not prevent the assignment of integrals whose values fall outside the range of members:

BorderSide b = (BorderSide) 12345;
Console.WriteLine (b);              // 12345

Flags Enums

You can combine enum members. To prevent ambiguities, members of a combinable enum require explicitly assigned values, typically in powers of two. For example:

[Flags]
public enum BorderSides
 { None=0, Left=1, Right=2, Top=4, Bottom=8 }

By convention, a combinable enum type is given a plural rather than singular name. To work with combined enum values, you use bitwise operators, such as | and &. These operate on the underlying integral values:

BorderSides leftRight =
  BorderSides.Left | BorderSides.Right;

if ((leftRight & BorderSides.Left) != 0)
  Console.WriteLine ("Includes Left");   // Includes Left

string formatted = leftRight.ToString(); // "Left, Right"

BorderSides s = BorderSides.Left;
s |= BorderSides.Right;
Console.WriteLine (s == leftRight);      // True

The Flags attribute should be applied to combinable enum types; if you fail to do this, calling ToString on an enum instance emits a number rather than a series of names.

For convenience, you can include combination members within an enum declaration itself:

[Flags] public enum BorderSides
{
  None=0,
  Left=1, Right=2, Top=4, Bottom=8,
  LeftRight = Left | Right, 
  TopBottom = Top  | Bottom,
  All       = LeftRight | TopBottom
}

Enum Operators

The operators that work with enums are:

=   ==   !=   <   >   <=   >=   +   -   ^  &  |   ˜
+=  -=   ++   -   sizeof

The bitwise, arithmetic, and comparison operators return the result of processing the underlying integral values. Addition is permitted between an enum and an integral type, but not between two enums.

Generic Types

A generic type declares type parameters—placeholder types to be filled in by the consumer of the generic type, which supplies the type arguments. Here is a generic type, Stack<T>, designed to stack instances of type T. Stack<T> declares a single type parameter T:

public class Stack<T>
{
  int position;
  T[] data = new T[100];
  public void Push (T obj) => data[position++] = obj;
  public T Pop()           => data[--position];
}

We can use Stack<T> as follows:

var stack = new Stack<int>();
stack.Push (5);
stack.Push (10);
int x = stack.Pop();        // x is 10
int y = stack.Pop();        // y is 5

Stack<int> fills in the type parameter T with the type argument int, implicitly creating a type on the fly (the synthesis occurs at runtime). Stack<int> effectively has the following definition (substitutions appear in bold, with the class name hashed out to avoid confusion):

public class ###
{
  int position;
  int[] data = new int[100];
  public void Push (int obj) => data[position++] = obj;
  public int Pop()           => data[--position];
}

Technically, we say that Stack<T> is an open type, whereas Stack<int> is a closed type. At runtime, all generic type instances are closed—with the placeholder types filled in.

Generic Methods

A generic method declares type parameters within the signature of a method. With generic methods, many fundamental algorithms can be implemented in a general-purpose way. Here is a generic method that swaps the contents of two variables of any type T:

static void Swap<T> (ref T a, ref T b)
{
  T temp = a; a = b; b = temp;
}

You can use Swap<T> as follows:

int x = 5, y = 10;
Swap (ref x, ref y);

Generally, there is no need to supply type arguments to a generic method, because the compiler can implicitly infer the type. If there is ambiguity, generic methods can be called with the type arguments as follows:

Swap<int> (ref x, ref y);

Within a generic type, a method is not classed as generic unless it introduces type parameters (with the angle bracket syntax). The Pop method in our generic stack merely consumes the type’s existing type parameter, T, and is not classed as a generic method.

Methods and types are the only constructs that can introduce type parameters. Properties, indexers, events, fields, constructors, operators, and so on cannot declare type parameters, although they can partake in any type parameters already declared by their enclosing type. In our generic stack example, for instance, we could write an indexer that returns a generic item:

public T this [int index] { get { return data[index]; } }

Similarly, constructors can partake in existing type parameters, but cannot introduce them.

Declaring Type Parameters

Type parameters can be introduced in the declaration of classes, structs, interfaces, delegates (see “Delegates”), and methods. You can specify multiple type parameters by separating them with commas:

class Dictionary<TKey, TValue> {...}

To instantiate:

var myDict = new Dictionary<int,string>();

Generic type names and method names can be overloaded as long as the number of type parameters differs. For example, the following three type names do not conflict:

class A {}
class A<T> {}
class A<T1,T2> {}

typeof and Unbound Generic Types

Open generic types do not exist at runtime: open generic types are closed as part of compilation. However, it is possible for an unbound generic type to exist at runtime—purely as a Type object. The only way to specify an unbound generic type in C# is with the typeof operator:

class A<T> {}
class A<T1,T2> {}
...

Type a1 = typeof (A<>);   // Unbound type
Type a2 = typeof (A<,>);  // Indicates 2 type args
Console.Write (a2.GetGenericArguments().Count());  // 2

You can also use the typeof operator to specify a closed type

Type a3 = typeof (A<int,int>);

or an open type (which is closed at runtime):

class B<T> { void X() { Type t = typeof (T); } }

The default Generic Value

You can use the default keyword to get the default value for a generic type parameter. The default value for a reference type is null, and the default value for a value type is the result of bitwise-zeroing the type’s fields:

static void Zap<T> (T[] array)
{
  for (int i = 0; i < array.Length; i++)
    array[i] = default(T);
}

From C# 7.1, you can omit the type argument for cases in which the compiler is able to infer it:

array[i] = default;

Generic Constraints

By default, a type parameter can be substituted with any type whatsoever. Constraints can be applied to a type parameter to require more specific type arguments. There are eight kinds of constraints:

where T : base-class  // Base class constraint
where T : interface   // Interface constraint
where T : class       // Reference type constraint
where T : class?      // (See "Nullable Reference Types")
where T : struct      // Value type constraint
where T : unmanaged   // Unmanaged constraint
where T : new()       // Parameterless constructor
                      // constraint
where U : T           // Naked type constraint

In the next example, GenericClass<T,U> requires T to derive from (or be identical to) SomeClass and implement Interface1, and requires U to provide a parameterless constructor:

class     SomeClass {}
interface Interface1 {}

class GenericClass<T,U> where T : SomeClass, Interface1
                        where U : new()
{ ... }

Constraints can be applied wherever type parameters are defined, whether in methods or in type definitions.

A base class constraint specifies that the type parameter must subclass (or match) a particular class; an interface constraint specifies that the type parameter must implement that interface. These constraints allow instances of the type parameter to be implicitly converted to that class or interface.

The class constraint and struct constraint specify that T must be a reference type or a (non-nullable) value type, respectively. The unmanaged constraint is a stronger version of a struct constraint: T must be a simple value type or a struct that is (recursively) free of any reference types. The parameterless constructor constraint requires T to have a public parameterless constructor and allows you to call new() on T:

static void Initialize<T> (T[] array) where T : new()
{
  for (int i = 0; i < array.Length; i++)
    array[i] = new T();
}

The naked type constraint requires one type parameter to derive from (or match) another type parameter.

Subclassing Generic Types

A generic class can be subclassed just like a nongeneric class. The subclass can leave the base class’s type parameters open, as in the following example:

class Stack<T>                   {...}
class SpecialStack<T> : Stack<T> {...}

Or the subclass can close the generic type parameters with a concrete type:

class IntStack : Stack<int>  {...}

A subtype can also introduce fresh type arguments:

class List<T>                     {...}
class KeyedList<T,TKey> : List<T> {...}

Self-Referencing Generic Declarations

A type can name itself as the concrete type when closing a type argument:

public interface IEquatable<T> { bool Equals (T obj); }

public class Balloon : IEquatable<Balloon>
{
  public bool Equals (Balloon b) { ... }
}

The following are also legal:

class Foo<T> where T : IComparable<T> { ... }
class Bar<T> where T : Bar<T> { ... }

Static Data

Static data is unique for each closed type:

class Bob<T> { public static int Count; }
...
Console.WriteLine (++Bob<int>.Count);     // 1
Console.WriteLine (++Bob<int>.Count);     // 2
Console.WriteLine (++Bob<string>.Count);  // 1
Console.WriteLine (++Bob<object>.Count);  // 1

Covariance

Assuming A is convertible to B, X has a covariant type parameter if X<A> is convertible to X<B>.

(With C#’s notion of variance, “convertible” means convertible via an implicit reference conversion—such as A subclassing B, or A implementing B. Numeric conversions, boxing conversions, and custom conversions are not included.)

For instance, type IFoo<T> has a covariant T if the following is legal:

IFoo<string> s = ...;
IFoo<object> b = s;

Interfaces (and delegates) permit covariant type parameters. To illustrate, suppose that the Stack<T> class that we wrote at the beginning of this section implements the following interface:

public interface IPoppable<out T> { T Pop(); }

The out modifier on T indicates that T is used only in output positions (e.g., return types for methods) and flags the type parameter as covariant, permitting the following code:

// Assuming that Bear subclasses Animal:
var bears = new Stack<Bear>();
bears.Push (new Bear());

// Because bears implements IPoppable<Bear>,
// we can convert it to IPoppable<Animal>:
IPoppable<Animal> animals = bears;   // Legal
Animal a = animals.Pop();

The cast from bears to animals is permitted by the compiler—by virtue of the interface’s type parameter being covariant.

The compiler will generate an error if you use a covariant type parameter in an input position (e.g., a parameter to a method or a writable property). The purpose of this limitation is to guarantee compile-time type safety. For instance, it prevents us from adding a Push(T) method to that interface, which consumers could abuse with the seemingly benign operation of pushing a camel onto an IPoppable<Animal> (remember that the underlying type in our example is a stack of bears). To define a Push(T) method, T must in fact be contravariant.

Contravariance

We previously saw that, assuming that A allows an implicit reference conversion to B, a type X has a covariant type parameter if X<A> allows a reference conversion to X<B>. A type is contravariant when you can convert in the reverse direction—from X<B> to X<A>. This is supported on interfaces and delegates when the type parameter appears only in input positions, designated with the in modifier. Extending our previous example, if the Stack<T> class implements the following interface:

public interface IPushable<in T> { void Push (T obj); }

we can legally do this:

IPushable<Animal> animals = new Stack<Animal>();
IPushable<Bear> bears = animals;    // Legal
bears.Push (new Bear());

Mirroring covariance, the compiler will report an error if you try to use a contravariant type parameter in an output position (e.g., as a return value, or in a readable property).

Writing Plug-In Methods with Delegates

A delegate variable is assigned a method at runtime. This is useful for writing plug-in methods. In this example, we have a utility method named Transform that applies a transform to each element in an integer array. The Transform method has a delegate parameter for specifying a plug-in transform:

public delegate int Transformer (int x);

class Test
{
  static void Main()
  {
    int[] values = { 1, 2, 3 };
    Transform (values, Square);
    foreach (int i in values)
      Console.Write (i + " ");    // 1 4 9
  }

  static void Transform (int[] values, Transformer t)
  {
    for (int i = 0; i < values.Length; i++)
      values[i] = t (values[i]);
  }

  static int Square (int x) => x * x;
}

Multicast Delegates

All delegate instances have multicast capability. This means that a delegate instance can reference not just a single target method, but also a list of target methods. The + and += operators combine delegate instances. For example:

SomeDelegate d = SomeMethod1;
d += SomeMethod2;

The last line is functionally the same as this one:

d = d + SomeMethod2;

Invoking d will now call both SomeMethod1 and SomeMethod2. Delegates are invoked in the order in which they are added.

The - and -= operators remove the right delegate operand from the left delegate operand. For example:

d -= SomeMethod1;

Invoking d will now cause only SomeMethod2 to be invoked.

Calling + or += on a delegate variable with a null value is legal, as is calling -= on a delegate variable with a single target (which will result in the delegate instance being null).

If a multicast delegate has a nonvoid return type, the caller receives the return value from the last method to be invoked. The preceding methods are still called, but their return values are discarded. In most scenarios in which multicast delegates are used, they have void return types, so this subtlety does not arise.

All delegate types implicitly derive from System.MulticastDelegate, which inherits from System.Delegate. C# compiles +, -, +=, and -= operations made on a delegate to the static Combine and Remove methods of the System.Delegate class.

Instance versus Static Method Targets

When an instance method is assigned to a delegate object, the latter must maintain a reference not only to the method, but also to the instance to which the method belongs. The System.Delegate class’s Target property represents this instance (and will be null for a delegate referencing a static method).

Generic Delegate Types

A delegate type can contain generic type parameters. For example:

public delegate T Transformer<T> (T arg);

Here’s how we could use this delegate type:

static double Square (double x) => x * x;

static void Main()
{
  Transformer<double> s = Square;
  Console.WriteLine (s (3.3));        // 10.89
}

The Func and Action Delegates

With generic delegates, it becomes possible to write a small set of delegate types that are so general they can work for methods of any return type and any (reasonable) number of arguments. These delegates are the Func and Action delegates, defined in the System namespace (the in and out annotations indicate variance, which we cover in the context of delegates shortly):

delegate TResult Func <out TResult> ();
delegate TResult Func <in T, out TResult> (T arg);
delegate TResult Func <in T1, in T2, out TResult>
 (T1 arg1, T2 arg2);
... and so on, up to T16

delegate void Action ();
delegate void Action <in T> (T arg);
delegate void Action <in T1, in T2> (T1 arg1, T2 arg2);
... and so on, up to T16

These delegates are extremely general. The Transformer delegate in our previous example can be replaced with a Func delegate that takes a single argument of type T and returns a same-typed value:

public static void Transform<T> (
  T[] values, Func<T,T> transformer)
{
  for (int i = 0; i < values.Length; i++)
    values[i] = transformer (values[i]);
}

The only practical scenarios not covered by these delegates are ref/out and pointer parameters.

Delegate Compatibility

Delegate types are all incompatible with one another, even if their signatures are the same:

delegate void D1(); delegate void D2();
...
D1 d1 = Method1;
D2 d2 = d1;            // Compile-time error

The following, however, is permitted:

D2 d2 = new D2 (d1);

Delegate instances are considered equal if they have the same type and method target(s). For multicast delegates, the order of the method targets is significant.

delegate object ObjectRetriever();
...
static void Main()
{
  ObjectRetriever o = new ObjectRetriever (GetString);
  object result = o();
  Console.WriteLine (result);      // hello
}
static string GetString() => "hello";

delegate void StringAction (string s);
...
static void Main()
{
  StringAction sa = new StringAction (ActOnObject);
  sa ("hello");  // Writes "Hello"
}
static void ActOnObject (object o) => Console.Write (o);

delegate TResult Func<out TResult>();

Func<string> x = ...;
Func<object> y = x;

delegate void Action<in T> (T arg);

Action<object> x = ...;
Action<string> y = x;

Standard Event Pattern

In almost all cases in which events are defined in the .NET Core library, their definition adheres to a standard pattern designed to provide consistency across library and user code. Here’s the preceding example refactored with this pattern:

public class PriceChangedEventArgs : EventArgs
{
  public readonly decimal LastPrice, NewPrice;

  public PriceChangedEventArgs (decimal lastPrice,
                                decimal newPrice)
  {
    LastPrice = lastPrice; NewPrice = newPrice;
  }
}

public class Stock
{
  string symbol; decimal price;

  public Stock (string symbol) => this.symbol = symbol;

  public event EventHandler<PriceChangedEventArgs>
               PriceChanged;

  protected virtual void OnPriceChanged
                        (PriceChangedEventArgs e) =>
    // Shortcut for invoking PriceChanged if not null:
    PriceChanged?.Invoke (this, e);

  
  public decimal Price
  {
    get { return price; }
    set
    {
      if (price == value) return;
      OnPriceChanged (new PriceChangedEventArgs (price,
                                                 value));
      price = value;
    }  
  }
}

At the core of the standard event pattern is System.EventArgs: a predefined .NET class with no members (other than the static Empty property). EventArgs is a base class for conveying information for an event. In this example, we subclass EventArgs to convey the old and new prices when a PriceChanged event is fired.

The generic System.EventHandler delegate is also part of .NET Core and is defined as follows:

public delegate void EventHandler<TEventArgs>
   (object source, TEventArgs e)
    where TEventArgs : EventArgs;

delegate void PriceChangedHandler
  (object sender,
   PriceChangedEventArgs e);

A protected virtual method named On-event-name centralizes firing of the event. This allows subclasses to fire the event (which is usually desirable) and also allows subclasses to insert code before and after the event is fired.

Here’s how we could use our Stock class:

static void Main()
{
  Stock stock = new Stock ("THPW");
  stock.Price = 27.10M;

  stock.PriceChanged += stock_PriceChanged;
  stock.Price = 31.59M;
}

static void stock_PriceChanged
  (object sender, PriceChangedEventArgs e)
{
  if ((e.NewPrice - e.LastPrice) / e.LastPrice > 0.1M)
    Console.WriteLine ("Alert, 10% price increase!");
}

For events that don’t carry additional information, .NET also provides a nongeneric EventHandler delegate. We can demonstrate this by rewriting our Stock class such that the PriceChanged event fires after the price changes. This means that no additional information need be transmitted with the event:

public class Stock
{
  string symbol; decimal price;

  public Stock (string symbol) => this.symbol = symbol;

  public event EventHandler PriceChanged;

  protected virtual void OnPriceChanged (EventArgs e) =>
    PriceChanged?.Invoke (this, e);
  
  public decimal Price
  {
    get => price;
    set
    {
      if (price == value) return;
      price = value;
      OnPriceChanged (EventArgs.Empty);      
    }  
  }
}

Note that we also used the EventArgs.Empty property—this saves instantiating an instance of EventArgs.

Event Accessors

An event’s accessors are the implementations of its += and -= functions. By default, accessors are implemented implicitly by the compiler. Consider this event declaration:

public event EventHandler PriceChanged;

The compiler converts this to the following:

• A private delegate field

• A public pair of event accessor functions, whose implementations forward the += and -= operations to the private delegate field

You can take over this process by defining explicit event accessors. Here’s a manual implementation of the PriceChanged event from our previous example:

EventHandler priceChanged;   // Private delegate
public event EventHandler PriceChanged
{
  add    { priceChanged += value; }
  remove { priceChanged -= value; }
}

This example is functionally identical to C#’s default accessor implementation (except that C# also ensures thread safety around updating the delegate). By defining event accessors ourselves, we instruct C# not to generate default field and accessor logic.

With explicit event accessors, you can apply more complex strategies to the storage and access of the underlying delegate. This is useful when the event accessors are merely relays for another class that is broadcasting the event, or when explicitly implementing an interface that declares an event:

public interface IFoo { event EventHandler Ev; }
class Foo : IFoo
{
  EventHandler ev;
  event EventHandler IFoo.Ev
  {
    add { ev += value; } remove { ev -= value; }
  }
}

Capturing Outer Variables

A lambda expression can reference the local variables and parameters of the method in which it’s defined (outer variables). For example:

static void Main()
{
  int factor = 2;
  Func<int, int> multiplier = n => n * factor;
  Console.WriteLine (multiplier (3));           // 6
}

Outer variables referenced by a lambda expression are called captured variables. A lambda expression that captures variables is called a closure. Captured variables are evaluated when the delegate is actually invoked, not when the variables were captured:

int factor = 2;
Func<int, int> multiplier = n => n * factor;
factor = 10;
Console.WriteLine (multiplier (3));           // 30

Lambda expressions can themselves update captured variables:

int seed = 0;
Func<int> natural = () => seed++;
Console.WriteLine (natural());           // 0
Console.WriteLine (natural());           // 1
Console.WriteLine (seed);                // 2

Captured variables have their lifetimes extended to that of the delegate. In the following example, the local variable seed would ordinarily disappear from scope when Natural finished executing. But because seed has been captured, its lifetime is extended to that of the capturing delegate, natural:

static Func<int> Natural()
{
  int seed = 0;
  return () => seed++;      // Returns a closure
}
static void Main()
{
  Func<int> natural = Natural();
  Console.WriteLine (natural());      // 0
  Console.WriteLine (natural());      // 1
}

Action[] actions = new Action[3];

for (int i = 0; i < 3; i++)
  actions [i] = () => Console.Write (i);

foreach (Action a in actions) a();     // 333

Action[] actions = new Action[3];
for (int i = 0; i < 3; i++)
{
  int loopScopedi = i;
  actions [i] = () => Console.Write (loopScopedi);
}
foreach (Action a in actions) a();     // 012

Lambda Expressions versus Local Methods

The functionality of local methods (see “Local methods”) overlaps with that of lambda expressions. Local methods have the advantages of allowing for recursion and avoiding the clutter of specifying a delegate. Avoiding the indirection of a delegate also makes them slightly more efficient, and they can access local variables of the containing method without the compiler having to “hoist” the captured variables into a hidden class.

However, in many cases you need a delegate, most commonly when calling a higher-order function (i.e., a method with a delegate-typed parameter):

public void Foo (Func<int,bool> predicate) { ... }

In such cases, you need a delegate anyway, and it’s precisely in these cases that lambda expressions are usually terser and cleaner.

The catch Clause

A catch clause specifies what type of exception to catch. This must be either System.Exception or a subclass of System.Exception. Catching System.Exception snares all possible errors. This is useful when:

• Your program can potentially recover regardless of the specific exception type.

• You plan to rethrow the exception (perhaps after logging it).

• Your error handler is the last resort, prior to termination of the program.

More typically, though, you catch specific exception types in order to avoid having to deal with circumstances for which your handler wasn’t designed (e.g., an OutOfMemoryException).

You can handle multiple exception types with multiple catch clauses:

try
{
  DoSomething();
}
catch (IndexOutOfRangeException ex) { ... }
catch (FormatException ex)          { ... }
catch (OverflowException ex)        { ... }

Only one catch clause executes for a given exception. If you want to include a safety net to catch more general exceptions (such as System.Exception), you must put the more specific handlers first.

You can catch an exception without specifying a variable, if you don’t need to access its properties:

catch (OverflowException)   // no variable
{ ... }

Furthermore, you can omit both the variable and the type (meaning that all exceptions will be caught):

catch { ... }

catch (WebException ex) 
  when (ex.Status == WebExceptionStatus.Timeout)
{
  ...
}

catch (WebException ex) when (ex.Status == something)
{ ... }
catch (WebException ex) when (ex.Status == somethingelse)
{ ... }

The finally Block

A finally block always executes—whether or not an exception is thrown and whether or not the try block runs to completion. finally blocks are typically used for cleanup code.

A finally block executes either:

• After a catch block finishes

• After control leaves the try block because of a jump statement (e.g., return or goto)

• After the try block ends

A finally block helps add determinism to a program. In the following example, the file that we open always gets closed, regardless of whether:

• The try block finishes normally

• Execution returns early because the file is empty (EndOfStream)

• An IOException is thrown while the file is being read

For example:

static void ReadFile()
{
  StreamReader reader = null;  // In System.IO namespace
  try
  {
    reader = File.OpenText ("file.txt");
    if (reader.EndOfStream) return;
    Console.WriteLine (reader.ReadToEnd());
  }
  finally
  {
    if (reader != null) reader.Dispose();
  }
}

In this example, we closed the file by calling Dispose on the StreamReader. Calling Dispose on an object, within a finally block, is a standard convention throughout .NET and is supported explicitly in C# through the using statement.

using (StreamReader reader = File.OpenText ("file.txt"))
{
  ...
}

{
  StreamReader reader = File.OpenText ("file.txt");
  try
  {
    ...
  }
  finally
  {
    if (reader != null) ((IDisposable)reader).Dispose();
  }
}

if (File.Exists ("file.txt"))
{
   using var reader = File.OpenText ("file.txt");  
   Console.WriteLine (reader.ReadLine());
   ...
}

Throwing Exceptions

Exceptions can be thrown either by the runtime or in user code. In this example, Display throws a System.ArgumentNull​Exception:

static void Display (string name)
{
  if (name == null)
    throw new ArgumentNullException (nameof (name));

  Console.WriteLine (name);
}

public string Foo() => throw new NotImplementedException();

string ProperCase (string value) =>
  value == null ? throw new ArgumentException ("value") :
  value == "" ? "" :
  char.ToUpper (value[0]) + value.Substring (1);

try {  ...  }
catch (Exception ex)
{
  // Log error
  ...
  throw;          // Rethrow same exception
}

try
{
  ... // parse a date of birth from XML element data
}
catch (FormatException ex)
{
  throw new XmlException ("Invalid date of birth", ex);
}

Key Properties of System.Exception

The most important properties of System.Exception are the following:

StackTrace

A string representing all the methods that are called from the origin of the exception to the catch block.

Message

A string with a description of the error.

InnerException

The inner exception (if any) that caused the outer exception. This, itself, might have another InnerException.

Common Exception Types

The following exception types are used widely throughout the CLR and .NET; you can throw them yourself or use them as base classes for deriving custom exception types:

System.ArgumentException

Thrown when a function is called with a bogus argument. This generally indicates a program bug.

System.ArgumentNullException

Subclass of ArgumentException that’s thrown when a function argument is (unexpectedly) null.

System.ArgumentOutOfRangeException

Subclass of ArgumentException that’s thrown when a (usually numeric) argument is too big or too small. For example, this is thrown when you pass a negative number into a function that accepts only positive values.

System.InvalidOperationException

Thrown when the state of an object is unsuitable for a method to successfully execute, regardless of any particular argument values. Examples include reading an unopened file or getting the next element from an enumerator where the underlying list has been modified partway through the iteration.

System.NotSupportedException

Thrown to indicate that a particular functionality is not supported. A good example is calling the Add method on a collection for which IsReadOnly returns true.

System.NotImplementedException

Thrown to indicate that a function has not yet been implemented.

System.ObjectDisposedException

Thrown when the object upon which the function is called has been disposed.

Enumeration

An enumerator is a read-only, forward-only cursor over a sequence of values. An enumerator is an object that implements System.Collections.IEnumerator or System.Collections.Gen​eric.IEnumerator<T>.

The foreach statement iterates over an enumerable object. An enumerable object is the logical representation of a sequence. It is not itself a cursor, but an object that produces cursors over itself. An enumerable either implements IEnumerable/IEnumerable<T> or has a method named GetEnumerator that returns an enumerator.

The enumeration pattern is as follows:

class Enumerator   // Typically implements IEnumerator<T>
{
  public IteratorVariableType Current { get {...} }
  public bool MoveNext() {...}
}
class Enumerable   // Typically implements IEnumerable<T>
{
  public Enumerator GetEnumerator() {...}
}

Here is the high-level way to iterate through the characters in the word beer using a foreach statement:

foreach (char c in "beer") Console.WriteLine (c);

Here is the low-level way to iterate through the characters in beer without using a foreach statement:

using (var enumerator = "beer".GetEnumerator())
  while (enumerator.MoveNext())
  {
    var element = enumerator.Current;
    Console.WriteLine (element);
  }

If the enumerator implements IDisposable, the foreach statement also acts as a using statement, implicitly disposing the enumerator object.

Collection Initializers

You can instantiate and populate an enumerable object in a single step. For example:

using System.Collections.Generic;
...

List<int> list = new List<int> {1, 2, 3};

The compiler translates the last line into the following:

List<int> list = new List<int>();
list.Add (1); list.Add (2); list.Add (3);

This requires that the enumerable object implements the System.Collections.IEnumerable interface, and that it has an Add method that has the appropriate number of parameters for the call. You can similarly initialize dictionaries (types that implement System.Collections.IDictionary) as follows:

var dict = new Dictionary<int, string>()
{
  { 5, "five" },
  { 10, "ten" }
};

Or, more succinctly:

var dict = new Dictionary<int, string>()
{
  [5] = "five",
  [10] = "ten"
};

The latter is valid not only with dictionaries, but with any type for which an indexer exists.

Iterators

Whereas a foreach statement is a consumer of an enumerator, an iterator is a producer of an enumerator. In this example, we use an iterator to return a sequence of Fibonacci numbers (for which each number is the sum of the previous two):

using System;
using System.Collections.Generic;

class Test
{
  static void Main()
  {
    foreach (int fib in Fibs(6))
      Console.Write (fib + "  ");
  }

  static IEnumerable<int> Fibs(int fibCount)
  {
    for (int i = 0, prevFib = 1, curFib = 1;
         i < fibCount;
         i++) 
    {
      yield return prevFib;
      int newFib = prevFib+curFib;
      prevFib = curFib;
      curFib = newFib;
    }
  }
}
OUTPUT: 1  1  2  3  5  8

Whereas a return statement expresses, “Here’s the value you asked me to return from this method,” a yield return statement expresses, “Here’s the next element you asked me to yield from this enumerator.” On each yield statement, control is returned to the caller, but the callee’s state is maintained so that the method can continue executing as soon as the caller enumerates the next element. The lifetime of this state is bound to the enumerator, such that the state can be released when the caller has finished enumerating.

Iterator Semantics

An iterator is a method, property, or indexer that contains one or more yield statements. An iterator must return one of the following four interfaces (otherwise, the compiler will generate an error):

System.Collections.IEnumerable
System.Collections.IEnumerator
System.Collections.Generic.IEnumerable<T>
System.Collections.Generic.IEnumerator<T>

Iterators that return an enumerator interface tend to be used less often. They’re useful when you’re writing a custom collection class: typically, you name the iterator GetEnumerator and have your class implement IEnumerable<T>.

Iterators that return an enumerable interface are more common—and simpler to use because you don’t need to write a collection class. The compiler, behind the scenes, writes a private class implementing IEnumerable<T> (as well as IEnumerator<T>).

static void Main()
{
  foreach (string s in Foo())
    Console.Write (s + " ");    // One Two Three
}

static IEnumerable<string> Foo()
{
  yield return "One";
  yield return "Two";
  yield return "Three";
}

static IEnumerable<string> Foo (bool breakEarly)
{
  yield return "One";
  yield return "Two";
  if (breakEarly) yield break;
  yield return "Three";
}

Composing Sequences

Iterators are highly composable. We can extend our Fibonacci example by adding the following method to the class:

static IEnumerable<int> EvenNumbersOnly (
  IEnumerable<int> sequence)
  {
    foreach (int x in sequence)
      if ((x % 2) == 0)
        yield return x;
  }
}

We can then output even Fibonacci numbers as follows:

foreach (int fib in EvenNumbersOnly (Fibs (6)))
  Console.Write (fib + " ");   // 2 8

Each element is not calculated until the last moment—when requested by a MoveNext() operation. Figure 5 shows the data requests and data output over time.

Figure 5. Composing sequences

The composability of the iterator pattern is essential in building LINQ queries.

Nullable<T> Struct

T? translates into System.Nullable<T>. Nullable<T> is a lightweight immutable structure, having only two fields, to represent Value and HasValue. The essence of System.Nullable<T> is very simple:

public struct Nullable<T> where T : struct
{
  public T Value {get;}
  public bool HasValue {get;}
  public T GetValueOrDefault();
  public T GetValueOrDefault (T defaultValue);
  ...
}

The code

int? i = null;
Console.WriteLine (i == null);              // True

translates to:

Nullable<int> i = new Nullable<int>();
Console.WriteLine (! i.HasValue);           // True

Attempting to retrieve Value when HasValue is false throws an InvalidOperationException. GetValueOrDefault() returns Value if HasValue is true; otherwise, it returns new T() or a specified custom default value.

The default value of T? is null.

Nullable Conversions

The conversion from T to T? is implicit, and from T? to T is explicit. For example:

int? x = 5;        // implicit
int y = (int)x;    // explicit

The explicit cast is directly equivalent to calling the nullable object’s Value property. Hence, an InvalidOperationException is thrown if HasValue is false.

Boxing/Unboxing Nullable Values

When T? is boxed, the boxed value on the heap contains T, not T?. This optimization is possible because a boxed value is a reference type that can already express null.

C# also permits the unboxing of nullable types with the as operator. The result will be null if the cast fails:

object o = "string";
int? x = o as int?;
Console.WriteLine (x.HasValue);   // False

Operator Lifting

The Nullable<T> struct does not define operators such as <, >, or even ==. Despite this, the following code compiles and executes correctly:

int? x = 5;
int? y = 10;
bool b = x < y;      // true

This works because the compiler borrows or “lifts” the less-than operator from the underlying value type. Semantically, it translates the preceding comparison expression into this:

bool b = (x.HasValue && y.HasValue)
          ? (x.Value < y.Value)
          : false;

In other words, if both x and y have values, it compares via int’s less-than operator; otherwise, it returns false.

Operator lifting means that you can implicitly use T’s operators on T?. You can define operators for T? in order to provide special-purpose null behavior, but in the vast majority of cases, it’s best to rely on the compiler automatically applying systematic nullable logic for you.

The compiler performs null logic differently depending on the category of operator.

Console.WriteLine (       null ==        null);  // True
Console.WriteLine ((bool?)null == (bool?)null);  // True

bool b = x < y;    // Translation:

bool b = (x == null || y == null)
  ? false 
  : (x.Value < y.Value);

// b is false (assuming x is 5 and y is null)

int? c = x + y;   // Translation:

int? c = (x == null || y == null)
         ? null 
         : (int?) (x.Value + y.Value);

// c is null (assuming x is 5 and y is null)

int? a = null;
int b = 2;
int? c = a + b;   // c is null - equivalent to a + (int?)b

bool? with & and | Operators

When supplied operands of type bool?, the & and | operators treat null as an unknown value. So, null | true is true, because:

• If the unknown value is false, the result would be true.

• If the unknown value is true, the result would be true.

Similarly, null & false is false. This behavior would be familiar to SQL users. The following example enumerates other combinations:

bool? n = null, f = false, t = true;
Console.WriteLine (n | n);    // (null)
Console.WriteLine (n | f);    // (null)
Console.WriteLine (n | t);    // True
Console.WriteLine (n & n);    // (null)
Console.WriteLine (n & f);    // False
Console.WriteLine (n & t);    // (null)

Nullable Types and Null Operators

Nullable types work particularly well with the ?? operator (see “Null-Coalescing Operator”). For example:

int? x = null;
int y = x ?? 5;        // y is 5

int? a = null, b = null, c = 123;
Console.WriteLine (a ?? b ?? c);  // 123

Using ?? on a nullable value type is equivalent to calling GetValueOrDefault with an explicit default value, except that the expression for the default value is never evaluated if the variable is not null.

Nullable types also work well with the null-conditional operator (see “Null-Conditional Operator”). In the following example, length evaluates to null:

System.Text.StringBuilder sb = null;
int? length = sb?.ToString().Length;

We can combine this with the null-coalescing operator to evaluate to zero instead of null:

int length = sb?.ToString().Length ?? 0;

Extension Method Chaining

Extension methods, like instance methods, provide a tidy way to chain functions. Consider the following two functions:

public static class StringHelper
{
  public static string Pluralize (this string s) {...}
  public static string Capitalize (this string s) {...}
}

x and y are equivalent, and both evaluate to "Sausages", but x uses extension methods, whereas y uses static methods:

string x = "sausage".Pluralize().Capitalize();

string y = StringHelper.Capitalize
           (StringHelper.Pluralize ("sausage"));

Ambiguity and Resolution

Naming Tuple Elements

You can optionally give meaningful names to elements when creating tuple literals:

var tuple = (Name:"Bob", Age:23);
Console.WriteLine (tuple.Name);     // Bob
Console.WriteLine (tuple.Age);      // 23

You can do the same when specifying tuple types:

static (string Name, int Age) GetPerson() => ("Bob",23);

Element names are automatically inferred from property or field names:

var now = DateTime.Now;
var tuple = (now.Day, now.Month, now.Year);
Console.WriteLine (tuple.Day);               // OK

Deconstructing Tuples

Tuples implicitly support the deconstruction pattern (see “Deconstructors”), so you can easily deconstruct a tuple into individual variables. So, instead of this

var bob = ("Bob", 23);
string name = bob.Item1;
int age = bob.Item2;

you can do this:

var bob = ("Bob", 23);
(string name, int age) = bob;   // Deconstruct bob into
                                // name and age.
Console.WriteLine (name);
Console.WriteLine (age);

The syntax for deconstruction is confusingly similar to the syntax for declaring a tuple with named elements! The following highlights the difference:

(string name, int age)      = bob;  // Deconstructing
(string name, int age) bob2 = bob;  // Declaring tuple

LINQ Fundamentals

The basic units of data in LINQ are sequences and elements. A sequence is any object that implements the generic IEnumerable interface, and an element is each item in the sequence. In the following example, names is a sequence, and Tom, Dick, and Harry are elements:

string[] names = { "Tom", "Dick", "Harry" };

A sequence such as this we call a local sequence because it represents a local collection of objects in memory.

A query operator is a method that transforms a sequence. A typical query operator accepts an input sequence and emits a transformed output sequence. In the Enumerable class in System.Linq, there are around 40 query operators, all implemented as static extension methods. These are called standard query operators.

string[] names = { "Tom", "Dick", "Harry" };

IEnumerable<string> filteredNames =
  System.Linq.Enumerable.Where (
    names, n => n.Length >= 4);

foreach (string n in filteredNames)
  Console.Write (n + "|");            // Dick|Harry|

IEnumerable<string> filteredNames =
   names.Where (n => n.Length >= 4);

static IEnumerable<TSource> Where<TSource> (
  this IEnumerable<TSource> source,
  Func<TSource,bool> predicate)

foreach (TSource element in source)
  if (predicate (element))
    yield return element;

string[] names = { "Tom", "Dick", "Harry" };

IEnumerable<string> upperNames =
  names.Select (n => n.ToUpper());

foreach (string n in upperNames)
  Console.Write (n + "|");       // TOM|DICK|HARRY|

var query = names.Select (n => new { 
                                     Name = n,
                                     Length = n.Length
                                   });
foreach (var row in query)
  Console.WriteLine (row);

{ Name = Tom, Length = 3 }
{ Name = Dick, Length = 4 }
{ Name = Harry, Length = 5 }

int[] numbers  = { 10, 9, 8, 7, 6 };
IEnumerable<int> firstThree = numbers.Take (3);
// firstThree is { 10, 9, 8 }

IEnumerable<int> lastTwo = numbers.Skip (3);

int[] numbers    = { 10, 9, 8, 7, 6 };
int firstNumber  = numbers.First();                // 10
int lastNumber   = numbers.Last();                 // 6
int secondNumber = numbers.ElementAt (2);          // 8
int firstOddNum  = numbers.First (n => n%2 == 1);  // 9

int[] numbers = { 10, 9, 8, 7, 6 };
int count     = numbers.Count();             // 5
int min       = numbers.Min();               // 6
int max       = numbers.Max();               // 10
double avg    = numbers.Average();           // 8

int evenNums = numbers.Count (n => n % 2 == 0);   // 3

int maxRemainderAfterDivBy5 = numbers.Max
                              (n => n % 5);       // 4

double rms = Math.Sqrt (numbers.Average (n => n * n));

int[] numbers = { 10, 9, 8, 7, 6 };

bool hasTheNumberNine = numbers.Contains (9);    // true
bool hasMoreThanZeroElements = numbers.Any();    // true
bool hasOddNum = numbers.Any (n => n % 2 == 1);  // true
bool allOddNums = numbers.All (n => n % 2 == 1); // false

int[] seq1 = { 1, 2, 3 }, seq2 = { 3, 4, 5 };

IEnumerable<int>
  concat = seq1.Concat (seq2),   // { 1, 2, 3, 3, 4, 5 }
  union  = seq1.Union  (seq2),   // { 1, 2, 3, 4, 5 }

IEnumerable<int>
  commonality = seq1.Intersect (seq2),    //  { 3 }
  difference1 = seq1.Except    (seq2),    //  { 1, 2 }
  difference2 = seq2.Except    (seq1);    //  { 4, 5 }

Standard Query Operators

We can divide the standard query operators (as implemented in the System.Linq.Enumerable class) into 12 categories, as summarized in Table 1.

Tables 2 through 13 summarize each query operator. The operators shown in bold have special support in C# (see “Query Expressions”).

Chaining Query Operators

To build more complex queries, you chain query operators together. For example, the following query extracts all strings containing the letter a, sorts them by length, and then converts the results to uppercase:

string[] names = { "Tom","Dick","Harry","Mary","Jay" };

IEnumerable<string> query = names
  .Where   (n => n.Contains ("a"))
  .OrderBy (n => n.Length)
  .Select  (n => n.ToUpper());

foreach (string name in query)
  Console.Write (name + "|");

// RESULT: JAY|MARY|HARRY|

Where, OrderBy, and Select are all standard query operators that resolve to extension methods in the Enumerable class. The Where operator emits a filtered version of the input sequence; OrderBy emits a sorted version of its input sequence; Select emits a sequence in which each input element is transformed or projected with a given lambda expression (n.ToUpper(), in this case). Data flows from left to right through the chain of operators, so the data is first filtered, then sorted, then projected. The end result resembles a production line of conveyor belts, as illustrated in Figure 6.

Figure 6. Chaining query operators

Deferred execution is honored throughout with operators, so no filtering, sorting, or projecting takes place until the query is actually enumerated.

Query Expressions

So far, we’ve written queries by calling extension methods in the Enumerable class. In this book, we describe this as fluent syntax. C# also provides special language support for writing queries, called query expressions. Here’s the preceding query expressed as a query expression:

IEnumerable<string> query =
  from n in names
  where n.Contains ("a")
  orderby n.Length
  select n.ToUpper();

A query expression always starts with a from clause, and ends with either a select or group clause. The from clause declares a range variable (in this case, n), which you can think of as traversing the input collection—rather like foreach. Figure 7 illustrates the complete syntax.

Figure 7. Query expression syntax

The compiler processes query expressions by translating them to fluent syntax. It does this in a fairly mechanical fashion—much like it translates foreach statements into calls to GetEnumerator and MoveNext:

IEnumerable<string> query = names
  .Where   (n => n.Contains ("a"))
  .OrderBy (n => n.Length)
  .Select  (n => n.ToUpper());

The Where, OrderBy, and Select operators then resolve using the same rules that would apply if the query were written in fluent syntax. In this case, they bind to extension methods in the Enumerable class (assuming that you’ve imported the System.Linq namespace) because names implements IEnumerable<string>. The compiler doesn’t specifically favor the Enumerable class, however, when translating query syntax. You can think of the compiler as mechanically injecting the words Where, OrderBy, and Select into the statement, and then compiling it as though you’d typed the method names yourself. This offers flexibility in how they resolve—the operators in Entity Framework queries, for instance, bind instead to the extension methods in the Queryable class.

Where, Select, SelectMany
OrderBy, ThenBy, OrderByDescending, ThenByDescending
GroupBy, Join, GroupJoin

string[] names = { "Tom","Dick","Harry","Mary","Jay" };

IEnumerable<string> query =
  from   n in names
  where  n.Length == names.Min (n2 => n2.Length)
  select n;

The let Keyword

The let keyword introduces a new variable alongside the range variable. For instance, suppose that you want to list all names whose length, without vowels, is greater than two characters:

string[] names = { "Tom","Dick","Harry","Mary","Jay" };

IEnumerable<string> query =
  from n in names
  let vowelless = Regex.Replace (n, "[aeiou]", "")
  where vowelless.Length > 2
  orderby vowelless
  select n + " - " + vowelless;

The output from enumerating this query is:

Dick - Dck
Harry - Hrry
Mary - Mry

The let clause performs a calculation on each element, without losing the original element. In our query, the subsequent clauses (where, orderby, and select) have access to both n and vowelless. A query can include multiple let clauses, and they can be interspersed with additional where and join clauses.

The compiler translates the let keyword by projecting into a temporary anonymous type that contains both the original and transformed elements:

IEnumerable<string> query = names
 .Select (n => new  
   {
     n = n, 
     vowelless = Regex.Replace (n, "[aeiou]", "")
   }
 )
 .Where (temp0 => (temp0.vowelless.Length > 2))
 .OrderBy (temp0 => temp0.vowelless)
 .Select (temp0 => ((temp0.n + " - ") + temp0.vowelless))

Query Continuations

If you want to add clauses after a select or group clause, you must use the into keyword to “continue” the query. For instance:

from c in "The quick brown tiger".Split()
select c.ToUpper() into upper
where upper.StartsWith ("T")
select upper

// RESULT: "THE", "TIGER"

Following an into clause, the previous range variable is out of scope.

The compiler translates queries with an into keyword simply into a longer chain of operators:

"The quick brown tiger".Split()
   .Select (c => c.ToUpper())
   .Where (upper => upper.StartsWith ("T"))

(It omits the final Select(upper=>upper) because it’s redundant.)

Multiple Generators

A query can include multiple generators (from clauses). For example:

int[] numbers = { 1, 2, 3 };
string[] letters = { "a", "b" };

IEnumerable<string> query = from n in numbers
                            from l in letters
                            select n.ToString() + l;

The result is a cross product, rather like you’d get with nested foreach loops:

"1a", "1b", "2a", "2b", "3a", "3b"

When there’s more than one from clause in a query, the compiler emits a call to SelectMany:

IEnumerable<string> query = numbers.SelectMany (
   n => letters,
   (n, l) => (n.ToString() + l));

SelectMany performs nested looping. It enumerates every element in the source collection (numbers), transforming each element with the first lambda expression (letters). This generates a sequence of subsequences, which it then enumerates. The final output elements are determined by the second lambda expression (n.ToString()+l).

If you subsequently apply a where clause, you can filter the cross product and project a result akin to a join:

string[] players = { "Tom", "Jay", "Mary" };

IEnumerable<string> query =
  from name1 in players
  from name2 in players
  where name1.CompareTo (name2) < 0
  orderby name1, name2
  select name1 + " vs " + name2;

RESULT: { "Jay vs Mary", "Jay vs Tom", "Mary vs Tom" }

The translation of this query into fluent syntax is more complex, requiring a temporary anonymous projection. The ability to perform this translation automatically is one of the key benefits of query expressions.

The expression in the second generator is allowed to use the first range variable:

string[] fullNames =
  { "Anne Williams", "John Fred Smith", "Sue Green" };

IEnumerable<string> query =
  from fullName in fullNames
  from name in fullName.Split()
  select name + " came from " + fullName;

Anne came from Anne Williams
Williams came from Anne Williams
John came from John Fred Smith

This works because the expression fullName.Split emits a sequence (an array of strings).

Multiple generators are used extensively in database queries, to flatten parent-child relationships and to perform manual joins.

Joining

LINQ provides three joining operators, the main ones being Join and GroupJoin, which perform keyed lookup-based joins. Join and GroupJoin support only a subset of the functionality you get with multiple generators/SelectMany, but are more performant with local queries because they use a hashtable-based lookup strategy rather than performing nested loops. (With Entity Framework queries, the joining operators have no advantage over multiple generators.)

Join and GroupJoin support only equi-joins (i.e., the joining condition must use the equality operator). There are two methods: Join and GroupJoin. Join emits a flat result set, whereas GroupJoin emits a hierarchical result set.

Following is the query expression syntax for a flat join:

from outer-var in outer-sequence
join inner-var in inner-sequence 
  on outer-key-expr equals inner-key-expr

For example, given the following collections

var customers = new[]
{
  new { ID = 1, Name = "Tom" },
  new { ID = 2, Name = "Dick" },
  new { ID = 3, Name = "Harry" }
};
var purchases = new[]
{
  new { CustomerID = 1, Product = "House" },
  new { CustomerID = 2, Product = "Boat" },
  new { CustomerID = 2, Product = "Car" },
  new { CustomerID = 3, Product = "Holiday" }
};

we could perform a join as follows:

IEnumerable<string> query =
  from c in customers
  join p in purchases on c.ID equals p.CustomerID
  select c.Name + " bought a " + p.Product;

The compiler translates this to:

customers.Join (                // outer collection
  purchases,                    // inner collection
  c => c.ID,                    // outer key selector
  p => p.CustomerID,            // inner key selector
  (c, p) =>                     // result selector
     c.Name + " bought a " + p.Product 
);

Here’s the result:

Tom bought a House
Dick bought a Boat
Dick bought a Car
Harry bought a Holiday

With local sequences, Join and GroupJoin are more efficient at processing large collections than SelectMany because they first preload the inner sequence into a keyed hashtable-based lookup. With a database query, however, you could achieve the same result equally efficiently as follows:

from c in customers
from p in purchases
where c.ID == p.CustomerID
select c.Name + " bought a " + p.Product;

IEnumerable<IEnumerable<Purchase>> query =
  from c in customers
  join p in purchases on c.ID equals p.CustomerID
  into custPurchases
  select custPurchases;   // custPurchases is a sequence

foreach (IEnumerable<Purchase> purchaseSequence in query)
  foreach (Purchase p in purchaseSequence)
    Console.WriteLine (p.Description);

from c in customers
join p in purchases on c.ID equals p.CustomerID
into custPurchases
select new { CustName = c.Name, custPurchases };

from c in customers
select new
{
  CustName = c.Name,
  custPurchases = 
    purchases.Where (p => c.ID == p.CustomerID)
}

int[] numbers = { 3, 5, 7 };
string[] words = { "three", "five", "seven", "ignored" };
IEnumerable<string> zip = 
  numbers.Zip (words, (n, w) => n + "=" + w);

3=three
5=five
7=seven

Ordering

The orderby keyword sorts a sequence. You can specify any number of expressions upon which to sort:

string[] names = { "Tom","Dick","Harry","Mary","Jay" };

IEnumerable<string> query = from n in names
                            orderby n.Length, n
                            select n;

This sorts first by length and then by name, yielding this result:

Jay, Tom, Dick, Mary, Harry

The compiler translates the first orderby expression to a call to OrderBy, and subsequent expressions to a call to ThenBy:

IEnumerable<string> query = names
   .OrderBy (n => n.Length)
   .ThenBy (n => n)

The ThenBy operator refines rather than replaces the previous sorting.

You can include the descending keyword after any of the orderby expressions:

orderby n.Length descending, n

This translates to the following:

.OrderByDescending (n => n.Length).ThenBy (n => n)

Grouping

GroupBy organizes a flat input sequence into sequences of groups. For example, the following groups a sequence of names by their length:

string[] names = { "Tom","Dick","Harry","Mary","Jay" };

var query = from name in names
            group name by name.Length;

The compiler translates this query into the following:

IEnumerable<IGrouping<int,string>> query = 
   names.GroupBy (name => name.Length);

Here’s how to enumerate the result:

foreach (IGrouping<int,string> grouping in query)
{
  Console.Write ("
 Length=" + grouping.Key + ":");
  foreach (string name in grouping)
    Console.Write (" " + name);
}

 Length=3: Tom Jay
 Length=4: Dick Mary
 Length=5: Harry

Enumerable.GroupBy works by reading the input elements into a temporary dictionary of lists so that all elements with the same key end up in the same sublist. It then emits a sequence of groupings. A grouping is a sequence with a Key property:

public interface IGrouping <TKey,TElement>
  : IEnumerable<TElement>, IEnumerable
{
  // Key applies to the subsequence as a whole
  TKey Key { get; }    
}

By default, the elements in each grouping are untransformed input elements, unless you specify an elementSelector argument. The following projects each input element to uppercase:

from name in names
group name.ToUpper() by name.Length

which translates to this:

names.GroupBy (
  name => name.Length, 
  name => name.ToUpper() )

The subcollections are not emitted in order of key. GroupBy does no sorting (in fact, it preserves the original ordering). To sort, you must add an OrderBy operator (which means first adding an into clause, because group by ordinarily ends a query):

from name in names
group name.ToUpper() by name.Length into grouping
orderby grouping.Key
select grouping

Query continuations are often used in a group by query. The next query filters out groups that have exactly two matches in them:

from name in names
group name.ToUpper() by name.Length into grouping
where grouping.Count() == 2
select grouping

OfType and Cast

OfType and Cast accept a nongeneric IEnumerable collection and emit a generic IEnumerable<T> sequence that you can subsequently query:

var classicList = new System.Collections.ArrayList();
classicList.AddRange ( new int[] { 3, 4, 5 } );
IEnumerable<int> sequence1 = classicList.Cast<int>();

This is useful because it allows you to query collections written prior to C# 2.0 (when IEnumerable<T> was introduced), such as ControlCollection in System.Windows.Forms.

Cast and OfType differ in their behavior when encountering an input element that’s of an incompatible type: Cast throws an exception, whereas OfType ignores the incompatible element.

The rules for element compatibility follow those of C#’s is operator. Here’s the internal implementation of Cast:

public static IEnumerable<TSource> Cast <TSource>
             (IEnumerable source)
{
  foreach (object element in source)
    yield return (TSource)element;
}

C# supports the Cast operator in query expressions—simply insert the element type immediately after the from keyword:

from int x in classicList ...

This translates to the following:

from x in classicList.Cast <int>() ...