csharp-nullable-reference-types

C# Nullable Reference Types

When to Use

• Introducing nullable reference types (NRT) into a codebase that has not yet adopted them
• Writing or refactoring C# code that uses T? / nullable annotations
• Annotating APIs with System.Diagnostics.CodeAnalysis nullable attributes
• Designing public/internal APIs where nullability contracts matter
• Wrapping unannotated or legacy APIs so downstream callers still benefit from NRT
• Reviewing code for correct null-state analysis, guard helpers, and the field keyword

Core Goals

• Prevent NullReferenceException at runtime by making null intent explicit in signatures.
• Express contracts the type system cannot represent directly using the official nullable attributes.
• Adopt NRT incrementally in legacy codebases without a big-bang rewrite.

Core Nullability Model

Non-nullable vs nullable

• string — non-nullable reference. The compiler assumes instances are never null; assigning null or a maybe-null value produces a warning.
• string? — nullable reference. The variable may be null; the compiler requires a null check before dereference.

string name = "Alice";
name = null;          // Warning: assigning null to non-nullable.

string? nickname = null;
Console.WriteLine(nickname.Length); // Warning: possible null dereference.

Null-state analysis (flow)

The compiler tracks whether a reference is definitely non-null or maybe null. Null checks and assignments update this state.

string? message = GetMessageOrNull();

if (message != null)
{
    // message is definitely non-null in this block.
    Console.WriteLine(message.Length);
}

// Outside the if, message is maybe null again.

Introduce explicit null checks (if (x != null), is not null, pattern matching) before dereferencing nullable values. Narrow nullability early and keep the non-null state alive. Null-conditional assignment (C# 14) lets you write customer?.Order = CreateOrder(); — the right side is evaluated only when the receiver is non-null.