Nullable Reference Types

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Make null visible to the compiler: nullable context, string vs string?, warnings, null checks, !, ??, ??=, nullable attributes, legacy code and avoiding NullReferenceException.

Introduction to Nullable Reference Types

Think about a form with some boxes marked required and some marked optional.

Whoever reads the form knows straight away: the "Name" box always has a value, but the "Middle name" box might be empty. Nobody is surprised by an empty optional box.

Old C# code had no such marks. Any string, any Customer, any object reference could secretly be null. If you forgot to check, your program crashed with the most common .NET error of all:

System.NullReferenceException: Object reference not set to an instance of an object.

Nullable reference types add labels to mark which types can be null and which cannot:

• string means "never null".
• string? means "might be null".

The compiler then checks your code and warns you whenever you might use a null by mistake, before the program runs.

In simple words: ? says "this can be empty", and the compiler makes sure you check before you use it.

Easy Way to Remember: no ? = always has a value. ? = check first.

What You Will Learn

In this lesson, you will learn:

1. How to turn on the nullable context.
2. The difference between string and string?.
3. What the nullability warnings mean.
4. Null checks the compiler understands.
5. The null-forgiving operator !.
6. The null-coalescing operators ?? and ??=.
7. Nullable attributes such as [NotNullWhen].
8. How to add nullability to older code.
9. Habits that prevent NullReferenceException.

Start With a Working Example

Press Run, then hover over the squiggly line in the editor.

The compiler warns before the crash

#nullable enable
using System;

string name = "Asha";
string? nickname = FindNickname("Asha");     // might be null

Console.WriteLine($"Name length: {name.Length}");

// Warning CS8602: Dereference of a possibly null reference.
// The compiler knows nickname might be null here.
try
{
    Console.WriteLine($"Nickname length: {nickname.Length}");
}
catch (NullReferenceException)
{
    Console.WriteLine("Crash! The warning was right.");
}

// The fix: check first.
if (nickname is not null)
    Console.WriteLine($"Nickname length: {nickname.Length}");
else
    Console.WriteLine("No nickname");

static string? FindNickname(string name) => null;

The compiler marked nickname.Length with a warning before you ran anything. Running it proved the warning right. The checked version below it has no warning.

Nullable Context

The nullable context is the switch that turns this feature on. When it is on, the compiler treats string as non-null and string? as nullable, and it gives warnings.

There are three ways to turn it on:

1. For the whole project, in the .csproj file. New projects created with dotnet new already have this:

<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>

2. For one file or part of a file, with a directive:

#nullable enable       // on from here
#nullable disable      // off from here
#nullable restore      // back to the project setting

3. Warnings only, or annotations only, for gradual migration:

#nullable enable warnings      // warn, but treat old code as "unknown"
#nullable enable annotations   // allow ? marks, but no warnings yet

Nullable References

With the context on, every reference type has two forms:

This is the same ? you already know from nullable value types such as int?. There is one big difference:

• int? is a different runtime type: Nullable<int>, with .HasValue and .Value.
• string? is the same runtime type as string. The ? is only a note for the compiler.

Nullable value types versus nullable reference types

#nullable enable
using System;

int? age = null;              // Nullable<int>: a real wrapper type
Console.WriteLine($"age.HasValue: {age.HasValue}");
Console.WriteLine($"int? runtime type:    {typeof(int?).Name}");

string? city = null;          // still just a string at runtime
Console.WriteLine($"city is null: {city is null}");
Console.WriteLine($"string? runtime type: {typeof(string).Name}");

city = "Pune";
Console.WriteLine($"Now city has {city.Length} letters");   // no warning: the compiler saw the assignment

The last line has no warning. The compiler tracks the value: after city = "Pune", it knows city is not null. This tracking is called flow analysis.

Nullability Warnings

Warnings about nullability all have numbers starting with CS86. These are the main ones you will see:

Common warnings in one place

#nullable enable
using System;

var customer = new Customer("Ravi");
Console.WriteLine(customer.Describe());

string? input = Console.ReadLine();        // null when there is no input
string city = input ?? "Unknown";          // fixed with ?? (no CS8600)
Console.WriteLine($"City: {city}");

class Customer
{
    public string Name { get; }
    public string? Email { get; set; }     // optional: fine to leave null
    public string Phone { get; set; } = "";// required-ish: given a default (no CS8618)

    public Customer(string name) => Name = name;

    public string Describe()
    {
        // Email.Length here would be CS8602, so we check:
        string email = Email ?? "(no email)";
        return $"{Name}, {email}, phone '{Phone}'";
    }
}

Null Checks

The compiler's flow analysis understands normal null checks. After a check, it knows the variable is safe, and the warning goes away.

The compiler understands these null checks:

• if (x is not null) { ... }
• if (x != null) { ... }
• if (x is null) return; (an early exit)
• if (x is { } value) { ... } (a property pattern)
• if (string.IsNullOrEmpty(x)) return;
• ArgumentNullException.ThrowIfNull(x);

Different null checks

#nullable enable
using System;

PrintLength("Chennai");
PrintLength(null);
Greet(new User("Meera"));
Greet(null);

static void PrintLength(string? text)
{
    if (text is null)
    {
        Console.WriteLine("No text");
        return;                                   // early exit
    }
    Console.WriteLine($"{text} has {text.Length} letters");   // safe here
}

static void Greet(User? user)
{
    if (user is { Name: var name })               // pattern: not null, and grab Name
        Console.WriteLine($"Hello, {name}");
    else
        Console.WriteLine("Hello, guest");
}

record User(string Name);

The Null-Conditional Operator ?.

?. safely reads a member only if the object is not null. If the object is null, the entire expression becomes null instead of crashing.

Safe member access with ?.

#nullable enable
using System;

Order? found = new Order(new Address("Kochi"));
Order? missing = null;

Console.WriteLine(found?.ShipTo?.City ?? "no city");
Console.WriteLine(missing?.ShipTo?.City ?? "no city");

int? length = missing?.ShipTo?.City.Length;    // int? because the chain might stop
Console.WriteLine($"Length: {length?.ToString() ?? "null"}");

record Address(string City);
record Order(Address? ShipTo);

Checking Arguments

For public methods, reject null arguments at the start. Then the rest of the method knows these arguments are safe to use.

public void Ship(Order order, string address)
{
    ArgumentNullException.ThrowIfNull(order);
    ArgumentException.ThrowIfNullOrWhiteSpace(address);
    ...
}

Null-Forgiving Operator (!)

Sometimes you know a value is not null, but the compiler cannot prove it. The null-forgiving operator ! tells the compiler: "trust me, this is not null." It removes the warning.

Telling the compiler you know better

#nullable enable
using System;
using System.Collections.Generic;

var prices = new Dictionary<string, decimal> { ["Pen"] = 10m, ["Notebook"] = 60m };

// Find returns string? because it might find nothing...
string? first = new List<string> { "Pen", "Notebook" }.Find(x => x.StartsWith("P"));

// ...but we just put "Pen" in the list, so we know it is found.
Console.WriteLine($"Found: {first!.ToUpper()}");

// A bad use of ! : this really can be null.
string? missing = new List<string> { "Pen" }.Find(x => x.StartsWith("Z"));
try
{
    Console.WriteLine(missing!.ToUpper());     // no warning, but still a crash
}
catch (NullReferenceException)
{
    Console.WriteLine("! only hides the warning. It does not make the value safe.");
}

null! is a common pattern for a field that a framework fills in later, such as an Entity Framework navigation property:

public Customer Customer { get; set; } = null!;   // EF sets this when loading

Null-Coalescing Operator (??)

?? provides a fallback value when the left side is null.

result = value ?? fallback;

• If value is not null, result is value.
• If value is null, result is fallback.

The result of x ?? "default" is always non-nullable. Use ?? to convert a string? into a string.

Fallbacks with ??

#nullable enable
using System;
using System.Collections.Generic;

var settings = new Dictionary<string, string?>
{
    ["Theme"] = "Dark",
    ["Language"] = null,
};

string theme = settings.GetValueOrDefault("Theme") ?? "Light";
string language = settings.GetValueOrDefault("Language") ?? "en-IN";
string font = settings.GetValueOrDefault("Font") ?? "Segoe UI";

Console.WriteLine($"{theme}, {language}, {font}");

// ?? can be chained: the first non-null wins
string? fromUser = null, fromCompany = null, fromSystem = "UTC+05:30";
Console.WriteLine($"Time zone: {fromUser ?? fromCompany ?? fromSystem ?? "UTC"}");

// ?? can throw when a value is required
try
{
    string apiKey = settings.GetValueOrDefault("ApiKey") ?? throw new InvalidOperationException("ApiKey is missing");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Null-Coalescing Assignment (??=)

??= assigns a value only if the variable is currently null.

x ??= value;     // same as: if (x is null) x = value;

It is perfect for lazy initialisation: creating something the first time it is needed.

Create on first use with ??=

#nullable enable
using System;
using System.Collections.Generic;

var cache = new PriceCache();
Console.WriteLine(cache.Get("Pen"));
Console.WriteLine(cache.Get("Notebook"));
Console.WriteLine(cache.Get("Pen"));

class PriceCache
{
    private Dictionary<string, decimal>? _prices;     // not loaded yet

    public decimal Get(string item)
    {
        _prices ??= Load();                             // loads only the first time
        return _prices[item];
    }

    private static Dictionary<string, decimal> Load()
    {
        Console.WriteLine("(loading prices)");
        return new() { ["Pen"] = 10m, ["Notebook"] = 60m };
    }
}

Nullable Annotations

Sometimes ? is not enough to describe how a method behaves. Think about int.TryParse-style methods: the output is null when the method returns false, and not null when it returns true.

Nullable attributes in System.Diagnostics.CodeAnalysis describe these rules, so the compiler understands your methods:

Teach the compiler about your TryFind method

#nullable enable
using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;

var phoneBook = new PhoneBook();

if (phoneBook.TryFind("Asha", out string? number))
    Console.WriteLine($"Asha: {number.Length} digits, {number}");   // no warning: number is not null here
else
    Console.WriteLine("Asha not found");

if (!phoneBook.TryFind("Zoya", out string? other))
    Console.WriteLine($"Zoya not found (value is {other ?? "null"})");

class PhoneBook
{
    private readonly Dictionary<string, string> _numbers = new() { ["Asha"] = "9840012345" };

    public bool TryFind(string name, [NotNullWhen(true)] out string? number)
        => _numbers.TryGetValue(name, out number);
}

Without [NotNullWhen(true)], number.Length inside the if would get a CS8602 warning, because number is declared string?. The attribute tells the compiler how the method behaves.

Required Members

For properties that must be set when an object is created, the cleanest fix for warning CS8618 is the required modifier:

required fixes CS8618 without fake defaults

#nullable enable
using System;

var product = new Product { Name = "Desk Lamp", Sku = "DL-204" };
Console.WriteLine($"{product.Name} ({product.Sku}), note: {product.Note ?? "none"}");

// var bad = new Product { Name = "Lamp" };   // error CS9035: required member 'Sku' must be set

class Product
{
    public required string Name { get; init; }
    public required string Sku { get; init; }
    public string? Note { get; init; }
}

Working with Legacy Code

Most real projects have old code written before nullable reference types. Turning the feature on for a big project at once can produce thousands of warnings. Migrate step by step instead.

A Safe Migration Plan

1. Turn on warnings for new files only. Add #nullable enable at the top of each new file, or each file you touch.
2. Start at the bottom. Annotate small, shared classes first (models, helpers). Code that uses them gets better warnings for free.
3. Annotate public APIs. Decide for every parameter and return value: can this be null? Add ? where yes.
4. Fix warnings, do not hide them. Use checks and ?? before reaching for !.
5. Flip the project switch to <Nullable>enable</Nullable> when most files are done.
6. Make nullable warnings errors to keep it clean.

Oblivious Code

Code compiled with nullable off is called oblivious. The compiler does not know whether its types can be null or not, so you get no warnings when you use them. Treat values from oblivious code as possibly null and check them.

Mixing old and new code in one file

#nullable disable
static class LegacyLookup
{
    // Written before nullable reference types: may return null with no warning.
    public static string FindManager(string employee) => employee == "Asha" ? "Ravi" : null;
}

#nullable enable
static class Program
{
    static void Main()
    {
        foreach (string employee in new[] { "Asha", "Kiran" })
        {
            string? manager = LegacyLookup.FindManager(employee);   // treat old results as maybe-null
            Console.WriteLine($"{employee} reports to {manager ?? "nobody yet"}");
        }
    }
}

The FindManager method can return null but says string. The compiler cannot help you there, so the new code stores the result in a string? and checks it.

Preventing Null Reference Exceptions

Nullable reference types catch most problems at compile time. A few habits close the rest of the gaps:

1. Turn nullable on in every project, and treat its warnings as errors.
2. Prefer non-null designs. Return an empty list, not null. Use a "null object" (like a NullLogger) instead of null.
3. Validate at the edges. Check arguments in public methods with ArgumentNullException.ThrowIfNull. Check data from JSON, databases and users as it enters your program.
4. Use required and constructors so objects are complete when created.
5. Use ?., ?? and ??= for optional values instead of long if chains.
6. Use ! rarely, and only with a comment that explains why it is safe.
7. Use TryXxx patterns with [NotNullWhen] for lookups that might fail.

Return empty, not null

#nullable enable
using System;
using System.Collections.Generic;

foreach (string customer in new[] { "Asha", "New Customer" })
{
    IReadOnlyList<string> orders = GetOrders(customer);
    Console.WriteLine($"{customer}: {orders.Count} order(s)");   // no null check needed
}

static IReadOnlyList<string> GetOrders(string customer) =>
    customer == "Asha"
        ? new[] { "ORD-1001", "ORD-1007" }
        : Array.Empty<string>();          // empty, never null

Callers never have to ask "is it null?" because the answer is always a list, maybe an empty one.

Where Nullable Reference Types Are Used

• All new .NET projects, which enable <Nullable> by default.
• The .NET libraries themselves, which are fully annotated.
• ASP.NET Core model binding and validation, where non-nullable properties are treated as required.
• Entity Framework Core, which makes non-nullable string properties NOT NULL columns.
• Library authors, who publish annotations so their users get warnings too.

Common mistakes

What to Remember

• Nullable reference types make "might be null" visible: string never null, string? maybe null.
• Turn them on with <Nullable>enable</Nullable> or #nullable enable.
• The compiler tracks values and warns with CS86xx codes before the program runs.
• Check with is null, is not null, patterns, ?. or early returns.
• ! only silences the compiler; it does not make a value safe.
• ?? supplies a fallback; ??= assigns only when the value is null.
• Attributes such as [NotNullWhen(true)] describe tricky methods to the compiler.
• Migrate old code file by file, and treat oblivious values as possibly null.
• Prefer designs where null cannot happen: required, empty collections and null objects.

Next: Logging