.CS File Format – Types

Kinds of type

Types fall into value types, reference types, type parameters and, in unsafe code, pointer types. A variable of a value type holds its value directly. A variable of a reference type holds a reference to an object; several variables may refer to the same object.

Value types are sealed (except for inheriting from System.ValueType), cannot be null unless wrapped in Nullable, and are copied on assignment. A reference type’s assignment copies only the reference, which is what makes two variables refer to the same object.

Built-in types

Each keyword is an alias for a type in System. They are the same type: int and System.Int32 can be used interchangeably.

• Types without a keyword, such as Int128, UInt128, Half and BigInteger, are library types.
• decimal is a base-10 type for money and the like. Its operations are exact where the result fits, unlike double.
• Floating-point operations do not throw. They produce infinities and NaN. Integer operations can overflow; see checked and unchecked.
• string has value equality with == (clause 8.2.5), but is a reference type.

Nullable value types

T?, where T is a non-nullable value type, is shorthand for System.Nullable<T> (C# 2, clause 8.3.12). It holds a T or no value.

int? a = 5;
int? b = null;

a.HasValue;              // true
b.GetValueOrDefault();   // 0
b ?? -1;                 // -1
int c = a.Value;         // InvalidOperationException if no value
if (a is int x) { }      // pattern, x is an int

• Operators are lifted to the nullable type (clause 12.4.8): if either operand of + and other arithmetic is null, the result is null.
• The relational operators <, >, <= and >= return false if either operand is null.
• bool? has three-valued & and | (clause 12.16.5): false & null is false, and true | null is true.
• Boxing a nullable value with no value gives a null reference; otherwise it boxes the T (clause 8.3.13).

Nullable reference types

Nullable reference types (C# 8, clause 8.9) add warnings to help avoid null reference errors. They change no behaviour at run time: string? and string are both System.String. The context they apply in is set by #nullable or the project’s Nullable property.

#nullable enable
string name = "Ann";        // not nullable
string? middle = null;      // nullable reference

int a = name.Length;        // fine
int b = middle.Length;      // warning: possible null dereference
int c = middle?.Length ?? 0;
int d = middle!.Length;     // ! silences the warning only

The compiler tracks the null state of each expression through the code. A ? on a type says that null is expected; without it, null is unexpected. The null-forgiving operator ! (clause 12.8.9) has no effect at run time. Library attributes in System.Diagnostics.CodeAnalysis describe what a method does about null; see Attributes.

Boxing and unboxing

Converting a value type to object, to System.ValueType, or to an interface it implements boxes it: the value is copied into an object on the heap (clause 8.3.13). Converting back unboxes it, and copies the value out.

int i = 42;
object box = i;         // boxing
int j = (int)box;       // unboxing
long l = (long)box;     // InvalidCastException: the box holds an int
object n = null;
int k = (int)n;         // NullReferenceException

Unboxing must name the exact value type, or its nullable form. A ref struct cannot be boxed.

Conversions

A conversion changes an expression from one type to another (clause 10). An implicit conversion needs no syntax. An explicit conversion needs a cast, (T)x. Conversions exist between built-in types and can be user-defined.

Dynamic

The dynamic type (C# 4, clauses 8.2.4 and 8.7) tells the compiler to bind operations at run time. It is object in the compiled code, with an attribute recording that it is dynamic. Any expression converts implicitly to it, and it converts implicitly to any type. Errors appear at run time as exceptions.

dynamic d = "hello";
Console.WriteLine(d.Length);   // 5, found at run time
d = 12;
int n = d + 1;                 // 13
d.NoSuchMember();              // RuntimeBinderException

Tuples

A tuple groups values in a lightweight value type (C# 7.0, clause 8.3.11). The compiler maps it to System.ValueTuple, whose fields are mutable. Element names exist only in source code.

(int Sum, int Count) t = (6, 3);
t.Sum;            // 6
t.Item1;          // 6, the field name
var pair = (1, "a");
var named = (x: 1, y: 2);

int a = 1, b = 2;
var inferred = (a, b);    // named a and b, C# 7.1

(int sum, int count) = t;       // deconstruction
(a, b) = (b, a);                // swap
var same = (1, 2) == (1, 2);    // true, C# 7.3

Tuples with more than seven elements nest the rest in a Rest field. Elements can be matched with positional patterns and split with deconstruction.

Arrays

An array is a reference type holding elements of one type, indexed from zero (clause 17). Every array derives from System.Array. T[] also implements IList<T>.

int[] a = new int[3];                 // zeros
int[] b = new int[] { 1, 2, 3 };
int[] c = { 1, 2, 3 };                // initialiser in a declaration
int[] d = [1, 2, 3];                  // collection expression, C# 12
int[,] grid = new int[2, 3];          // rectangular
int[][] jagged = new int[2][];        // array of arrays
a[^1];                                // last element, C# 8
b[1..3];                              // a copy of a range, C# 8

An out-of-range index throws IndexOutOfRangeException. Arrays of a reference type are covariant: object[] o = new string[1]; compiles, but storing a value of the wrong type throws ArrayTypeMismatchException (clause 17.6).

Anonymous types

An anonymous type (C# 3) is a class generated by the compiler from an object initialiser: var p = new { Name = "Ann", Age = 30 };. Properties are read-only and Equals compares them. Members of the same name and type, in the same order, in the same assembly, share a type. They can be copied with with (C# 10).

Union types

A union type (C# 15, in .NET 11) holds a value of one of a fixed list of case types. Unlike the rest of this page it has no clause number yet: it is described by the Unions feature specification. The .NET 11 SDK is still at the release candidate stage.

public record class Cat(string Name);
public record class Dog(string Name, string Breed);

public union Pet(Cat, Dog);

Pet pet = new Dog("Rex", "Labrador");   // union conversion from each case type

string name = pet switch
{
    Dog d => d.Name,
    Cat c => c.Name,
};

• The compiler turns a union declaration into a struct marked with [System.Runtime.CompilerServices.Union] that implements IUnion. It has one public constructor per case type and a Value property of type object?, and value-type cases are boxed.
• Any type that converts to object can be a case type: classes, structs, interfaces, type parameters, nullable types and other unions.
• A body may add members, except instance fields, auto-properties and field-like events. Declared constructors must delegate to a generated constructor with this(…).
• A type or declaration pattern on a union tests its contents; see Patterns.
• A default union value contains null, so a null arm is advisable where default values can occur.
• Any class or struct with a [Union] attribute that follows the union pattern is also a union type. It can use other storage, such as without boxing.

Implicit typing

var asks the compiler to infer a local variable’s type from its initialiser. The variable is still statically typed. See Variables. A target-typed expression such as new() takes its type from where it is used.