Nullable Reference Migration

Nullable Reference Migration

Enable C# nullable reference types (NRTs) in an existing codebase and systematically resolve all warnings. The outcome is a project (or solution) with <Nullable>enable</Nullable>, zero nullable warnings, and accurately annotated public API surfaces — giving both the compiler and consumers reliable nullability information.

When to Use

• Enabling nullable reference types in an existing C# project or solution
• Systematically resolving CS86xx nullable warnings after enabling the feature
• Annotating a library's public API surface so consumers get accurate nullability information
• Upgrading a dependency that has added nullable annotations and new warnings appear
• Analyzing suppressions in a code base that has already enabled NRTs to determine whether they can be removed

When Not to Use

• The project already has <Nullable>enable</Nullable> and zero warnings — the migration is done unless the user wants to re-examine suppressions with a view to removing unnecessary ones (see Step 6)
• The user only wants to suppress warnings without fixing them (recommend against this)
• The code targets C# 7.3 or earlier, which does not support nullable reference types

Inputs

Workflow

🛑 Zero runtime behavior changes. NRT migration is strictly a metadata and annotation exercise. The generated IL must not change — no new branches, no new null checks, no changed control flow, no added or removed method calls. The only acceptable changes are nullable annotations (?), nullable attributes ([NotNullWhen], etc.), ! operators (metadata-only), and #nullable directives. If you discover a missing runtime null guard or a latent bug during migration, do not fix it inline. Instead, offer to insert a // TODO: Consider adding ArgumentNullException.ThrowIfNull(param) comment at the site so the user can address it as a separate change. Never mix behavioral fixes into an annotation commit.

Commit strategy: Commit at each logical boundary — after enabling <Nullable> (Step 2), after fixing dereference warnings (Step 3), after annotating declarations (Step 4), after applying nullable attributes (Step 5), and after cleaning up suppressions (Step 6). This keeps each commit focused and reviewable, and prevents losing work if a later step reveals a design issue that requires rethinking. For file-by-file migrations, commit each file or batch of related files individually.

Step 1: Evaluate readiness

Optional: Run scripts/Get-NullableReadiness.ps1 -Path <project-or-solution> to automate the checks below. The script reports <Nullable>, <LangVersion>, <TargetFramework>, <WarningsAsErrors> settings and counts #nullable disable directives, ! operators, and #pragma warning disable CS86xx suppressions. Use -Json for machine-readable output.

1. Identify how the project is built and tested. Look for build scripts (e.g., build.cmd, build.sh, Makefile), a .sln file, or individual .csproj files. If the repo uses a custom build script, use it instead of dotnet build throughout this workflow.
2. Run dotnet --version to confirm the SDK is installed. Nullable reference types (NRTs) require C# 8.0+ (.NET Core 3.0 / .NET Standard 2.1 or later).
3. Open the .csproj (or Directory.Build.props if properties are set at the repo level) and check the <LangVersion> and <TargetFramework>. If the project multi-targets, note all TFMs.