How would you enable nullable reference types across a large existing .NET codebase without stopping feature work?

1. Two contexts: annotations and warnings

Nullable reference types are controlled by two independent switches. The <Nullable> property and the #nullable directive set them together or separately:

The same values work as directives inside a file: #nullable enable, #nullable disable, #nullable enable warnings, #nullable disable annotations and #nullable restore (go back to the project setting). That is what makes file-by-file and region-by-region migration possible.

2. It is a compile-time feature only

 source:   public string Name { get; set; }        public string? Notes { get; set; }
              |                                        |
 compiler: null-state analysis, CS86xx warnings  <-- all of the checking happens here
              |
 IL:       [Nullable(1)] string Name               [Nullable(2)] string Notes
           (metadata for other compilers and tools; the runtime ignores it)
              |
 runtime:  both are just System.String references. Null can still arrive.

Null can still reach a non-nullable string from:

• callers compiled with nullable disabled, or from other .NET languages;
• reflection, serialisers, ORMs and model binders that set properties directly;
• default structs and arrays (new string[10] holds ten nulls);
• the ! operator, which tells the compiler to stop checking.

So validation at trust boundaries stays: ArgumentNullException.ThrowIfNull on public entry points, and model validation on API requests.

3. How flow analysis works

The compiler tracks a null state for every expression: not-null or maybe-null.

string? preferred = customer.PreferredName;   // maybe-null (declared string?)

if (preferred is null)                         // after this branch...
    return customer.LegalName;

return preferred.ToUpperInvariant();           // ...not-null here, no warning

It understands is null, is not null, == null, ??, ??=, ?., pattern matching and throw expressions. It does not follow calls into other methods unless those methods carry attributes that describe their behaviour, which is what section 5 is about.

Two things it deliberately doesn't track well:

• Fields across method calls. After calling another method, the compiler can't know whether _cache was set to null in it. Copy the field into a local before checking it.
• Array elements and collection items. list[0] has the annotation of the element type, regardless of what you stored.

4. The warnings you will see most

WarningsAsErrors=nullable and NoWarn=nullable are shorthands that cover the whole nullable warning set, so you don't need to list IDs.

5. Attributes for what flow analysis can't see

From System.Diagnostics.CodeAnalysis:

public sealed class ConnectionHolder
{
    private SqlConnection? _connection;

    [MemberNotNull(nameof(_connection))]
    private void EnsureOpen()
    {
        _connection ??= new SqlConnection(_connectionString);
    }

    public Task<int> CountAsync()
    {
        EnsureOpen();
        return _connection.ExecuteScalarAsync<int>("select count(*) from Claims"); // no warning
    }
}

6. Framework behaviour that changes when you enable it

This is where "compile-time only" stops being the whole story. Some libraries read the nullable metadata at run time:

The EF Core and MVC rows are why "enable nullable" on an entity or API project is a behaviour change that needs testing, not just a warning clean-up.

7. Sizing and ordering the migration

 Step 1: measure                    Step 2: order by dependency
 --------------------------         -------------------------------------
 dotnet build                        Shared.Kernel  (leaf, no deps)   <-- first
   -p:Nullable=enable                Domain         -> Shared.Kernel
   -flp:"logfile=nrt.log;           Infrastructure -> Domain
         warningsonly"              Api / Workers  -> everything       <-- last
 count CS86xx per project

1. Measure. Build once with -p:Nullable=enable in a CI job, which applies to every project without changing a file, and count CS86xx warnings per project from the log. That number is the size of the job, and the per-project breakdown shows where to start.
2. Order by dependency. Annotate the projects at the bottom of the graph first. If an application is migrated before its libraries, every call into those libraries is oblivious: there are no warnings, and you'll get a second wave of them when the library is annotated.
3. Pick the granularity per project.
   • Small or leaf projects: <Nullable>enable</Nullable> in the project file and fix it in one focused pull request.
   • Large application projects: leave the project at disable, add #nullable enable to each file as it's touched, and require it for new files.
   • Alternative for large projects: set the project to enable and add #nullable disable to the top of every existing file with a script. New files are then nullable by default, and the task becomes "remove the directive from one file at a time". This is often easier to track, because the remaining work is a simple count of files containing #nullable disable.
4. Lock it in. When a project reaches zero, add <WarningsAsErrors>$(WarningsAsErrors);nullable</WarningsAsErrors>, so a new warning fails its build.
5. Finish. Move <Nullable>enable</Nullable> and the warnings-as-errors setting to Directory.Build.props, delete the per-project settings and any leftover directives, and add a check in CI that no #nullable disable remains outside generated code.

8. Legacy code and third-party libraries

• Oblivious APIs. Calling a library compiled without nullable gives no warnings either way. Wrap important ones behind a small annotated adapter, so your code has an accurate contract.
• Generated code (files with an <auto-generated> header or names such as .g.cs and .designer.cs) is treated as nullable disabled unless it contains a #nullable directive, so it doesn't add to the count.
• Two-phase initialisation (new followed by Init()) fights the analysis. Fix it with constructor initialisation or [MemberNotNull], not with !.
• DTOs that are filled by a serialiser: use required members so construction sites must set them, and string? for genuinely optional fields.
• = default! or = null! is acceptable only for members a framework always sets, such as EF Core DbSet<T> properties. Each one is a promise the compiler can't check.

9. Diagnosis

10. Performance and security

• No run-time cost. The annotations are metadata; nothing is inserted into the generated code. Build time is barely affected.
• Security. Nullable is not input validation. An attacker's JSON can still send null; validate request models and keep guard clauses on public APIs.
• The ! operator turns a compile-time warning back into a possible run-time exception. Review each one, and consider an analyser rule or a review checklist that flags new uses.

11. .NET 11 awareness

.NET 11 (due in November 2026, an STS release with 24 months of support, currently in preview and release candidates) doesn't change how nullable reference types work. The migration approach in this answer applies to .NET 10 LTS and .NET 11 alike; check the release notes of each SDK upgrade for new nullable-related warnings or analyser defaults.

12. Try it yourself

1. Create a class library, add <Nullable>enable</Nullable>, and paste in CustomerDirectory from the code example.
2. Remove [NotNullWhen(true)] from TryGet and see CS8602 appear in DisplayName.
3. Add <WarningsAsErrors>nullable</WarningsAsErrors> and confirm the warning now fails the build.
4. Put #nullable disable at the top of the file and see the warnings disappear; replace it with #nullable restore.
5. In an existing solution, run dotnet build -p:Nullable=enable -flp:"logfile=nrt.log;warningsonly" and count warnings per project to size a real migration.
6. In an ASP.NET Core project, add a non-nullable string property to a request model, post JSON without it and note the 400 response. Change it to string? and try again.

<!-- Per project during migration -->
<PropertyGroup>
  <Nullable>enable</Nullable>
  <WarningsAsErrors>$(WarningsAsErrors);nullable</WarningsAsErrors>
</PropertyGroup>

using System.Diagnostics.CodeAnalysis;

namespace Insurance.Customers;

public sealed record Customer(Guid Id, string LegalName, string? PreferredName, string? Abn);

public sealed class CustomerDirectory
{
    private readonly Dictionary<Guid, Customer> _customers = [];

    public void Add(Customer customer)
    {
        ArgumentNullException.ThrowIfNull(customer); // callers without nullable can still pass null
        _customers[customer.Id] = customer;
    }

    public bool TryGet(Guid id, [NotNullWhen(true)] out Customer? customer) =>
        _customers.TryGetValue(id, out customer);

    public string DisplayName(Guid id)
    {
        if (!TryGet(id, out var customer))
        {
            return "Unknown customer";
        }

        // Flow analysis knows customer is not null here
        return customer.PreferredName ?? customer.LegalName;
    }
}

// A file in a large legacy project, migrated as it was touched
#nullable enable

namespace Insurance.Claims;

public sealed class ClaimSummary
{
    public required string ClaimNumber { get; init; }
    public string? AssessorNotes { get; init; }
}