Nullable reference types and flow analysis

An export of 1,200 customers stopped at row 412 with NullReferenceException: one customer had no email address, and the code called customer.Email.Trim(). The type string had always allowed null, and nothing at compile time said which strings might be missing.

Nullable reference types put that information into the types, and the compiler checks it. You will turn them on, read the warnings they raise, and write null checks that the compiler can follow, so that a build without warnings means every read was checked.

string? says a reference may be null, and the compiler checks the rest

With nullable reference types on, string means a string that is never null, and string? one that may be. New projects have had them on since the .NET 6 templates, through <Nullable>enable</Nullable> in the project file, and so do file-based apps: the project that dotnet project convert writes for one sets it too. warnings/Program.cs breaks the rules in four ways, and the session builds and runs it:

// Four kinds of nullable warning. The build still succeeds, and the program runs.
string? found = Lookup("C-101");
string missing = Lookup("C-102");
Console.WriteLine($"found has {found.Length} characters");
Send(null);
Console.WriteLine($"City is null: {new Customer().City is null}");
Console.WriteLine($"missing has {missing.Length} characters");

static string? Lookup(string id) => id == "C-101" ? "asha@example.com" : null;

static void Send(string address) => Console.WriteLine($"sending to {address ?? "nobody"}");

class Customer
{
    public string City { get; set; }
}

from session import run

# warnings builds with four kinds of nullable warning, and then runs until it reads the null it was warned about.
run("""
cd warnings
dotnet build -v q
!dotnet bin/Debug/net10.0/App.dll
""")

$ cd warnings
$ dotnet build -v q
warnings/Program.cs(15,19): warning CS8618: Non-nullable property 'City' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the property as nullable. [warnings/App.csproj]
warnings/Program.cs(3,18): warning CS8600: Converting null literal or possible null value to non-nullable type. [warnings/App.csproj]
warnings/Program.cs(4,32): warning CS8602: Dereference of a possibly null reference. [warnings/App.csproj]
warnings/Program.cs(5,6): warning CS8625: Cannot convert null literal to non-nullable reference type. [warnings/App.csproj]
warnings/Program.cs(7,34): warning CS8602: Dereference of a possibly null reference. [warnings/App.csproj]

Build succeeded.

warnings/Program.cs(15,19): warning CS8618: Non-nullable property 'City' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the property as nullable. [warnings/App.csproj]
warnings/Program.cs(3,18): warning CS8600: Converting null literal or possible null value to non-nullable type. [warnings/App.csproj]
warnings/Program.cs(4,32): warning CS8602: Dereference of a possibly null reference. [warnings/App.csproj]
warnings/Program.cs(5,6): warning CS8625: Cannot convert null literal to non-nullable reference type. [warnings/App.csproj]
warnings/Program.cs(7,34): warning CS8602: Dereference of a possibly null reference. [warnings/App.csproj]
    5 Warning(s)
    0 Error(s)

Time Elapsed …
$ dotnet bin/Debug/net10.0/App.dll
found has 16 characters
sending to nobody
City is null: True
Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Program.<Main>$(String[] args) in warnings/Program.cs:line 7
[exit status 134]

The build succeeded with five warnings, and each one names a line:

Then the program ran. Line 4 got lucky, because C-101 has an email address, and line 7, which CS8602 pointed at, threw NullReferenceException. The annotations changed nothing at run time: string and string? are both System.String, and the compiler adds no check. Everything nullable reference types do happens while the code compiles.

Flow analysis proves a value is not null before it is read

The compiler gives every expression a null-statenull-state: What the compiler knows about a reference at one point in the code: not-null or maybe-null. Assignments and null checks change it, and reading a maybe-null value draws warning CS8602., not-null or maybe-null, and updates it after each assignment and each null check. That tracking is flow analysisflow analysis: The compiler's tracking of null-state through the statements of a method: it follows assignments, checks, patterns and early returns, but not the bodies of the methods a line calls.. checks/Program.cs reads the same lookups after a check, a pattern, ?? and required:

// The same lookups, written so that flow analysis can prove each value is not null where it is read.
string? found = Lookup("C-101");
if (found is null)
{
    return;
}

Console.WriteLine($"found has {found.Length} characters");

string? missing = Lookup("C-102");
Console.WriteLine(missing is not null ? $"missing has {missing.Length} characters" : "C-102 has no email");

string email = Lookup("C-102") ?? "no-reply@example.com";
Console.WriteLine($"C-102 is sent to {email}");

var customer = new Customer { City = "Pune" };
Console.WriteLine($"{customer.City} has {customer.City.Length} letters");

static string? Lookup(string id) => id == "C-101" ? "asha@example.com" : null;

class Customer
{
    public required string City { get; set; }
}

from session import run

# checks reads the same values after a null check, a pattern, ?? and required: it builds without a warning.
run("""
cd checks
dotnet build -v q
dotnet bin/Debug/net10.0/App.dll
""")

$ cd checks
$ dotnet build -v q

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed …
$ dotnet bin/Debug/net10.0/App.dll
found has 16 characters
C-102 has no email
C-102 is sent to no-reply@example.com
Pune has 4 letters

No warnings. Step through the null-state of each value:

A check that leaves the method, if (found is null) return;, proves found for every line after it. Inside missing is not null ? … : … only the first branch reads missing. ?? gives a value that is never null, and required makes every object initializer set City, which removes CS8618. Microsoft’s guide states the limit: the analysis does not trace into the bodies of methods, so a check hidden inside a helper proves nothing at the call site.

Three tools go beyond these checks. The null-forgiving operatornull-forgiving operator: A ! written after an expression, as in name!: it tells the compiler to treat the expression as not null and removes its nullable warnings. It changes nothing when the program runs. ! tells the compiler that a value is not null, and changes nothing when the program runs. In generic code, T? and the notnull constraint say whether a type argument may be null. #nullable directives and WarningsAsErrors decide where the checks apply and whether a nullable warning stops the build.

The ! operator and the nulls flow analysis cannot see, reproduced Pro: opens with a Pro, Premium or Ultimate pass

Generic code: what T? means for int and for string, measured Pro: opens with a Pro, Premium or Ultimate pass

Stricter builds: nullable warnings as errors, file by file Pro: opens with a Pro, Premium or Ultimate pass

Practise: an address book that builds with warnings as errors

addressbook treats every nullable warning as an error, and its build fails with four. The comment at the top of Program.cs lists the four lines it prints once it builds:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WarningsAsErrors>nullable</WarningsAsErrors>
  </PropertyGroup>

</Project>

// Practice: make this project build with nullable warnings as errors. Change types, add checks, and use ! at most
// once, with a comment that says why it is safe. When it builds, dotnet run prints these four lines:
//   Asha Rao: asha@example.com, 0 characters
//   Ravi Iyer: no email, 11 characters
//   Meena Das: not in the book
//   last search: Meena Das
var book = new AddressBook();
book.Add(new Contact("Asha Rao", "asha@example.com", null));
book.Add(new Contact("Ravi Iyer", null, "98200 11122"));

foreach (string name in new[] { "Asha Rao", "Ravi Iyer", "Meena Das" })
{
    Contact contact = book.Find(name);
    Console.WriteLine($"{name}: {contact.Email.ToLowerInvariant()}, {contact.Phone.Length} characters");
}

Console.WriteLine($"last search: {book.LastSearch}");

class Contact
{
    public Contact(string name, string email, string phone)
    {
        Name = name;
        Email = email;
        Phone = phone;
    }

    public string Name { get; }

    public string Email { get; }

    public string Phone { get; }
}

class AddressBook
{
    private readonly List<Contact> _contacts = [];

    public string LastSearch { get; private set; }

    public void Add(Contact contact) => _contacts.Add(contact);

    public Contact Find(string name)
    {
        LastSearch = name;
        foreach (Contact contact in _contacts)
        {
            if (contact.Name == name)
            {
                return contact;
            }
        }

        return null;
    }
}

from session import run

# The practice project as it starts: built with nullable warnings as errors. The compiler reports its errors in the
# order it finds them, which can change from one build to the next, so they are sorted, each shown once.
run("""
cd addressbook
dotnet build -v q | grep -E "error CS|Error\\(s\\)" | sort -u
""")

$ cd addressbook
$ dotnet build -v q | grep -E "error CS|Error\(s\)" | sort -u
    4 Error(s)
addressbook/Program.cs(39,19): error CS8618: Non-nullable property 'LastSearch' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the property as nullable. [addressbook/App.csproj]
addressbook/Program.cs(54,16): error CS8603: Possible null reference return. [addressbook/App.csproj]
addressbook/Program.cs(8,54): error CS8625: Cannot convert null literal to non-nullable reference type. [addressbook/App.csproj]
addressbook/Program.cs(9,35): error CS8625: Cannot convert null literal to non-nullable reference type. [addressbook/App.csproj]

Then take the self-check on the first two sections, string? and flow analysis: it starts with whichever of them you have answered less well so far.

Interview questions

Fresher · What is the difference between string and string? in C#?

Both are System.String when the program runs: a variable of either type can hold null, and nothing checks it at run time. The difference is a promise that the compiler checks. With nullable reference types on, string promises that the value is never null, so the compiler warns when a value that may be null is assigned to it (CS8600) or when a non-nullable property is left unset (CS8618). string? says the value may be missing, so the compiler warns when it is read without a check (CS8602). The annotations cost nothing at run time, and they turn the question “can this be null?” into a warning at the line where it matters.

Key takeaways

• With nullable reference types on, string means never null and string? means may be null; the compiler warns where the two meet, and the program runs exactly as it would without the annotations.
• CS8600, CS8602, CS8618 and CS8625 point at an assignment, a read, an unset member and a null literal; each marks a line where a null can arrive or be read.
• Flow analysis tracks maybe-null and not-null through assignments, checks, patterns, ?? and required, but not into the bodies of the methods a line calls.