Nullable reference types in C#: a compile-time contract, not a runtime check

What it is

The C# documentation describes nullable reference types as a group of compile-time features: an annotation context in which reference types are non-nullable unless written with ?, and a warning context in which the compiler performs null-state analysis, tracking whether each expression is not-null or maybe-null and warning when a maybe-null value is dereferenced or assigned to a non-nullable target. The language reference is explicit that there is no runtime difference: string and string? are the same .NET type and the compiler adds no runtime checks. New projects since .NET 6 set <Nullable>enable</Nullable>; older code is nullable-oblivious until the property or a #nullable enable directive is added. Analysis does not look into method bodies, so signatures carry attributes such as [NotNullWhen(true)], [MaybeNullWhen(false)] and [MemberNotNull] to describe post-conditions, and the documentation states that the .NET runtime APIs are annotated as of .NET 5.

Why it matters

Kotlin, Swift and TypeScript (strictNullChecks) engineers expect the type system to enforce null safety; in C# it is a warning layer over an older type system. Two consequences: warnings help only if they fail the build, and a non-nullable parameter can still receive null from reflection, deserialisation, an oblivious assembly or a caller using !.

How to apply

• Enable it project-wide and promote the nullability warnings to errors: the compiler options documentation accepts nullable as a shorthand in <WarningsAsErrors>nullable</WarningsAsErrors>.
• Migrate a large codebase in phases, as the documentation describes: enable warnings or annotations first, or add #nullable enable file by file, then converge on the project-wide setting.
• Validate at trust boundaries anyway: ArgumentNullException.ThrowIfNull(x) in public APIs, and treat deserialised objects as maybe-null until checked.
• Prefer the attributes to !: a TryGet method with [NotNullWhen(true)] out T? value lets callers use the value without suppression.
• Initialise non-nullable members in the constructor, mark helper methods with [MemberNotNull(nameof(field))], or declare the member required.

Pitfalls

The documentation lists two runtime holes the compiler does not warn about: default of a struct with non-nullable reference fields, and new string[3], whose elements are null until assigned. Entity Framework Core reads the annotations to decide whether a column is required, which the reference notes as a behavioural exception. An unconstrained generic T? is not Nullable<T>; it is only that when T is constrained to struct. The ! operator is a promise, not a check, and a wrong promise becomes a NullReferenceException far from its cause.