As developers, we’re often tasked with maintaining and modernizing legacy codebases that were written long before some of the best practices of today—such as nullability annotations—were available. While modern C# now supports nullable reference types, enabling us to avoid the dreaded NullReferenceException, introducing this feature to existing, large codebases can be a challenge.

In this article, I’ll share my step-by-step approach for introducing nullability into a legacy .NET and C# project. You’ll learn how to apply nullability in a controlled, incremental manner using project-level settings, scoped annotations, and file/method-level directives, all while maintaining the integrity of your legacy codebase. After all, modernizing your code doesn’t have to be an all-or-nothing endeavor—gradual change is key to a successful transition. Let’s get started!

Why Gradually Introduce Nullability?

Nullability annotations in C# allow us to specify whether a reference type can be null or not. This feature brings more type safety and reliability to your code, reducing the chance of runtime errors caused by null values. But here’s the challenge: introducing nullability into an existing, possibly large codebase and no clear code style, where methods and properties might be riddled with potential nulls, can result in an overwhelming number of compiler warnings. In such cases, it’s easy to give up on nullability altogether, leaving your codebase vulnerable to null reference exceptions. But it doesn’t have to be that way.

To address this, you can take an incremental approach. Rather than trying to make your entire codebase null-safe in one go, you can introduce nullability step by step—starting with new code and gradually refactoring old code. This method minimizes disruption and lets your team handle the transition without being flooded with warnings.

Step 1: Understanding Nullability Annotations in C#

In modern C#, a string is assumed not nullable by default, meaning it cannot contain a null value without a compiler warning. However, you can explicitly declare a string as nullable by using the string? syntax. Here’s an example:

string nonNullableString = "Hello";   // Can't be null, compiler will warn
string? nullableString = null;        // Can be null, no compiler warning

The nullable string? type indicates that the variable may contain a null value, while the non-nullable string enforces that null values are not allowed.

The beauty of nullable reference types is that they make your intent clear, and C#’s compiler will help enforce this through warnings whenever there’s a potential for null dereferencing. And there is a huge list of possible nullable warnings, see Nullable reference types warnings .

Step 2: Enabling Nullability at the Project Level

The most straightforward way to introduce nullability across your entire project is by enabling it globally in your project’s .csproj file or your Directory.Build.props file. You can do this by adding the following property inside your <PropertyGroup> section:

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

This setting will enable nullable reference types for every file in the project, enforcing null-safety checks everywhere. However, this can result in a lot of warnings right away—especially in a large legacy codebase. If you’re not ready to tackle all these warnings at once, you might want to consider a more cautious approach.

A Safer Option: <Nullable>annotations</Nullable>

Instead of enabling nullability across the board from the start, you can take a more cautious approach by using the following property in your .csproj file:

<PropertyGroup>
    <Nullable>annotations</Nullable>
</PropertyGroup>

This option only enables annotations (i.e., you can specify nullable or non-nullable reference types), but it won’t trigger warnings for potential null reference issues in your code. This way, you can begin adding annotations like string? and int? to clarify nullability without worrying about fixing warnings immediately. This is particularly useful for large legacy projects where refactoring everything at once isn’t practical.

Once you feel confident with the annotations you’ve added, you can switch the property to <Nullable>enable</Nullable> and start addressing the warnings generated by the compiler for potential nullability issues. But until then, you can work on adding nullability annotations at your own pace.

Step 3: Using #nullable Directives for Scoped Control

In addition to enabling nullability project-wide, you may also want to control nullability at more granular levels. C# provides the #nullable directive, which allows you to enable or disable nullability checks at the file or method level. This gives you more control over where nullability is enforced, allowing you to gradually introduce null-safety to your codebase.

File-Level Nullability Control

If you want to enable nullability for just a specific file, you can use the #nullable enable directive at the top of the file. This should be the first line in the file, before any namespaces or other code. Here’s an example:

#nullable enable

public class CustomerService
{
    public string? GetCustomerName(int id)
    {
        // Null-safety checks enabled
        return null; // This is allowed because 'string?' is nullable
    }

    public void AddCustomer(Customer customer)
    {
        // Additional code
    }
}

In this case, all code within the file will now adhere to nullability rules. This is useful if you’re working on a new file or refactoring an older one.

Method-Level Nullability Control

If you only want to enable nullability for a specific method rather than an entine file, you can do so using #nullable around the method itself. This can help you focus on null-safety checks for specific methods without affecting the rest of the file. This is particularly helpful when you’re working on large files and want to incrementally refactor certain methods:

public class CustomerService
{
    #nullable enable
    public string? GetCustomerName(int id)
    {
        // Null-safety checks enabled just for this method
    }
    #nullable restore

    public void LegacyMethod(Customer customer)
    {
        // Null-safety checks are restored to project setting
    }
}

This way, you can enable null-safety in smaller, manageable chunks and refactor legacy methods over time. The #nullable restore directive resets the nullability setting to the project level, ensuring that the rest of the file adheres to the global nullability setting.

Step 4: Transitioning to Full Nullability

Once you’ve added nullability annotations throughout your code and feel confident in the accuracy of those annotations, you can switch the project setting from <Nullable>annotations</Nullable> to <Nullable>enable</Nullable>. This change will turn on full null-safety, meaning the compiler will now generate warnings for potential null reference issues.

At this point, your task will be to resolve any warnings by checking for null values, using the null-coalescing operator (??), or adjusting method signatures to ensure null-safety. Gradually fixing these warnings will make your code more robust and reduce the risk of runtime null reference exceptions.

Conclusion

Introducing nullability into a legacy codebase doesn’t have to be a daunting task. By taking an incremental approach—starting with project-level settings like <Nullable>annotations</Nullable>, using #nullable directives for scoped control, and focusing on new or refactored code—you can modernize your codebase while avoiding the flood of warnings that comes with a full-on switch to nullability.

Remember, the goal is to improve the long-term reliability of your code, and with nullability annotations, you’re well on your way to a safer, more maintainable C# project. Take it step by step, and soon, your legacy codebase will be a thing of the past. Modern, null-safe code awaits