What are nullable reference types in C#? Explain the annotations (? and !), how the compiler's null-state flow analysis works, attributes such as [NotNullWhen] and [MemberNotNull], and their limits at run time.

1. How annotations are stored

Because string? is still System.String, the compiler records nullability in metadata attributes:

• [Nullable(1)] = not-null, [Nullable(2)] = maybe-null, [Nullable(0)] = oblivious. For generic types, a byte array encodes each type argument (Dictionary<string, List<string?>> → [1, 1, 1, 2]).
• [NullableContext(n)] on a type or method sets the default to shrink metadata.
• At run time, NullabilityInfoContext (.NET 6+) reads these attributes — ASP.NET Core model binding uses it to infer [Required] for non-nullable properties, which is why enabling NRT can suddenly make API fields required and return 400s.

Code compiled with nullable disabled is "oblivious": its types are treated as neither nullable nor non-nullable, so no warnings appear when consuming it.

2. The two contexts: annotation and warning

<Nullable> has four values:

This split allows staged migration: first annotate public APIs (annotations), or first see warnings on existing code (warnings), then enable.

3. The flow analysis model

The compiler performs a data-flow pass over the method's control-flow graph, similar to definite assignment:

• Every expression has a null-state. Literals and new are not-null; default and null literals are maybe-null; a read of a declared T? is maybe-null; a read of T is not-null.
• Conditionals split state: in if (x != null) { A } else { B }, x is not-null in A.
• After a dereference (x.Length), the compiler assumes not-null for the rest of the path (it warned once at the dereference).
• Calls invalidate nothing about locals, but fields and properties are trusted to keep their state between calls — the compiler does not assume a method call could null out this.Customer. That is a deliberate unsoundness to avoid warning noise.
• Lambdas are analysed with the state at the point of declaration for captured variables, which can be wrong if the variable is reassigned later.

The analysis is intentionally unsound in several places (fields, arrays, struct defaults, default in generics) to keep false positives manageable. It finds the vast majority of bugs, not all.

4. Generics and nullability

• T? on unconstrained T: for reference types adds nullability; for value types, nothing (not Nullable<T>). So T? FirstOrDefault<T>() returns 0 for int.
• where T : class → T non-nullable reference; where T : class? → any reference type.
• where T : notnull → non-nullable reference or value type (used by Dictionary<TKey, ...>'s key).
• [MaybeNull] T / [return: MaybeNull] were the pre-C# 9 way of expressing "may return default".

5. required members and constructors

CS8618 (non-nullable field not initialised) is the most common warning in DTOs. Options, from best to worst:

1. Constructor or primary constructor parameters (records do this naturally).
2. required modifier (C# 11): public required string Email { get; init; } — the compiler forces object initialisers to set it, and System.Text.Json (.NET 7+) honours required during deserialisation.
3. Initialise to a sensible value (= string.Empty;, = [];) when empty is meaningful.
4. = null!; — only for framework-populated properties, such as EF Core navigation properties.

6. Interaction with EF Core and ASP.NET Core

• EF Core: string Name → nvarchar(...) NOT NULL; string? Notes → nullable column. Required navigation properties are configured from annotations. Enabling NRT on an existing model can generate migrations that change column nullability — review them carefully.
• MVC model binding / minimal APIs: non-nullable reference properties are implicitly required (SuppressImplicitRequiredAttributeForNonNullableReferenceTypes turns this off). A missing field becomes a 400 validation error instead of a null.
• Options pattern: use [Required] plus ValidateDataAnnotations().ValidateOnStart() because configuration binding does not respect NRT.

7. Migration strategy for a large codebase

1. Enable in new projects and leaf libraries first (no dependants to break).
2. Annotate public contracts first — every consumer benefits.
3. Use #nullable enable per file for gradual adoption in big projects.
4. Fix warnings by understanding intent, not by !. Track warning counts in CI.
5. Turn nullable warnings into errors once clean, so they never regress.

Try it yourself

1. Write bool TryFind(int id, out Customer? c) and observe the warning when using c after true; add [NotNullWhen(true)].
2. Create a class with an Initialize() method that sets a field and fix CS8618 with [MemberNotNull].
3. Deserialise {} into a record with a non-nullable string Name and observe it is null; then enable RespectNullableAnnotations.
4. Inspect a compiled assembly in ILSpy and find the NullableAttribute bytes.

using System.Diagnostics.CodeAnalysis;
using System.Text.Json;

namespace Types;

public sealed class Customer
{
    public required string Name { get; init; }      // must be set by initialiser
    public string? MiddleName { get; init; }        // optional
    public string Email { get; init; } = string.Empty;

    public string DisplayName =>
        MiddleName is { Length: > 0 } middle ? $"{Name} {middle[0]}." : Name;
}

public sealed class CustomerRepository
{
    private readonly Dictionary<int, Customer> _byId = new();
    private List<Customer> _cache;

    public CustomerRepository() => Reload();

    [MemberNotNull(nameof(_cache))]
    private void Reload() => _cache = [.. _byId.Values];

    public bool TryFind(int id, [NotNullWhen(true)] out Customer? customer)
        => _byId.TryGetValue(id, out customer);

    public Customer? Find(int id) => _byId.GetValueOrDefault(id);

    public void Add(Customer customer)
    {
        ArgumentNullException.ThrowIfNull(customer);   // still validate public inputs
        _byId[_byId.Count + 1] = customer;
        Reload();
    }
}

public static class NrtDemo
{
    public static void Main()
    {
        var repo = new CustomerRepository();
        repo.Add(new Customer { Name = "Ada" });

        if (repo.TryFind(1, out var c))
            Console.WriteLine(c.DisplayName);          // no warning: NotNullWhen(true)

        Customer? maybe = repo.Find(42);
        Console.WriteLine(maybe?.Name ?? "not found");

        // Run-time gap: JSON can still produce null unless you opt in
        var options = new JsonSerializerOptions { RespectNullableAnnotations = true };
        try
        {
            JsonSerializer.Deserialize<Customer>("""{"Name":null}""", options);
        }
        catch (JsonException ex)
        {
            Console.WriteLine($"Rejected: {ex.Message}");
        }
    }
}